Returning reference data for asynchronous requests

Reference data is additional data you can include when making asynchronous API requests. After calling an asynchronous API endpoint with your reference data, the polling API can return that data sent in the original asynchronous request.

Here's a diagram that illustrates how this works.

Workflow

  1. Send an asynchronous request to the merge trigger email API endpoint, where my campaign name is "Summer_Campaign".

    POST /rest/asyncApi/v1.3/campaigns/Summer_Campaign/email

    Include the following reference data in the request:

      "referenceData": "sample_ID : 173289739"

    Request body

    {
  "mergeTriggerRecordData": {
    "fieldNames": [
      "EMAIL_ADDRESS_"
    ],
    "mergeTriggerRecords": [
      {
        "fieldValues": [
          "john.doe@oracle.com"
        ],
        "optionalData": [
          {
            "name": "CITY_",
            "value": "Redwood City"
          },
          {
            "name": "MOBILE_NUMBER_",
            "value": "12345678933"
          }
        ]
      },
      {
        "fieldValues": [
          "george.washington@oracle.com"
        ],
        "optionalData": [
          {
            "name": "CITY_",
            "value": "Vancouver"
          },
          {
            "name": "MOBILE_NUMBER_",
            "value": "12345678934"
          }
        ]
      }
    ]
  },
  "referenceData": "sample_ID : 173289739",
  "mergeRule": {
    "insertOnNoMatch": false,
    "updateOnMatch": "NO_UPDATE",
    "matchColumnName1": "EMAIL_ADDRESS_",
    "matchColumnName2": "",
    "matchColumnName3": "",
    "matchOperator": "NONE",
    "optinValue": "I",
    "optoutValue": "O",
    "htmlValue": "H",
    "textValue": "T",
    "rejectRecordIfChannelEmpty": "E",
    "defaultPermissionStatus": "OPTIN"
  }
}

    Response

    If successful, a request ID is returned. In step 2 we will send this request ID to the Polling API to find out the status of the asynchronous request.

    {
  "requestId": "SkxIMG1YOjoxNTIxNzg3ODM0",
  "apiName": "asyncMergeTriggerEmail",
  "status": "REQUEST_ACCEPTED" "links": [
    {
      "rel": "self",
      "href": "/rest/asyncapi/v1.3/campaigns/myEmailCmpn/email",
      "method": "POST"
    },
    {
      "rel": "asyncResponse",
      "href": "/rest/asyncapi/v1.3/requests/SkxIMG1YOjoxNTIxNzg3ODM0",
      "method": "GET"
    }
  ]
}

  2. Send a request to the Polling API to find out the status of the asynchronous request.

    Request

    GET /rest/asyncApi/v1.3/requests/SkxIMG1YOjoxNTIxNzg3ODM0?returnReferenceData=true

    Response

    The response includes information about the asynchronous request and the reference data specified. See Polling API endpoint for more information.

    {
  "response": [
    {
      "success": true,
      "errorMessage": null,
      "recipientId": 7001327
    }
  ],
  "referenceData": "sample_ID:173289739",
  "requestId": "SkxIMG1YOjoxNTIxNzg3ODM0",
  "apiName": "asyncMergeTriggerSms",
  "timeZone": "India Standard Time",
  "requestTime": "2021-05-31T19:15:41.957",
  "requestProcessedTime": "2021-05-31T19:15:48.363",
  "status": "SUCCESS"
}

Returning reference data is supported by the endpoints:

Learn more

Asynchronous API resources