Polling API endpoint

Use the Polling API to find out the status of up to 10 asynchronous requests.

Note: The Asynchronous API is generally available for all Responsys customers.

Workflow

Leveraging the asynchronous APIs and the polling API typically resembles this workflow:

  1. A client sends a request to a Responsys asynchronous API endpoint. The asynchronous API endpoint responds to the client with a request ID.

  2. A client sends the request ID to the Polling API endpoint to find out the status of the request. The Polling API responds with the status of the asynchronous request.

Here's a diagram illustrating how the polling API works:

Optionally you can include reference data in the request to the asynchronous endpoint. The Polling API can then return the reference data specified in the asynchronous request. Refer to Returning reference data for asynchronous requests for more information.

Request details

  • You can specify up to 10 request IDs per request.
  • Client applications must poll for responses within 24 hours after the initial API request was processed. A daily job on the server deletes responses that are more than one day old.
  • The system throttles the Polling API. You can get the throttling limit of the API by using the Get Throttling Limits REST API request.
  • Status returned by the polling API is only about completion of the merge and submitting to the personalization queue. The results do not reflect the final campaign send status. In other words, it’s possible that the campaign send could fail due to personalization errors even if the result indicates success.
Request Method Service URL
GET

/rest/asyncApi/v1.3/requests/{requestId}

Request Headers

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Path Parameters

  • requestId : Unique identifier of the API request. Obtain this value from the successful response to your asynchronous request. You can specify up to 10 request IDs per request, combined using the "&" operator.
Query Parameters
Request Body Required Properties N/A

Example Requests

Retrieve the polling results for the request IDs dzBPSUZGOjoxNTIxNDQ0NjUz and dzBBGFFDcvuTNDTYNVDr.

/rest/asyncApi/v1.3/requests/dzBPSUZGOjoxNTIxNDQ0NjUz&dzBBGFFDcvuTNDTYNVDr

Retrieve the polling results for the request ID dzBPSUZGOjoxNTIxNDQ0NjUz and display the reference data for the asynchronous request.

/rest/asyncApi/v1.3/requests/dzBPSUZGOjoxNTIxNDQ0NjUz?returnReferenceData=true

Response Notes:

The response HTTP STATUS code is always 200 (Ok), unless there is a system error (500 Internal Server Error). See Common error responses for the Polling API for details about the error responses.

For a successful response, the response body properties are as follows:

  • responseMessage: object that contains either the merge results for the recipients sent in the async Merge Trigger request, a message property with the in-progress message "PROCESSING_REQUEST", or the standard REST API error JSON. See the Handling errors section for more details about error responses.
  • requestId: the unique identifier that was returned by the original asynchronous API request.
  • apiName: Property that contains the name of the request API.
  • timeZone: The time zone of the Responsys account performing the request.
  • requestTime: Timestamp of when the request was submitted.
  • requestProcessedTime: Timestamp when the request was processed.
  • status: Status of the async API request.

Sample Responses - Successful

Merge successful. In this scenario, two Async Merge Trigger Email requests were successfully processed, and a response code of 200 OK was received.

"requestData": [
  {
    "responseMessage": [
      {
        "recipientId": 16005207,
        "success": true,
        "errorMessage": ""
      },
      {
        "recipientId": 21001007,
        "success": true,
        "errorMessage": ""
      }
    ],
    "requestId": "dzBPSUZGOjoxNTIxNDQ0NjUz",
    "apiName": "asyncMergeTriggerEmail",
    "timeZone": "Brasilia Time",
    "requestTime": "2021-01-13 06:36:25.774",
    "requestProcessedTime": "2021-01-13 06:36:27",
    "status": "SUCCESS"
  },
  {
    "responseMessage": [
      {
        "recipientId": 81006008,
        "success": true,
        "errorMessage": ""
      },
      {
        "recipientId": 81006009,
        "success": true,
        "errorMessage": ""
      }
    ],
    "requestId": "dzBBGFFDcvuTNDTYNVDr",
    "apiName": "asyncMergeTriggerEmail",
    "timeZone": "Brasilia Time",
    "requestTime": "2021-01-13 06:16:03.221",
    "requestProcessedTime": "2021-01-13 06:26:01",
    "status": "SUCCESS"
  }
]

Merge successful with returnReferenceData enabled. This scenario is the same as above, with displaying the reference data of the original request.

{
  "response": [
    {
      "success": true,
      "errorMessage": null,
      "recipientId": 7001327
    },
    {
      "success": false,
      "errorMessage": "FAILURE: Record 1 = Bad Email Format\r\n",
      "recipientId": 0
    }
  ],
  "referenceData": "{\"referenceKey1\":\"referenceValue1\"}",
  "requestId": "ZXFBNWRGOjoxNjIyNDY4NzQx",
  "apiName": "asyncMergeTriggerSms",
  "timeZone": "India Standard Time",
  "requestTime": "2021-05-31T19:15:41.957",
  "requestProcessedTime": "2021-05-31T19:15:48.363",
  "status": "SUCCESS"
}

Mixed results for the merge. In this scenario, the request succeeded for the first recipient, but failed for the second recipient.

{
  "responseMessage": [
    {
      "recipientId": 16005207,
      "success": true,
      "errorMessage": ""
    },
    {
      "recipientId": 0,
      "success": false,
      "errorMessage": "FAILURE: Record 1 = INVALID_PARAMETER:matchColumnName1 is not found in fieldNames or corresponding value is null or empty\r\n"
    }
  ],
  "requestId": "MWxNQXJDOjoxNTIwOTQ4ODI1",
  "apiName": "asyncMergeTriggerSms",
  "timeZone": "Brasilia Time",
  "requestTime": "2018-03-13 06:47:05.435",
  "requestProcessedTime": "2018-03-13 06:47:06",
  "status": "SUCCESS"
}

Processing request. In this scenario, an async request is still being processed, and a response code of 200 OK was received.

{ 
    "responseMessage": { 
        "message": "PROCESSING_REQUEST" 
    }, 
    "requestId": "SkxIMG1YOjoxNTIxNzg3ODM1", 
    "apiName": "",
    "timeZone": "Brasilia Time",
    "requestTime": "2018-03-14 04:49:57.0", 
    "requestProcessedTime": "", 
    "status": "IN_PROGRESS" 
}

Sample Response - Failure:

The following example shows a sample error response – in this case, the responseMessage object contains the error JSON, which tells us that the campaign was invalid. A response code of 200 OK is shown, however, because the polling request itself completed successfully.

{
    "responseMessage": {
        "errorCode": "CAMPAIGN_IS_INVALID",
        "detail": "An error has occurred and the system is unable to process your request at this time. Please contact Responsys Support for further assistance.",
        "type": "",
        "title": "Not a valid campaign",
        "errorDetails": "[]"
    },
    "requestId": "dzBPSUZGOjoxNTIxNDQ0NjUz",
    "apiName": "asyncMergeTriggerEmail",
    "timeZone": "Brasilia Time",
    "requestTime": "2018-03-19 13:00:53.013",
    "requestProcessedTime": "2018-03-19 13:00:55",
    "status": "ERROR"
}

Learn more

Common error responses for the Polling API

Asynchronous API resources