Trigger REI event

Triggers a Responsys Event Interface (REI) Event for Profile List, App Channel List, and Web Push recipients. Enables developers to trigger custom events for users across email, print, and mobile app channels to begin Program Orchestration. This feature is only available if it is enabled for your account. To access this feature for existing accounts, please log in to My Oracle Support and create a service request.

Service URL:

/rest/api/v1.3/events/rei/{eventName}

Required Path Parameter:

eventName - Name of the REI event defined in Responsys.

Request Method:

POST

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Triggering a REI Event for Profile List Recipients

Use this endpoint to trigger a Responsys REI event in Responsys for Profile List, App Channel List, and/or Web Push recipients. Enables developers to trigger custom events for users across email, print, and mobile app channels to begin Program Orchestration. You can set up a Program to listen for one or more Responsys Event Interface (REI) events, which can then start a program or be used in a program event switch. This enables marketers to send Email, SMS, Push, and In-App messages to users using the most appropriate channel.

This example demonstrates how to include Profile List recipients. The App Channel List Recipients example is explained below.

Here's an industry-specific example of how this endpoint could be leveraged for Profile List recipients:

  • A retailer might define custom events for a purchase, a new subscriber, or a new customer. After triggering the event, the retailer might want to thank the customer or send a follow-up email.

NOTES:

  • A single request is limited to 200 recipients (includes both Profile List recipients and App Channel List recipients). If you need to trigger a REI event for more than 200 recipients, submit multiple requests to trigger the event.
  • To pass extended/accented characters in optionalData payload, they must be escaped as Unicode characters. For example, the euro currency symbol is escaped as \u20AC, the yen currency symbol is escaped as \u00A5, an umlauted u is escaped as \u00FC, an accented e is escaped as \u00E9, and the like. Otherwise, you may receive an INVALID_REQUEST_CONTENT error.
  • When including app channel list recipients, both deviceId and apiKey are required.
  • Identify Profile List recipients using the parameters: recipientId, emailAddress, customerId, mobileNumber, emailMD5Hash, and emailSHA256Hash. The system processes the attributes in the above-listed order and accepts the first non-null value found.

Example

Trigger a REI event for an item purchase for a customer with the customerId of 8, within the Profile List named My_Profile_List.

Sample Request Body:

Refer to the online REST API reference for an explanation of each parameter.

{
  "reiEvent": {
    "eventNumberDataMapping": null,
    "eventDateDataMapping": null,
    "eventStringDataMapping": null
  },
  "recipientData": [
    {
      "recipient": {
        "customerId": 8,
        "emailAddress": null,
        "listName": {
          "folderName": "FOLDER_NAME",
          "objectName": "My_Profile_List"
        },
        "recipientId": null,
        "mobileNumber": null,
        "emailFormat": "HTML_FORMAT"
      },
      "optionalData": [
        {
          "name": "PRODUCT_NAME",
          "value": "Stonewash Jeans"
        }
      ]
    }
  ]
}

Sample Response in case of success:

[
  {
    "errorMessage": null,
    "success": true,
    "recipientId": 213000901
  }
]

Troubleshooting Failures

If the REI event is incorrect or not found, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Purchase_Event for account:45147:oracleaccount",
  "errorDetails": []
}

Triggering a REI event for App Channel List Recipients

This example demonstrates how to trigger a REI event for App Channel List recipients. This use case supports marketers who want to trigger a REI event for mobile app users within an App Channel List.

Here's an industry-specific example of how this endpoint could be leveraged for App Channel List recipients:

  • A retail company that sells denim jeans might could define a custom event when a user requests to be notified when a jeans style becomes available again at the store. Let's call this a "Back in Stock Notification" event. After the event is triggered, the retailer could then send the user a Back in Stock push notification when the requested item is available.

NOTES:

  • Include App Channel List recipients using the parameters: deviceId and apiKey.
  • When including App Channel List recipients, both deviceId and apiKey are required.
  • A single request is limited to 200 recipients (includes both Profile List recipients and App Channel List recipients). If you need to trigger a REI event for more than 200 recipients, submit multiple requests to trigger the event.
  • To pass extended/accented characters in optionalData payload, they must be escaped as Unicode characters. For example, the euro currency symbol is escaped as \u20AC, the yen currency symbol is escaped as \u00A5, an umlauted u is escaped as \u00FC, an accented e is escaped as \u00E9, and the like. Otherwise, you may receive an INVALID_REQUEST_CONTENT error.

Example

Trigger a REI event because a customer wants to be notified when a pair of jeans is back in stock. The mobile app user's device has a device identifier of 00008020-008D4548007B4F26, within the App Channel list named My_App_Channel_List.

Sample Request Body:

Refer to the online REST API reference for an explanation of each parameter.

{
  "reiEvent": {
    "eventNumberDataMapping": null,
    "eventDateDataMapping": null,
    "eventStringDataMapping": null
  },
  "recipientData": [
    {
      "recipient": {
        "customerId": "",
        "recipientId": "",
        "mobileNumber": "",
        "emailFormat": "",
        "emailAddress": "",
        "emailSHA256Hash": "",
        "emailMD5Hash": "",
        "listName": {
          "folderName": "My_Folder",
          "objectName": "My_App_Channel_List"
        },
        "mobileAppRecipient": {
          "deviceId": "00008020-008D4548007B4F26",
          "apiKey": null
        }
      },
      "optionalData": [
        {
          "name": "PRODUCT_SKU_ID",
          "value": "DDJ9289"
        },
        {
          "name": "PRODUCT_CATEGORY",
          "value": "MEN'S APPAREL"
        },
        {
          "name": "PRODUCT_NAME",
          "value": "Stonewash Jeans"
        }
      ]
    }
  ]
}

Sample Response in case of success:

[
  {
    "errorMessage": "MULTIPLE_RECIPIENTS_FOUND",
    "recipientId": -2,
    "success": false
  },
  {
    "errorMessage": null,
    "recipientId": 8147,
    "success": true
  }
]

Troubleshooting Failures

If the REI event is incorrect or not found, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

If there is no existing app channel list or profile list when deviceId and API key is specified, the response resembles: 

200 OK
[
  {
    "errorMessage": "Push channel List: appChannelList is not valid.",
    "recipientId": -1,
    "success": false
  }
]

If no list name is specified, the response resembles:

{
  "errorMessage": "Push channel List: is not valid.",
  "recipientId": -1,
  "success": false
}

If there is no existing profile list, an empty profile list, or no app channel list with the given profile attributes, the response resembles:

200 OK
[
  {
    "errorMessage": "PROFILE_LIST_NOT_FOUND",
    "recipientId": -1,
    "success": false
  }
]

When neither a profile or app channel list is specified, the response resembles:

200 OK
[
  {
    "errorMessage": "Request should contain data for only one channel.",
    "recipientId": -1,
    "success": false
  }
]

If the event standard variables are not specified in the optional data payload, the response resembles:

200 OK
[
  {
    "errorMessage": " The expected mandatory column RSYS_GEN_FENCE_NAME is missing.",
    "recipientId": 25667,
    "success": false
  }
]

If the optional variable data type is incorrect, the response resembles:

[
  {
    "errorMessage": " Expected TIMESTAMP data type.",
    "recipientId": 25667,
    "success": false
  }
]

If no profile attribute is found in the list, the response resembles: 

200 OK
[
  {
    "errorMessage": "NO_RECIPIENT_FOUND",
    "recipientId": -1,
    "success": false
  }
]

If more than 200 recipients are included in the request, the response resembles:

{
  "type": "",
  "title": "Recipient limit exceeded",
  "errorCode": "RECIPIENT_LIMIT_EXCEEDED",
  "detail": "Recipient limit exceeded, maximum of 200 recipients are allowed per each api call",
  "errorDetails": []
}

Trigger a REI event for Web Push Channel List Recipients

This example demonstrates how to trigger a REI event for Web Push Channel List recipients. This use case supports marketers who want to trigger a REI event for website visitors within a Web Push Channel List.

Here's an industry-specific example of how this endpoint could be leveraged for Web Push Channel List recipients:

  • A retail company that sells denim jeans might could define a custom event when a user requests to be notified when a jeans style becomes available again at the store. Let's call this a "Back in Stock Notification" event. After the event is triggered, the retailer could then send the user a Back in Stock web push notification when the requested item is available.

NOTES:

  • Include Web Push Channel List recipients using the parameters: visitorId and apiKey.
  • A single request is limited to 200 recipients (includes both Profile List recipients and Web Push Channel List recipients). If you need to trigger a REI event for more than 200 recipients, submit multiple requests to trigger the event.
  • To pass extended/accented characters in optionalData payload, they must be escaped as Unicode characters. For example, the euro currency symbol is escaped as \u20AC, the yen currency symbol is escaped as \u00A5, an umlauted u is escaped as \u00FC, an accented e is escaped as \u00E9, and the like. Otherwise, you may receive an INVALID_REQUEST_CONTENT error.

Example

Trigger a REI event because a customer wants to be notified when a pair of jeans is back in stock. The website visitor's browser has a visitorId identifier of 00008020-008D4548007B4F26 and apiKey of 888, within the Web Push Channel list named My_Web_Push_Channel_List.

Sample Request Body:

Refer to the online REST API reference for an explanation of each parameter.

{
  "reiEvent": {
    "eventNumberDataMapping": null,
    "eventDateDataMapping": null,
    "eventStringDataMapping": null
  },
  "recipientData": [
    {
      "recipient": {
        "customerId": "",
        "recipientId": "",
        "mobileNumber": "",
        "emailFormat": "",
        "emailAddress": "",
        "emailSHA256Hash": "",
        "emailMD5Hash": "",
        "listName": {
          "folderName": "My_Folder",
          "objectName": "My_Web_Push_Channel_List"
        },
        "webPushAppRecipient": {
          "visitorId": "dc764f0a-514a-9a10-6da8-8567d573e06f",
          "apiKey": "888"
        }
      },
      "optionalData": [
        {
          "name": "PRODUCT_SKU_ID",
          "value": "DDJ9289"
        },
        {
          "name": "PRODUCT_CATEGORY",
          "value": "MEN'S APPAREL"
        },
        {
          "name": "PRODUCT_NAME",
          "value": "Stonewash Jeans"
        }
      ]
    }
  ]
}

Sample Response in case of success:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

Troubleshooting Failures

If the REI event is incorrect or not found, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

If there is no existing web push channel list, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

If the folder specified is invalid, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

If an invalid visitorId or apiKey is specified, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

When a null visitorId or apiKey is specified, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

If no channels are specified or if more than 1 channel is specified, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

If more than 200 recipients are included in the request, the response resembles:

{
  "type": "",
  "title": "Rei event not found",
  "errorCode": "REI_EVENT_NOT_FOUND",
  "detail": "Unable to retrieve EventDefinition for eventName:Back_In_Stock for account:45147:oracleaccount",
  "errorDetails": []
}

Learn more

Get all custom events for an account

Trigger a custom event