API Custom Tracking Identifier - X-Request-Id

Both synchronous and asynchronous Responsys API calls can accept a custom tracking identifier string in the API call header, and this custom tracking identifier string will persist in header of subsequent responses related to the API call. This allows you to track the response / status of an API call to you a tracking identifier string you generated and provided. In the case of asynchronous calls, the polling response’s header will include the standard “requestId” and the custom tracking identifier string.  

The new header attribute is named, “X-Request-Id”.  Please populate this API header attribute with your own API tracking identifier string.  API responses will include the X-Request-ID header attribute.

Acceptable characters for the “X-Request-Id” are:

  • Letters A-Z (upper case)
  • Letters a-z (lower case)
  • Numbers 0-9 
  • The period (.) character
  • The underscore (_) character
  • The colon (:) character
  • The hyphen (-) character

API calls encountering errors at the network edge or at the Oracle Response load balancing point before reaching the main Responsys API servers will not return the error with the X-Request-Id string.  These early points in data flow do not support the X-Request-Id  in their response.

An example curl command’s header containing X-Request-Id is:

curl --location 'https://<accountSpecificString>-api.responsys.ocs.oraclecloud.com/rest/api/v1.3/campaigns/Campaign_Program/email' \

--header 'Content-Type: application/json' \

--header 'Authorization: *******' \

--header 'X-Request-Id: ACdhej_1234' \

--data-raw '{

Sample synchronous response is below.  Asynchronous response will also include a “requestId” attribute, necessary for async polling lookups.

Sample synchronous response

Sample synchronous response

The Responsys-generated “requestId” response header attribute remains the lookup identifier for any Async Polling requests. The Aysnc Polling API’s response header will include the “requestId” lookup string and the new “X-Request-Id” header attribute, if applicable. More information about Async Polling is available at: https://docs.oracle.com/en/cloud/saas/marketing/responsys-develop/API/REST/Async/asyncApi-v1.3-requests-requestId-get.htm.

Business Benefit:

  • Track the response / status of an API call to you a tracking identifier string you generated and provided.

Steps to enable and configure

You don't need to do anything to enable this feature.

Tips and considerations

Pro Tip: If you wish to associate the custom tracking identifier string with specific contact event data (CED) occurrences, please include the custom tracking string value as a CED Custom Column value. Use the Trigger Message API’s optionalData payload to populate the custom tracking identifier string value into a Campaign Dynamic Variable matching the name of the desired CED Custom Column. More information: CED Custom Columns 

Access requirements

  • The X-Request-Id is available to all API customers starting with the 26C release; there is no need to contact Support for enablement.