1. REST API for Oracle Responsys Marketing Cloud Service
  2. Tasks
  3. Profile List Recipients

Delete multiple Profile List Recipients

post

/rest/api/v1.3/lists/{listName}/members

Request

Path Parameters
Query Parameters
Body ()
Request Body
Root Schema : Delete List Recipients
Type: object
Title: Delete List Recipients
Show Source
  • ids
    Array of values corresponding to the fieldNames.
  • Query Attribute based on which records will be deleted. Can have the values r(RIID),e(email address),m(mobile number),c(customer id)
Nested Schema : ids
Type: array
Array of values corresponding to the fieldNames.
Show Source
Nested Schema : items
Type: array
Field Values for the recipient in the Profile List
Show Source
Back to Top

Response

Supported Media Types

Default Response

Body ()
Root Schema : Profile List Recipients
Type: object
Title: Profile List Recipients
Show Source
Nested Schema : mergeRule
Type: object
Merge rule used to merge recipient records in a Profile List. Only used during the merge operation.
Show Source
  • 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.
  • Value of incoming preferred email format data. For example, 'H' may represent a preference for HTML formatted email.
  • Indicates what should be done for records where a match is not found (true = insert / false = no insert).
  • 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.
  • 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).
  • Allowed Values: [ "NONE", "AND" ]
    Operator to join match column names
  • Value of incoming opt-in status data that represents an opt-in status. For example, 'I' may represent an opt-in status.
  • Value of incoming opt-out status data that represents an optout status. For example, '0' may represent an opt-out status.
  • 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.
  • Value of incoming preferred email format data. For example, 'T' may represent a preference for Text formatted email.
  • 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
Nested Schema : fieldNames
Type: array
Field Names in 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
Nested Schema : items
Type: array
Field Values for the recipient in the Profile List
Show Source
Back to Top

Examples

Tip:

Need Higher API Call Limits? We have an API on Asynchronous API with the same functionality. Please use the Asynchronous Delete Multiple Profile List Recipients API.

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.

FIELDS DESCRIPTION
Authorization <AUTH_TOKEN>
Content-Type application/json
REQUEST NOTES
  • For this request to work, your endpoint must include the query attribute action=delete.
  • 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, 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 specify c for your queryAttribute, the system expects the ids array to contain the customer ID values for the records you want to delete.

Sample Request

When Responsys 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"] 
}
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, 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, re-run the request until all of the requested IDs return a DELETEFAILED: No records found message in the response.
  • A successful delete will also delete associated PET records.
  • Other attributes in the response like mapTemplateName and mergeRule will have default values of null/false.

Sample Response: Success

The following response shows that the delete succeeded for recipient1@example.com. However, the delete failed for recipient2@example.com because the list did not contain any records with that email address. 

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",
      "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.
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": [] }
Back to Top