Skip to main content
Making Sense of API Response in ContactNow
8x8 Support

Making Sense of API Response in ContactNow

Objective

A lot is said in the API response for each and every API call made, making sense of the response can further assist in identifying any errors or faults in the API call.  This article will assist in understanding the API call to better troubleshoot any issues you may be experiencing with API calls.

Applies To

ContactNow, API (all API calls), EasyContactnow

Response Definition

Prepare an API call and create a listener for the response for further analysis, Ideally, you can make use of third-party applications to run your API calls and this will provide visibility into the Response on the API call.  

postman is a recommended third-party application to use for testing the API calls and it can be downloaded from this link: https://www.getpostman.com/

To read the response from a create/update/delete or read API call please note the available parameters in the response and the following example response below:

Failed json example:

{
    "success":true,
    "account_id":"123456",
    "total":0,
    "bad":1,
    "error":"Invalid queue id [0]"
}
  1. success : (true/false) indicates the response 200 also could be an invalid token or credentials not found on the API endpoint.
  2. account_id : (API Credentials account id "Primary Key").
  3. total : (0) zero indicates no entries to the database.
  4. bad : (1-n) this is the number of failed entries and this will return the error message as seen in point 5 ( it is important to note that the bad=0 will return no error).
  5. error : (Missing Argument/Invalid Argument ) from the error it is seen that the queue id is invalid as there cannot be any queue with the id zero and generally this would indicate that there is a dataset that has no assigned queue.

Failed xml example:

<result>
    <success>1</success>
    <account_id>123456</account_id>
    <total>0</total>
    <bad>1</bad>
    <error>Invalid queue id [0]</error>
</result>
  1. <success> (1/0)  1 = true, 0 = false, indicates the response 200 also could be an invalid token or credentials not found on the API endpoint.
  2. <account_id> (API Credentials account id "Primary Key").
  3. <total> (0) zero indicates no entries to the database.
  4. <bad> (1-n) this is the number of failed entries and this will return the error message as seen in point 5 ( it is important to note that the bad=0 will return no error).
  5. <error> (Missing Argument/Invalid Argument ) from the error it is seen that the queue id is invalid as there cannot be any queue with the id zero and generally this would indicate that there is a dataset that has no assigned queue.

Successful json response:

{
    "success":true,
    "account_id":"123456",
    "total":1,
    "bad":0,
    "key":"123456"
}
  1. success : (true/false) indicates the response 200 also could be an invalid token or credentials not found on the API endpoint.
  2. account_id : (API Credentials account id "Primary Key").
  3. total : (1-n) this is the number of successful entries n is the number of successful entries to the database.
  4. bad : (0) this value of zero will verify that there were no errors.
  5. key : this is the returned primary key entry (id/urn) of the successful insert, update or delete.

Successful xml response:

<result>
    <success>1</success>
    <account_id>123456</account_id>
    <total>1</total>
    <bad>0</bad>
    <key>123456</key>
</result>
  1. <success> (true/false) indicates the response 200 also could be an invalid token or credentials not found on the API endpoint.
  2. <account_id> (API Credentials account id "Primary Key").
  3. <total> (1-n) this is the number of successful entries n is the number of successful entries to the database.
  4. <bad> (0) this value of zero will verify that there were no errors.
  5. <key> this is the returned primary key entry (id/urn) of the successful insert, update or delete.

Common Errors:

The many errors to list and in most cases, the errors are well defined indicating the missing parameters, actions or invalid field, parameter or token. 

  • Invalid Token: use the Validate token API to confirm the token is valid
    • If the API returns success = true and the token is valid, make sure the token was generated on the device that requested it as the security on these tokens are IP locked to the device that created it, sharing tokens and using on Dynamic IP Address systems will not work - to overcome this you can use the parameter "address and provide a list of IP addresses that will use the token.  For more details please refer to the following KCS ContactNow: A Shared API Token On distributed systems. Please note that these are limited to 10 IP's.
    • validating the Token confirms it is valid but won't advise on the 
  • Missing DXI section: Check and confirm payload if XML contains the <dxi></dxi> tags.
    • Using the parameter raw  = 1 

Additional Information

It is possible to have success on an API call with both a bad =n and total = 0, this indicates that the API call was to the correct URL/endpoint and the token was valid or the correct platform.  Further to this the total = 0 indicates that there were no entries made for some reason and would reflect a bad state at 1. The bad = 1 will always return the error which will define the cause of the no entry to the database.  

If the bad state is set to 1 and there is no visible error returned it is important to note the format used and switching between xml and json will at times get the error to present the valid mess

 

  • Was this article helpful?