Merge Profile Extension Recipients
post
/rest/api/v1.3/lists/{listName}/listExtensions/{petName}/members
Merge recipient data into a Profile Extension Table (PET)
Request
Path Parameters
-
listName: string
List name
-
petName: string
Profile Extension Table (PET) name
Request body
Root Schema : Profile Extension Recipients
Type:
object
Title:
Show Source
Profile Extension Recipients
-
insertOnNoMatch:
boolean
Specifies whether a recipient record should be inserted into the Profile Extension if it does not already exist. Only used during the merge operation.
-
matchColumnName1:
Allowed Values:
[ "RIID", "CUSTOMER_ID", "EMAIL_ADDRESS", "MOBILE_NUMBER", "EMAIL_MD5_HASH", "EMAIL_SHA256_HASH" ]
The first column name to be used to match the recipient record to the Profile Extension records. Only used during the merge operation. -
matchColumnName2(optional):
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). -
recordData:
object recordData
Record data that represents field names and corresponding values for the recipient.
-
updateOnMatch:
Allowed Values:
[ "REPLACE_ALL", "NO_UPDATE" ]
Specifies whether a recipient record should be updated in the Profile Extension if it already exists. Only used during the merge operation.
Nested Schema : recordData
Type:
object
Record data that represents field names and corresponding values for the recipient.
Show Source
-
fieldNames:
array fieldNames
Field names of the Profile List. Must contain contain at least one of the merge key fields from the Profile List.
-
mapTemplateName(optional):
string
The map template in CX Audience 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.
Nested Schema : fieldNames
Type:
array
Field names of the Profile List. Must contain contain at least one of the merge key fields from the Profile List.
Show Source
Nested Schema : records
Type:
array
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
Show Source
-
Array of:
array items
Field values for the recipient in the Profile List
Response
Supported Media Types
- application/json
Default Response
Root Schema : Profile Extension Recipients
Type:
object
Title:
Show Source
Profile Extension Recipients
-
insertOnNoMatch:
boolean
Specifies whether a recipient record should be inserted into the Profile Extension if it does not already exist. Only used during the merge operation.
-
matchColumnName1:
Allowed Values:
[ "RIID", "CUSTOMER_ID", "EMAIL_ADDRESS", "MOBILE_NUMBER", "EMAIL_MD5_HASH", "EMAIL_SHA256_HASH" ]
The first column name to be used to match the recipient record to the Profile Extension records. Only used during the merge operation. -
matchColumnName2(optional):
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). -
recordData:
object recordData
Record data that represents field names and corresponding values for the recipient.
-
updateOnMatch:
Allowed Values:
[ "REPLACE_ALL", "NO_UPDATE" ]
Specifies whether a recipient record should be updated in the Profile Extension if it already exists. Only used during the merge operation.
Nested Schema : recordData
Type:
object
Record data that represents field names and corresponding values for the recipient.
Show Source
-
fieldNames:
array fieldNames
Field names of the Profile List. Must contain contain at least one of the merge key fields from the Profile List.
-
mapTemplateName(optional):
string
The map template in CX Audience 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.
Nested Schema : fieldNames
Type:
array
Field names of the Profile List. Must contain contain at least one of the merge key fields from the Profile List.
Show Source
Nested Schema : records
Type:
array
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
Show Source
-
Array of:
array items
Field values for the recipient in the Profile List
Examples
For an existing profile extension table, new members can be added or data for existing members can be updated.
NOTES:
- The service URL requires the names of both the Profile List and the Profile Extension Table.
- Up to 200 members can be processed in a single request.
- 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 null.
- For a given profile extension table, an array of record data that contain field names and their corresponding field values are specified. The
fieldNames
attribute must 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. 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:
{ "recordData" : { "fieldNames" : ["riid_", "email_address_", "salary"], "records" : [ ["1761408", "foo@bar.com", "10000"], ["98798", "baz@foo.com", "298909"], ["xyz", "bar@baz.com", "wedrfwe"], ["12312", "bar@foo.com", "23423","23423"], ["1761409", "foo@baz.com", "239482734"] ], "mapTemplateName" : null }, "insertOnNoMatch" : true, "updateOnMatch" : "REPLACE_ALL", "matchColumnName1" : "RIID", "matchColumnName2" : "EMAIL_ADDRESS" }
Sample Response: Success
RESPONSE NOTES:
- 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 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.
{ "recordData": { "fieldNames": ["RIID_"], "records": [ ["1761408"], ["MERGEFAILED: Record 1 = RECORD DOES NOT MATCH ANY CONTACTS IN THE LIST DemoNewsLetterList\r\n"], ["MERGEFAILED: Record 2 = ERROR: The value xyz is not valid for an integer field\n\n\r\n"], ["MERGEFAILED: Record 3 = Field Names length, doesn't match with Field Values length\r\n"], ["1761409"] ], "mapTemplateName": null }, "insertOnNoMatch": true, "updateOnMatch": "REPLACE_ALL", "matchColumnName1" : "RIID", "matchColumnName2" : "EMAIL_ADDRESS", "links": [ { "rel": "self", "href": "/rest/api/v1.3/lists/DemoNewsLetterList/listExtensions/DemoNewsLetterPet/members", "method": "POST" }, { "rel": "retrieveProfileExtensionRecipientsRIID", "href": "/rest/api/v1.3/lists/DemoNewsLetterList/listExtensions/DemoNewsLetterPet/members/<riid>", "method": "GET" }, { "rel": "deleteProfileExtensionRecipientsRIID", "href": "/rest/api/v1.3/lists/DemoNewsLetterList/listExtensions/DemoNewsLetterPet/members/<riid>", "method": "DELETE" } ] }
Sample Response: Failure
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "Match Column is null", "errorDetails": [] }