Retrieve Multiple Profile Extension Recipients
/rest/api/v1.3/lists/{listName}/listExtensions/{petName}/members
The request method for this API is
POST
, because the query parameters are passed in the request body. The ids array contains the identifier values for the recipients. Values passed in the ids
array must correspond to the queryAttribute
specified. For example, if you specify e
for your queryAttribute
, the system expects the ids array to contain email address values for the records you want to retrieve. By specifying field names in the fieldList
, you can determine which fields are returned for recipients.Request
-
listName: string
The name of the parent profile list for the profile extension table.
-
petName: string
The name of the profile extension table to retrieve recipients.
-
action: string
Required. Must have the value get. For example:
?action=get
object
bulk profile Extension Recipients
-
fieldList(optional):
array fieldList
field names list
-
ids(optional):
array ids
email ids list
-
queryAttribute(optional):
string
query attribute
Response
- application/json
Default Response
object
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.
-
matchColumn:
Allowed Values:
[ "RIID", "CUSTOMER_ID", "EMAIL_ADDRESS", "MOBILE_NUMBER", "EMAIL_MD5_HASH", "EMAIL_SHA256_HASH" ]
The column name to be used to match the recipient record to the Profile Extension records. Only used during the merge operation. -
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.
object
-
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 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
-
Array of:
array items
Field values for the recipient in the Profile List
Examples
Retrieve profile extension recipients.
- For this request, your request 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 at maximum 500 characters.
- Values passed in the
ids
array must correspond to the query attribute. For example, if you specifyc
for yourqueryAttribute
, the system expects the ids array to contain the customer ID values for the records you want to retrieve. - To retrieve values of all columns, you can specify only one field with value set to
all
. (If you have a column namedall
, you should use two or more specific column names to avoid getting all columns). - For
fieldList
, each field name must be 150 characters or fewer.
A successful request requires the following headers:
FIELDS | DESCRIPTION |
---|---|
Authorization | <AUTH_TOKEN> |
Content-Type | application/json |
Sample Request:
For the Profile List named "MyExampleList", associated with the Profile Extension Table named "MyPetName", retrieve recipients by email address. Where the email addresses to retrieve are recipient1@example.com and recipient2@example.com. For each record, retrieve the fields "RIID_", "EMAIL_ADDRESS_", "CUSTOMER_ID_", "POSTAL_STREET_2_", "POSTAL_STREET_1_", "CITY_", "STATE_", "POSTAL_CODE_", and "COUNTRY_".
POST /rest/api/v1.3/lists/MyExampleList/listExtensions/MyPETName/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" ] }
Sample Response: Success
- 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.
- For each match, 10 records maximum will be returned. For example, if there are 11 records for a given email address, only the first 10 records will be returned and the next result is paginated.
- If the system cannot find a record for a given ID, it will not return 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.
{ "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 }, "insertOnNoMatch": false, "updateOnMatch": null, "matchColumn": null, "links": [ { "rel": "self", "href": "/rest/api/v1.3/lists/MyExampleList /listExtensions/MyPETName/members?action=get", "method": "POST" }, { "rel": "deleteMultipleProfileExtensionMembers", "href": "/rest/api/v1.3/lists/MyExampleList /listExtensions/MyPETName/members", "method": "POST" }, { "rel": "mergeProfileExtensionRecipients", "href": "/rest/api/v1.3/lists/MyExampleList /listExtensions/MyPETName/members", "method": "POST" } ] }
Error Response Examples
This section lists the common error responses when retrieving multiple profile extension recipients.
HTTPS status code 400 Bad Request
Invalid field names: Requests fail if the fields provided do not exist in the table. The error resembles:
{ "type": "", "title": "Invalid field name", "errorCode": "INVALID_FIELD_NAME", "detail": "Column(s) [EMAIL_ADDRESS_, CUSTOMER_ID_] not found in the table", "errorDetails": [] }
Invalid query attribute: Requests fail if the query attribute value is invalid. The error resembles:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "Query Attribute Must be either r, e, c, m, e_md5, or e_sha256.", "errorDetails": [] }
QueryColumn is null OR empty: Requests fail if the queryAttribute
is missing. The error resembles:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "QueryColumn is null OR empty", "errorDetails": [] }
Id to retrieve is empty: Requests fail if no values were provided in the ids array. The error resembles:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "IdToRetrieve is empty", "errorDetails": [] }
Field list is empty: Requests fail if no values were provided in the fieldList
array. The error resembles:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "fieldList is empty", "errorDetails": [] }
Record limit exceeded: Requests fail if more than 5 query ID values are sent. The error resembles:
{ "type": "", "title": "Record limit exceeded", "errorCode": "RECORD_LIMIT_EXCEEDED", "detail": "Record limit exceeded, maximum of 5 records are allowed per each api call", "errorDetails": [] }
ID to retrieve exceeds limit of 500 characters: Requests fail if any ID exceeds the 500 character limit. The error resembles:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "IdToRetrieve exceeds limit of 500 characters.", "errorDetails": [] }
Field list exceeds limit of 150 characters: Requests fail if one or more field names in the fieldList array is more than 150 characters. The error resembles:
{ "type": "", "title": "Invalid request parameters", "errorCode": "INVALID_PARAMETER", "detail": "FieldList exceeds limit of 150 characters.", "errorDetails": [] }