Merge List Recipients
/rest/api/v1.3/lists/{listName}/members
Request
-
listName: string
List Name
object
Profile List Recipients
-
mergeRule:
object mergeRule
Merge rule used to merge recipient records in a Profile List. Only used during the merge operation.
-
recordData:
object recordData
Record data that represents Field Names and corresponding values for the recipient.
object
-
defaultPermissionStatus(optional):
string
Allowed Values:
[ "OPTIN", "OPTOUT" ]
This value must be specified as either OPTIN or OPTOUT and would be applied to all of the records contained in the API call. If this value is not explicitly specified, then it is set to OPTOUT. -
htmlValue(optional):
string
Value of incoming preferred email format data. For example, 'H' may represent a preference for HTML formatted email.
-
insertOnNoMatch(optional):
boolean
Indicates what should be done for records where a match is not found (true = insert / false = no insert).
-
matchColumnName1(optional):
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. -
matchColumnName2(optional):
string
Allowed Values:
[ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
Second match column for determining whether an insert or update should occur. (optional). -
matchOperator(optional):
string
Allowed Values:
[ "NONE", "AND" ]
Operator to join match column names -
optinValue(optional):
string
Value of incoming opt-in status data that represents an opt-in status. For example, 'I' may represent an opt-in status.
-
optoutValue(optional):
string
Value of incoming opt-out status data that represents an optout status. For example, '0' may represent an opt-out status.
-
rejectRecordIfChannelEmpty(optional):
string
String containing comma-separated channel codes that if specified will result in record rejection when the channel address field is null. Channel codes are 'E' (Email), 'M' (Mobile), 'P' (Postal Code). For example 'E,M' would indicate that a record that has a null for Email or Mobile Number value should be rejected. This parameter can also be set to null or to an empty string, which will cause the validation to not be performed for any channel, except if the matchColumnName1 parameter is set to EMAIL_ADDRESS_ or MOBILE_NUMBER_. When matchColumnName1 is set to EMAIL_ADDRESS_ or MOBILE_NUMBER_, then the null or empty string setting is effectively ignored for that channel.
-
textValue(optional):
string
Value of incoming preferred email format data. For example, 'T' may represent a preference for Text formatted email.
-
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
-
mapTemplateName(optional):
string
The Map Template in Responsys that can be used to map Field Names of the Profile List to Column Names.
-
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
Profile List Recipients
-
mergeRule:
object mergeRule
Merge rule used to merge recipient records in a Profile List. Only used during the merge operation.
-
recordData:
object recordData
Record data that represents Field Names and corresponding values for the recipient.
object
-
defaultPermissionStatus(optional):
string
Allowed Values:
[ "OPTIN", "OPTOUT" ]
This value must be specified as either OPTIN or OPTOUT and would be applied to all of the records contained in the API call. If this value is not explicitly specified, then it is set to OPTOUT. -
htmlValue(optional):
string
Value of incoming preferred email format data. For example, 'H' may represent a preference for HTML formatted email.
-
insertOnNoMatch(optional):
boolean
Indicates what should be done for records where a match is not found (true = insert / false = no insert).
-
matchColumnName1(optional):
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. -
matchColumnName2(optional):
string
Allowed Values:
[ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
Second match column for determining whether an insert or update should occur. (optional). -
matchOperator(optional):
string
Allowed Values:
[ "NONE", "AND" ]
Operator to join match column names -
optinValue(optional):
string
Value of incoming opt-in status data that represents an opt-in status. For example, 'I' may represent an opt-in status.
-
optoutValue(optional):
string
Value of incoming opt-out status data that represents an optout status. For example, '0' may represent an opt-out status.
-
rejectRecordIfChannelEmpty(optional):
string
String containing comma-separated channel codes that if specified will result in record rejection when the channel address field is null. Channel codes are 'E' (Email), 'M' (Mobile), 'P' (Postal Code). For example 'E,M' would indicate that a record that has a null for Email or Mobile Number value should be rejected. This parameter can also be set to null or to an empty string, which will cause the validation to not be performed for any channel, except if the matchColumnName1 parameter is set to EMAIL_ADDRESS_ or MOBILE_NUMBER_. When matchColumnName1 is set to EMAIL_ADDRESS_ or MOBILE_NUMBER_, then the null or empty string setting is effectively ignored for that channel.
-
textValue(optional):
string
Value of incoming preferred email format data. For example, 'T' may represent a preference for Text formatted email.
-
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
-
mapTemplateName(optional):
string
The Map Template in Responsys that can be used to map Field Names of the Profile List to Column Names.
-
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
Tip:
Need Higher API Call Limits? We have an API on Asynchronous API with the same functionality. Please use the Asynchronous Merge Profile List Members API.New members can be added to an existing profile list and existing members in a profile list can be updated. For a given list in a specific folder, an array of record data that contain field names and their corresponding field values are specified. Up to 200 members can be handled per a single request.
FIELDS | DESCRIPTION |
---|---|
Authorization | <AUTH_TOKEN> |
Content-Type | application/json |
Sample Request
- The
matchColumnName
attributes can have the following possible values:RIID_ CUSTOMER_ID_ EMAIL_ADDRESS_ MOBILE_NUMBER_ EMAIL_MD5_HASH_ EMAIL_SHA256_HASH_
- Limitations for
matchColumnName
attributes:A combination of either of the
HASH_
keys or a combination ofEMAIL_ADDRESS_
with either of theHASH_
keys cannot be given asmatchColumnNames
at the same time.When either of the
HASH_
keys exists as a match column, then only updates are possible, thus the corresponding value ininsertOnNoMatch
should be set to false when using these columns asmatchColumnNames
.
{ "recordData": { "fieldNames": [ "riid_", "mobile_number_", "email_address_" ], "records": [ [ "4094326", "9845349498", "ab.cd@gmail.com" ], [ "4094327", "9844444444", "unknown@oracle.com" ], [ "4094328", "9844444666", "abc@gmail.com" ], [ "ssdcf", "9844444444", "xyz" ] ], "mapTemplateName": null }, "mergeRule": { "htmlValue": "H", "optinValue": "I", "textValue": "T", "insertOnNoMatch": true, "updateOnMatch": "REPLACE_ALL", "matchColumnName1": "RIID_", "matchColumnName2": null, "matchOperator": "NONE", "optoutValue": "O", "rejectRecordIfChannelEmpty": null, "defaultPermissionStatus": "OPTIN" } }
Sample Response: Success
- 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. - The order of records in the response matches the order of records specified in the request payload. Furthermore, other attributes in the response, such as like
mapTemplateName
andmergeRule
, will mirror the valid values specified in the request payload or default to null/false in case of invalid values.
{ "recordData": { "fieldNames": [ "RIID_" ], "records": [ [ "4094326" ], [ "4094327" ], [ "4094328" ], [ "MERGEFAILED: Record 3 = INVALID_PARAMETER: The value ssdcf is not valid for an integer field\n\n\r\n" ] ], "mapTemplateName": null }, "mergeRule": { "textValue": "T", "insertOnNoMatch": true, "updateOnMatch": "REPLACE_ALL", "matchOperator": "NONE", "matchColumnName3": null, "matchColumnName1": "RIID_", "matchColumnName2": null, "optinValue": "I", "optoutValue": "O", "rejectRecordIfChannelEmpty": null, "htmlValue": "H", "defaultPermissionStatus": "OPTIN" }, "links": [ { "rel": "self", "href": "/rest/api/v1.3/lists/DemoNewsLetterList/members", "method": "POST" }, { "rel": "retrieveListRecipientsRIID", "href": "/rest/api/v1.3/lists/DemoNewsLetterList/members/<riid>, "method": "GET" } ] }
Sample Response: Failure
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "matchColumnName1 in ListMergeRule is null or empty", "errorDetails": [ ] }