Add or Update RIID in the Organizational Scope Mapping
/rest/api/v1.3/lists/{listName}/orgListExtensions/members
Request
-
listName: string
List name
object
Merge Org List Recipients
-
insertOnNoMatch(optional):
boolean
Indicates what should be done for records where a match is not found (true = insert / false = no insert).
-
matchColumnName1:
string
Allowed Values:
[ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
First match column for determining whether an insert or update should occur. -
recordData:
object recordData
Record data that represents field names and corresponding values for the recipient.
-
updateOnMatch(optional):
string
Allowed Values:
[ "REPLACE_ALL", "NO_UPDATE" ]
Controls how the existing record should be updated.
object
-
fieldNames:
array fieldNames
Field names in the Profile List
-
records:
array records
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
array
-
Array of:
array items
Field Values for the recipient in the Profile List
Response
- application/json
Default Response
object
Merge Org List Recipients
-
insertOnNoMatch(optional):
boolean
Indicates what should be done for records where a match is not found (true = insert / false = no insert).
-
matchColumnName1:
string
Allowed Values:
[ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
First match column for determining whether an insert or update should occur. -
recordData:
object recordData
Record data that represents field names and corresponding values for the recipient.
-
updateOnMatch(optional):
string
Allowed Values:
[ "REPLACE_ALL", "NO_UPDATE" ]
Controls how the existing record should be updated.
object
-
fieldNames:
array fieldNames
Field names in the Profile List
-
records:
array records
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
array
-
Array of:
array items
Field Values for the recipient in the Profile List
Examples
Add or Update RIID-to-Audience Scope Code Mapping Data for Profile List members
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.
- 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. (That is, it is not a PET that is accessible to Responsys users directly.)
- Up to 200 members can be processed in a single request.
- 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).- The
fieldNames
attribute must also contain at least one of the merge key fields from the profile list (for example,RIID_
,EMAIL_ADDRESS_
,CUSTOMER_ID_
), otherwise the request will result in a MERGEFAILED error.
- 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. - Up to two match columns can be used for merging records into a profile extension table. If only one match column is specified, the other match column can be set to an empty value (for example,
"matchColumnName2" : "")
. matchColumnName1
andmatchColumnName2
values must not contain the usual trailing underscore for the enumerated values. For example,RIID
works butRIID_
results in an INVALID_PARAMETER error ("Match Column is null").- Limitation for match columns: New records will not be inserted for
insertOnNoMatch
if amatchColumnName
is eitherEMAIL_MD5_HASH
orEMAIL_SHA256_HASH
, even if matching records are not found in the table. The email hash attributes (EMAIL_MD5_HASH
orEMAIL_SHA256_HASH
) are only used for updating existing records.
A successful request requires the following headers:
FIELDS | DESCRIPTION |
---|---|
Authorization | <AUTH_TOKEN> |
Content-Type | application/json |
Sample Request Body:
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 error shown in the Sample Response body.
{ "recordData" : { "fieldNames" : ["AUDIENCE_SCOPE_CODE", "REC_STATUS_", "EMAIL_ADDRESS_"], "records" : [ ["IN", "A", "4as0dsa@tesasdsat.com"], ["IN", "F", "ab.cd@gmail.com"] ], "mapTemplateName" : null }, "insertOnNoMatch" : true, "updateOnMatch" : "REPLACE_ALL", "matchColumnName1" : "EMAIL_ADDRESS" "matchColumnName2" : "" }
Sample Response: Success
- 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 thefieldNames
attribute and the correspondingRIID_
values for the records in therecords
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
andmatchColumn
will mirror the valid values specified in the request payload or default to null/false in case of invalid values.
In the sample response below, the first record was merged successfully, but the second record failed to merge because it had the incorrect REC_STATUS_
value. Also, 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"} ] }
Sample Response: Failure
In the following sample response body, the request attempted to send more than 200 recipients in a single request.
{ "type": "", "title": "Record limit exceeded", "errorCode": "RECORD_LIMIT_EXCEEDED", "detail": "Record limit exceeded, maximum of 200 records are allowed per each api call", "errorDetails": [] }
The following table shows common errors when this type of 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>. |