Add or update RIID in the organizational scope mapping

Important: This API only applies if Targeting by Organization is enabled for your account.

This API allows you to update the system mapping table that maps a Profile List member’s RIID to the Organization Scope appropriate for that member. This ensures that Responsys only sends messages to those recipients belonging to a campaign’s target audience of selected organization units.

REQUEST NOTES:

The service URL only requires the names of the Profile List. The mapping table that stores the information is an internal system table that is not accessible through the application UI.
Up to 200 members can be processed in a single request.
Up to two match columns can be used for merging records into the table. If only one match column is specified, the other match column can be set to an empty value (for example, "matchColumnName2" : "").
Mandatory fieldNames attributes:
- AUDIENCE_SCOPE_CODE: This is the audience scope code, as defined in the organization table. It is a code that defines the org to which the customer belongs. You can view the organization tree when logged in to Responsys by selecting Account | Organization Management.
- REC_STATUS_: This is the status of the record. Valid values are "A" (Active) or "D" (Deleted).
  - To add a mapping record: Specify "A" for REC_STATUS_. The system adds the mapping to the table. Note that each RIID (customer) can have more than one audience scope coding.
  - To mark a record as deleted: Specify "D" for REC_STATUS_. The system will treat this record as deleted.
- Must include a system column name to be used for the merge, and it should also be used for matchColumnName1.
matchColumnName1 and matchColumnName2 values must not contain the usual trailing underscore for the enumerated values. For example, RIID works but RIID_ results in an INVALID_PARAMETER error (“Match Column is null”). matchColumnName values can be as follows: RIID, CUSTOMER_ID, EMAIL_ADDRESS, MOBILE_NUMBER, EMAIL_MD5_HASH, or EMAIL_SHA256_HASH
Limitation for match columns: New records will not be inserted for insertOnNoMatch if a matchColumnName is either EMAIL_MD5_HASH or EMAIL_SHA256_HASH, even if matching records are not found in the table. The email hash attributes (EMAIL_MD5_HASH or EMAIL_SHA256_HASH) are only used for updating existing records.

Please see the definition of merge rule parameters provided in Definitions of Rule Parameters for Merging Members into a Profile List.

Service URL:

/rest/api/v1.3/lists/{listName}/orgListExtensions/members

Request Method:

PUT

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Request Body Example:

In the example below, both records have an AUDIENCE_SCOPE_CODE of "IN". The first example is a valid "Active" (add) entry, but the second record illustrates an incorrect REC_STATUS_, "F", which will result in the INVALID_PARAMETER error shown in the Sample Response Body.

{
  "recordData" : {
    "fieldNames" : ["AUDIENCE_SCOPE_CODE", "REC_STATUS_", "EMAIL_ADDRESS_"],
    "records" : [
      ["IN", "A", "4as0dsa@yahoo.com"],
      ["IN", "F", "abcd@gmail.com"]
    ],
    "mapTemplateName" : null
  },
  "insertOnNoMatch" : true,
  "updateOnMatch" : "REPLACE_ALL",
  "matchColumnName1" : "EMAIL_ADDRESS"
  "matchColumnName2" : ""
}

Response:

For each record, if the Audience Scope Code is valid, then system updates the table. The system updates the table with the Profile List member’s RIID, Audience Scope Code, and status details (REC_STATUS_).

Irrespective of what field names were used to perform the merge, the response will always contain only RIID_ in the fieldNames attribute and the corresponding RIID_ values for the records in the records attribute.
In case merge failed for a record, the RIID_ of the record is not present in the response. Instead, an error message starting with MERGEFAILED: is returned. Client developers can look for the string MERGEFAILED: in the response for a particular row to determine whether that recipient was merged successfully or not.

Reasons for MERGEFAILED include an invalid REC_STATUS_ value, Audience Scope Code provided does not exist, and Audience Scope Code provided does not exist AND the member is not found in the Profile List.
The order of records in the response matches the order of records specified in the request payload. Furthermore, other attributes in the response like mapTemplateName, insertOnNoMatch, updateOnMatch, and matchColumn will mirror the valid values specified in the request payload or default to null/false in case of invalid values.

Sample response – successful merge for the first record, failed merge for the second record:

In this example, we sent two records (per the previous request example) to merge to the mapping table. The request was sent to the endpoint using the Profile List “contacts_list” as the {list_name} value. The list name is used in the endpoints provided in the links array in the response.

{
  "recordData": 
    { "fieldNames": [ "RIID_" ],
      "records": [ 
        [ "8381" ],
        [ "MERGEFAILED: Invalid REC_STATUS_ provided - should be 'A' or 'D' " ]
  ], 
    "mapTemplateName": null },

  "insertOnNoMatch": true,
  "updateOnMatch": "REPLACE_ALL",
  "matchColumn": "EMAIL_ADDRESS",

  "links": [
    { "rel": "self", "href": "/rest/api/v1.3/lists/contacts_list/orgListExtensions/members", "method": "PUT" },
    { "rel": "retrieveProfileExtensionRecipientsRIID", "href": "/rest/api/v1.3/lists/ contacts_list/listExtensions//members/<riid>", "method": "GET"}
  ]
}

ERROR NOTES

The sample on the next page shows the format for the error response body.

Common errors returned when the request fails:

Error Code	Detail
RECORD_LIMIT_EXCEEDED	Record limit exceeded, maximum of 200 records are allowed per each API call
INVALID_PARAMETER	Match column name is not in `fieldNames`
INVALID_PARAMETER	Match column name is empty or is not a system column
INVALID_PARAMETER	`fieldNames` should have `REC_STATUS_` and `AUDIENCE_SCOPE`
PROFILE_EXTENSION_NOT_FOUND	No Organization Profile Extensions Found For List <`list_name`>.

Sample Response in case of failure - request body attempted to send more than 200 recipients:

{
   "type": "",
   "title": "Record limit exceeded",
   "errorCode": "RECORD_LIMIT_EXCEEDED",
   "detail": "Record limit exceeded, maximum of 200 records are allowed per each api call",
   "errorDetails": []
}