Retrieve multiple profile list records in a single request

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.

REQUEST NOTES:

• For this request to work, your endpoint must include the query attribute action=get (as shown in the Service URL below).
• Note that the request method for this API is POST, because you pass the query attribute and the IDs to retrieve in the request body.
• You can send up to 200 IDs in the request body.
• To retrieve values of all columns, you can specify only one field with value set to ‘all’. (If you have a column called ‘all’, you should use two or more specific column names to avoid getting all of the columns).

Service URL:

/rest/api/v1.3/lists/{listName}/members?action=get

Request Method:

POST

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Request Body:

Request attributes:

queryAttribute – Specifies the query attribute that you are sending. It can be one of the following values:

• r – RIID
• e – Email address
• c – Customer ID
• m – Mobile number

fieldList – Comma-separated list of the fields you want from the records you are retrieving. Set this value to all to get all Profile List fields for each record returned. Each field name must be 150 characters or fewer.

ids – Array containing the identifier values corresponding to the query attribute. For example, if you specify c, the system expects the ids array to contain the customer ID values for the records you want to retrieve. You can pass up to 200 IDs in the request, and each ID must be 500 characters or fewer.

Sample request endpoint and body:

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"]
}

Sample Response in case of success:

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 and mergeRule will have default values of null/false.

HTTPS response status code: 200 OK

{
  "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?action=delete",
      "method": "POST" },
    { "rel": "mergeListRecipients",
      "href": "/rest/api/v1.3/lists/MyExampleProfileList/members",
      "method": "POST" }
  ]
}

Troubleshooting error responses

The system returns error responses when:

No records found for all of the IDs: 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": []
}
			

List not found: The system could not find the Profile List specified in the request endpoint. A 404 not found error is returned with the following error response body:

{
  "type": "", 
  "title": "List not found", 
  "errorCode": "LIST_NOT_FOUND", 
  "detail": "MyOtherExampleProfileList List Not Found", 
  "errorDetails": []
}
			

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": []
}
			

queryAttribute is null or empty: A 400 bad request error is returned with the following error response body (queryAttribute is called "QueryColumn" in the error message):

{
  "type": "", 
  "title": "Invalid request parameters", 
  "errorCode": "INVALID_PARAMETER", 
  "detail": "QueryColumn is null OR empty", 
  "errorDetails": []
}
			

fieldList array 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": "fieldList is empty", 
  "errorDetails": []
}
			

No values 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": "error detail", 
  "errorDetails": []
}
			

One or more ids array value 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": []
}
			

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 queryAttribute value is not valid.: A 400 bad request error is returned with the following error response body:

{
  "type": "", 
  "title": "Invalid request parameters", 
  "errorCode": "INVALID_PARAMETER", 
  "detail": "Query Attribute Must be either r, e, c or m", 
  "errorDetails": []
}
			

Record limit exceeded: 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": []
}
}

API limit exceed: 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": []
}