1. REST API for Oracle Responsys Marketing Cloud Service
  2. Tasks
  3. Events

Trigger REI Event

post

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

Triggers a REI Event for Profile List, App Channel List, and Web Push recipients. Enables developers to trigger REI 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.

Request

Path Parameters
Body ()
Request Body
Root Schema : Trigger Rei Event
Type: object
Title: Trigger Rei Event
Show Source
Nested Schema : recipientData
Type: array
Array of Recipients with Optional Data
Show Source
Nested Schema : reiEvent
Type: object
reiEvent.
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : optionalData
Type: array
Array of optional data containing name value pairs.
Show Source
Nested Schema : recipient
Type: object
Information about the Recipient.
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : listName
Type: object
Profile List to which the Recipient belongs.
Show Source
Nested Schema : mobileAppRecipient
Type: object
Data for push channel recipient
Show Source
Nested Schema : webPushAppRecipient
Type: object
Data for web push channel recipient
Show Source
Back to Top

Response

Supported Media Types

Default Response

Body ()
Root Schema : Trigger Custom Event Response
Type: array
Title: Trigger Custom Event Response
Array of Recipient Results.
Show Source
Nested Schema : items
Type: object
Response for individual recipient.
Show Source
Back to Top

Examples

Trigger 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 and the Web Push Channel List Recipients example are 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.

A successful request requires the following headers:

FIELDS DESCRIPTION
Authorization AUTH_TOKEN
Accept application/json

Sample Request Body:

{
  "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 Success Response:

[
  {
    "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": []
}

Trigger 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.

A successful request requires the following headers:

FIELDS DESCRIPTION
Authorization AUTH_TOKEN
Accept application/json

Sample Request Body:

{
  "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:

[
  {
    "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.

A successful request requires the following headers:

FIELDS DESCRIPTION
Authorization AUTH_TOKEN
Accept application/json

Sample Request Body:

{
  "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:

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

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:

[
  {
    "errorMessage": "Web Push channel List: MY_WEB_PUSH_CHANNEL_LIST not valid.",
    "success": false,
    "recipientId": -1
  }
]

If the folder specified is invalid, the response resembles:

[
  {
    "errorMessage": "Web Push channel List: CONTACT_WEBPUSH does not exist in folder: MY_FOLDER",
    "success": false,
    "recipientId": -1
  }
]

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

[
  {
    "errorMessage": "visitorId: a5941d50-51d5-7a53-bbd3c apiKey: ABEgFh-jS1FHww1C67vzONIKo is not valid.",
    "success": false,
    "recipientId": -1
  }
]

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

[
  {
    "errorMessage": "visitorId: visitor_Id_value apiKey: API_Key_value is not valid.",
    "success": false,
    "recipientId": -1
  }
]

[
  {
    "errorMessage": "visitorId and apiKey can not be null or empty for web push recipient.",
    "success": false,
    "recipientId": -1
  }
]

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

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

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": []
}
Back to Top