Prerequisites:

1. Authentication details - Till ID and password for basic auth and valid access token for OAuth.
2. Appropriate access group access.
3. API details
4. Any API testing tool such as Postman, Swagger, etc.

Step-by-step instructions:

1. Determine the necessary API for your first request. Refer API Index for a list of our APIs.

2. Select an API tool. Below are some suggested tools along with guidance on their usage:

   1. Postman
   2. 'Try it' from ReadMe

3. Build a URL for the API call. For more information, refer to the API URL structure documentation.

4. Select the type of API call. For information on API call types, refer to the API HTTP methods documentation.

5. Enter the authentication details. You can use Basic auth or OAuth. For more information refer to the Basic Auth and OAuth documentation.

   🚧

   Ensure that your till has the appropriate access group permissions. For example, if your till lacks write permissions for Customer resources, you will be unable to add a customer using those till credentials. For more information, refer to the access group. documentation.

6. Run the request.

7. Evaluate the response.

   • For information on API response codes, refer API status codes documentation.
     Once you have successfully made a request, make sure to check the response to ensure it is correct and as expected.

Getting started with Postman

Prerequisites:

1. Authentication details - Till ID and password for basic auth and valid access token for OAuth.
2. Appropriate access group access.
3. API endpoint details.

Step by step instructions

1. Open Postman and from the home page, click New .

2. Select the Authorization tab and from the Type drop-down, select the authentication type. For basic authentication, select Basic auth and for authenticating using an access token, select No Auth.

Basic Auth
To authenticate using basic auth, enter the Till ID in Username and in the Password field, enter the till password in MD5 format. For more information on these, refer Basic authentication documentation.

Authenticating using access token
To authenticate using an access token, generate the token, select Headers, and enter the Key X-CAP-API-OAUTH-TOKEN, then input the token in the Value field. The Content-Type and accept key fields are auto-generated.

🚧

Warning

Ensure that your till has the appropriate access group permissions. For example, if your till lacks write permissions for Customer resources, you will be unable to add a customer using those till credentials. For more information, refer to the access group. documentation.

3. From the method drop-down, select the method type.

4. In the URL text box, enter the API URL. Refer API Index for a list of our APIs and refer to the API URL structure documentation for information on building a URL.

5. (a) For POST and PUT methods, select Body tab > raw and enter the body parameters.

(b)For GET / DELETE methods, select the Parameters tab and enter the query parameters.

5. Click Send. The response is displayed on the interface.

{
    "loyaltyInfo": {
        "loyaltyType": "loyalty"
    },
    "profiles": [
        {
            "firstName": "Jose",
            "lastName": "Jones",
            "identifiers": [
                {
                    "type": "mobile",
                    "value": "988001234"
                },
                {
                    "type" : "email",
                    "value" : "[email protected]"
                }
            ],
            "source": "INSTORE"
        }
    ]
}

//REQUEST
https://eucrm.cc.capillarytech.com/v2/customers/lookup?source=INSTORE&identifierName=mobile&identifierValue=9449489999

//RESPONSE

{
  "entity": 552695692,
  "warnings": []
}

// BODY

{
  "profiles": [
    {
      "firstName": "Tom",
      "lastName": "Sawyer",
      "fields": {
        "gender": "Male",
        "city": "Bangalore"
      },
      "identifiers": [
        {
          "type": "mobile",
          "value": 919111111111
        },
        {
          "type": "email",
          "value": "[email protected]"
        },
        {
          "type": "wechat",
          "value": "wc_2"
        }
      ],
      "commChannels": [
        {
          "type": "email",
          "value": "[email protected]",
          "primary": "true",
          "verified": "false",
          "meta": {
            "residence": true
          }
        },
        {
          "type": "wechat",
          "value": "wc_2",
          "primary": "true",
          "verified": "true",
          "meta": {
            "residence": true
          }
        },
        {
          "type": "mobilePush",
          "value": "abcd12343434",
          "primary": true,
          "verified": true,
          "meta": {
            "lastViewedDate": "2019-10-25"
          }
        }
      ],
      "source": "WECHAT",
      "accountId": "1234"
    }
  ],
  "loyaltyInfo": {
    "loyaltyType": "loyalty"
  },
  "extendedFields": {
    "gender": "MALE",
    "city": "Bangalore"
  },
  "loyaltyProgramEnrollments": [
    {
      "programId": 1016,
      "tierNumber": 234,
      "loyaltyPoints": 75,
      "tierExpiryDate": "2022-02-11T16:36:17+05:30",
      "pointsExpiryDate": "2022-02-11T16:36:17+05:30"
    }
  ]
}



//RESPONSE

{
  "createdId": 162116213,
  "warnings": [],
  "sideEffects": [
    {
      "awardedPoints": 25,
      "type": "points"
    }
  ]
}

//REQUEST

https://eucrm.cc.capillarytech.com/v2/userGroup2/1234/leave?source=INSTORE&accountId=321&identifierName=mobile&identifierValue=1234566789

//RESPONSE

{
  "warnings": [],
  "errors": [],
  "success": true
}

You can click Save as example to save the response for future reference.

Using Postman for Bulk API requests

You can configure automation for repetitive API requests in Postman. This approach allows the automatic execution of numerous API requests and is useful when there is no specific BULK API available for your requirements.

👍

Note

This method is primarily intended for cleanup activities during migrations or other rare circumstances. It is not recommended for all APIs and should not be considered a replacement for BULK APIs.

To create a Bulk API request using POSTMAN, perform the following:

1. Click on the Add icon.

2. Click Blank collection. A new collection is created.

3. Click the three-dot menu, and click Add a request.

3. Enter the API information such as HTTP method, API endpoint, and authorization.

3. In the Body, enter the body parameters. For the dynamic values, define the value using a variable. The variables should be defined in the format {{variablename}}. For example, see the below sample body of a transaction ADD API where "mobilenumber", "billNumber", and "billAmount" are the variables:

6. Define the values for the variables in a CSV file and save it. Make sure that the names of the variables defined and those in the CSV files are the same. For example, if the variables are "mobilenumber", "billNumber", and "billAmount", define the values for those in the CSV file.

7. Save the request.
8. Click the three-dot menu, and click Run collection.
9. Click Select File and upload the CSV file which contains the variables and the values for the dynamic parameters.
10. Select the Persist response for a session checkbox to view the response in the results.
11. Click Run.
12. To view the responses, click on the Iterations.

Getting started wih 'Try it' on ReadMe

This section will walk you through the steps to make your API request from the ReadMe portal.

Prerequisites

1. Basic Auth credentials - till ID and MD5 encoded password. For more information refer to the Basic authentication documentation.
2. Host URL

Step by step instructions

1. Navigate to the Capillary developer documentation portal.
2. Select the API you want to run. For example, Add a user group.
3. Enter the body parameters (for POST and PUT) or query parameters (for GET and DELETE) information.

NOTE: Parameters marked required are mandatory.
For POST or PUT calls, if the body parameters fields are not available, enter the API payload in the RAW_BODY in the appropriate JSON format.

4. From the CURL section, select CURL from the drop-down. To view available request CURL examples, click the REQUEST drop-down and select the CURLs.

To clear an example, select Clear example.

5. In the URL, enter the HOST URL.

6. If applicable, Enter the appropriate header values. The headers section is visible only if the API supports any additional headers.

7. In the Authorization section, enter the till ID and password in MD5 format.
   NOTE: This is not required if you have entered the access token in the X-CAP-API-OAUTH-TOKEN header.

8. Click Try it! . The Response section displays the response.

To view other sample responses, click the RESPONSE drop-down. The drop-down displays the available example responses.

Testing API using ReadMe Try it

Viewing example in ReadMe

👍

Congratulations! You have successfully sent your first Capillary API call!