Delete multiple profile list records in a single request

Your client application can delete multiple profile list records in a single batch request by using the query attribute action=delete and by passing a list of IDs.

REQUEST NOTES:

  • For this request to work, your endpoint must include the query attribute action=delete (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 delete in the request body.
  • You can send up to 200 IDs in the request body.

Service URL:

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

Request Method:

POST

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Request Body:

Request attributes:

queryAttribute – Specifies the query attribute to use for locating the records that you want to delete. It can be one of the following values:

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

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 delete. You can pass up to 200 IDs in the request, and each ID must be 500 characters or fewer.

Sample request endpoint and body:

When the server receives the following sample endpoint and request, the system will attempt to delete two records from the profile list MyExampleProfileList for people whose email addresses are recipient1@example.com and recipient2@example.com.

Sample request endpoint:
POST /rest/api/v1.3/lists/MyExampleProfileList/members?action=delete
Sample request body:
{
  "queryAttribute" : "e",
  "ids" : ["recipient1@example.com", "recipient2@example.com"]
}

Sample Response in case of success:

RESPONSE NOTES:

  • When the system successfully deletes records for a given ID (up to 10 records), then the ID is returned in the response.
  • In a successful delete, the system deletes matching records for a given ID, including seed/proof records, up to the maximum of 10 records. If the system finds more than 10 records matching an ID, then the system will delete only the 10 most recent records. To ensure that all records associated with a given ID are deleted, you can re-run the request until all of the requested IDs return a DELETEFAILED: No records found message in the response.
  • Other attributes in the response like mapTemplateName and mergeRule will have default values of null/false.
HTTPS response status code: 200 OK

{
  "recordData":
    {"fieldNames": ["EMAIL_ADDRESS_"],
     "records": [
       ["recipient1@example.com "],
       ["DELETEFAILED: No Records found for EMAIL_ADDRESS_ = recipient2@example.com"]
     ],
     "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=delete",
      "method": "POST" },
    { "rel": "retrieveMultipleListRecipients",
      "href": "/rest/api/v1.3/lists/MyExampleProfileList/members?action=get",
      "method": "POST" },
    { "rel": "mergeListRecipients",
      "href": "/rest/api/v1.3/lists/MyExampleProfileList/members",
      "method": "POST" }
  ]
}

Troubleshooting error responses

Individual list member errors when the HTTPS response is 200 OK

When the system has successfully received a request to delete multiple list members, it will return a successful HTTPS status code of 200 OK. However, the batch delete might have mixed results. The response payload contains an array of messages about the success or failure for each individual member. Some examples of DELETEFAILED messages:

  • When the system could not find any records corresponding to the ID, it returns an error message of DELETEFAILED: No Records found.
  • When an invalid value is sent for the ID, the system returns a DELETEFAILED error for that ID. For example, if test is sent as one of the values in the ids array when the queryAttribute is r, then the system returns the following message for that ID: DELETEFAILED: ERROR: The value test is not valid for an integer field\n\n

Other error responses:

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

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

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

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