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

Retrieve Multiple Profile Extension Recipients

post

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

This endpoint is used to retrieve multiple profile extension recipients in an existing profile extension table. By supplying an ID for a recipient (for example email address) you can retrieve up to 200 recipients in a single request.
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

Path Parameters
Query Parameters
Body ()
Request body
Root Schema : bulk profile Extension Recipients
Type: object
Title: bulk profile Extension Recipients
Show Source
Nested Schema : fieldList
Type: array
field names list
Show Source
Nested Schema : ids
Type: array
email ids list
Show Source
Back to Top

Response

Supported Media Types

Default Response

Bulk Retrieve Profile Extension Recipients
Body ()
Root Schema : Profile Extension Recipients
Type: object
Title: Profile Extension Recipients
Show Source
  • Specifies whether a recipient record should be inserted into the Profile Extension if it does not already exist. Only used during the merge operation.
  • 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
    Record data that represents field names and corresponding values for the recipient.
  • 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.
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 of the Profile List. Must contain contain at least one of the merge key fields from 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

Retrieve profile extension recipients.

NOTES:
  • 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 specify c for your queryAttribute, 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 named all, 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

RESPONSE NOTES:
  • 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": []
}
Back to Top