Retrieve multiple Profile List Recipients
post
/rest/api/v1.3/lists/{listName}/members
Request
Path Parameters
-
listName: string
List Name
Query Parameters
-
action: string
**action** should have the value **get**(action=get).
Request Body
Root Schema : Retrieve List Recipients
Type:
object
Title:
Show Source
Retrieve List Recipients
-
fieldList:
array fieldList
Array of field names to be retrieved
-
ids:
array ids
Array of values corresponding to the fieldNames.
-
queryAttribute:
string
Query Attribute based on which records will be retrieved. Can have the values r(RIID),e(email address),m(mobile number),c(customer id)
Nested Schema : fieldList
Type:
array
Array of field names to be retrieved
Show Source
-
Array of:
array items
Field Name in the Profile List
Nested Schema : ids
Type:
array
Array of values corresponding to the fieldNames.
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 List Recipients
Type:
object
Title:
Show Source
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.
Nested Schema : mergeRule
Type:
object
Merge rule used to merge recipient records in a Profile List. Only used during the merge operation.
Show Source
-
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.
Nested Schema : recordData
Type:
object
Record data that represents Field Names and corresponding values for the recipient.
Show Source
-
fieldNames:
array fieldNames
Field Names in 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 : 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
Your client application can retrieve multiple profile list records in a single batch request by using the query attribute action=get
and by passing a list of IDs.
FIELDS | DESCRIPTION |
---|---|
Authorization | <AUTH_TOKEN> |
Content-Type | application/json |
REQUEST NOTES
- For this request to work, your endpoint must include the query attribute
action=get
. - Note that the request method for this API is
POST
, because you pass the query parameters in the request body. - You can send up to 200 IDs in the request body, and each ID must be 500 characters or fewer.
- Values passed in the
ids
array must correspond to the query attribute. For example, if you specifyc
for yourqueryAttribute
, the system expects theids
array to contain the customer ID values for the records you want to delete. - To retrieve values of all columns, you can specify only one field with value set to
all
. (If you have a column calledall
, you should use two or more specific column names to avoid getting all of the columns). - For
fieldList
, each field name must be 150 characters or fewer.
Sample Request
The following sample endpoint and request are requesting two records from the profile list
MyExampleProfileList
for people whose email addresses are
recipient1@example.com
and
recipient2@example.com
. The
fieldList
lists the fields that will be returned for each recipient in the response.
Sample request endpoint: POST /rest/api/v1.3/lists/MyExampleProfileList/members?action=get Sample request body: { "queryAttribute" : "e", "fieldList" : ["RIID_","EMAIL_ADDRESS_","CUSTOMER_ID_","POSTAL_STREET_2_","POSTAL_STREET_1_","CITY_","STATE_","POSTAL_CODE_","COUNTRY_"], "ids" : ["recipient1@example.com", "recipient2@example.com"] }
RESPONSE NOTES
- For each match, 10 records maximum will be returned. For example, if there are 11 records for a given mobile number, only the most recent 10 records will be returned.
- If the system cannot find a record for a given ID, it will not return either a result or an error message. The system only returns an error message if it cannot find any records for all of the IDs passed.
- Other attributes in the response like
mapTemplateName
andmergeRule
will have default values of null/false.
Sample Response in case of success:
{ "recordData": { "fieldNames": ["RIID_","EMAIL_ADDRESS_","CUSTOMER_ID_","POSTAL_STREET_2_","POSTAL_STREET_1_","CITY_","STATE_","POSTAL_CODE_","COUNTRY_"], "records": [ [ "63036487","recipient1@example.com","481",null,"1427 CLAY ST","San Francisco","CA",null,"USA" ], [ "63027514","recipient2@example.com","818",null,"1993 O'Shaughnessy Blvd","San Francisco","CA","94131","USA" ] ], "mapTemplateName": null }, "mergeRule": { "textValue": null, "htmlValue": null, "optinValue": null, "insertOnNoMatch": false, "updateOnMatch": null, "matchColumnName1": null, "matchColumnName2": null, "matchOperator": null, "optoutValue": null, "rejectRecordIfChannelEmpty": null, "defaultPermissionStatus": null, "matchColumnName3": null }, "links": [ { "rel": "self", "href": "/rest/api/v1.3/lists/MyExampleProfileList/members?action=get", "method": "POST" }, { "rel": "deleteMultipleListRecipients", "href": "/rest/api/v1.3/lists/MyExampleProfileList/members", "method": "POST" }, { "rel": "mergeListRecipients", "href": "/rest/api/v1.3/lists/MyExampleProfileList/members", "method": "POST" } ] }
Troubleshooting error responses
No records found for all of the IDs passed in the request payload. For example, if you sent 30 IDs and no records were found for any of them, you would receive this error. A
404 not found error is returned with the following error response body:
{ "type": "", "title": "Record not found", "errorCode": "RECORD_NOT_FOUND", "detail": "No records found in the list for given ids", "errorDetails": [] }
An ID type does not match the field type. A
400 bad request error is returned with the following error response body:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "The value recipient1@example.com is not valid for an integer field", "errorDetails": [] }
The
queryAttribute
(called
"QueryColumn" in the error message) is null or empty. A
400 bad request error is returned with the following error response body:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "QueryColumn is null OR empty", "errorDetails": [] }
No values were provided in the
ids
array. A
400 bad request error is returned with the following error response body:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "IdToRetrieve is empty", "errorDetails": [] }
One or more of the values sent in the
ids
array is more than 500 characters. For example, if you used email address as the
queryAttribute
and one of the email addresses was more than 500 characters, then this error would occur. A
400 bad request error is returned with the following error response body:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "IdToRetrieve exceeds limit of 500 characters.", "errorDetails": [] }
The
fieldList
array is empty. A
400 bad request error is returned with the following error response body:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "fieldList is empty", "errorDetails": [] }
One or more of the field names sent in the fieldList array is more than 150 characters. A
400 bad request error is returned with the following error response body:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "FieldList exceeds limit of 150 characters.", "errorDetails": [] }
The
fieldList
array contains one or more invalid field names. A
400 bad request error is returned with the following error response body (where the invalid field names sent are returned in the square brackets). In the following example,
RIID
is flagged as invalid because the field name in Responsys is
RIID_
:
{ "type": "", "title": "Invalid field name", "errorCode": "INVALID_FIELD_NAME", "detail": "Column(s) [RIID] not found in the list", "errorDetails": [] }
The 200-record limit is exceeded (that is, more than 200 query ID values are sent). A
400 bad request error is returned with the following error response body:
{ "type": "", "title": "Record limit exceeded", "errorCode": "RECORD_LIMIT_EXCEEDED", "detail": "Record limit exceeded, maximum of 200 records are allowed per each api call", "errorDetails": [] }
When the client application exceeds the throttling limit for this API, a
401 Unauthorized error is returned with the following error response body:
{ "type": "", "title": "", "errorCode": "API_LIMIT_EXCEEDED", "detail": "", "errorDetails": [] }