REST API for Oracle Responsys Marketing Cloud Service

Retrieve List Recipients Count using query attribute

get

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

Retrieves a count of Profile List Recipients that match the query attributes. If no query attributes are specified, retrieves total count of the profile list recipients.

Request

Path Parameters

listName: string

List Name

Query Parameters

id: string

ID corresponding to the query attribute
qa: string
Query Attribute. Can be one of:
- 'r' (RIID_)
- 'e' (EMAIL_ADDRESS_)
- 'c' (CUSTOMER_ID_)
- 'm' (MOBILE_NUMBER_)
- 'e_md5' (EMAIL_MD5_HASH_)
- 'e_sha256' (EMAIL_SHA256_HASH_)

Response

Supported Media Types

application/json

Default Response

Root Schema : Retrieve List Recipients Count

Type: object

Title: Retrieve List Recipients Count

Show Source

count: integer

Count of list recipients that matches the query attribute passed or total count of list recipients when no query attributes are passed
links: object links

link URLs that represents next link table APIs

{
    "title":"Retrieve List Recipients Count",
    "type":"object",
    "properties":{
        "count":{
            "description":"Count of list recipients that matches the query attribute passed or total count of list recipients when no query attributes are passed",
            "type":"integer"
        },
        "links":{
            "type":"object",
            "description":"link URLs that represents next link table APIs",
            "properties":{
                "rel":{
                    "type":"string",
                    "description":"link table API name"
                },
                "href":{
                    "type":"string",
                    "description":"URI of link table API"
                },
                "method":{
                    "type":"string",
                    "description":"request method type"
                }
            }
        }
    },
    "required":[
        "count",
        "links"
    ]
}

Nested Schema : links

Type: object

link URLs that represents next link table APIs

Show Source

href(optional): string

URI of link table API
method(optional): string

request method type
rel(optional): string

link table API name

{
    "type":"object",
    "description":"link URLs that represents next link table APIs",
    "properties":{
        "rel":{
            "type":"string",
            "description":"link table API name"
        },
        "href":{
            "type":"string",
            "description":"URI of link table API"
        },
        "method":{
            "type":"string",
            "description":"request method type"
        }
    }
}

Examples

You can retrieve a count of existing members of a profile list with or without query parameters. If no query parameters are specified, the total count of profile list recipients will be returned. Otherwise, use query parameters to narrow the search.

FIELDS	DESCRIPTION
Authorization	<AUTH_TOKEN>

FIELDS	DESCRIPTION
id	ID corresponding to the query attribute
qa	Can be either `r` (RIID), `e` (EMAIL_ADDRESS), `c` (CUSTOMER_ID), `m` (MOBILE_NUMBER), `e_md5` (EMAIL_MD5_HASH_consisting of 32 characters), or `e_sha256` (EMAIL_SHA256_HASH_ consisting of 64 characters). If an `e_md5` and `e_sha256` are both provided in the same request, the `e_sha256` is ignored.

Sample Request URL:

Retrieve all profile list recipients within the DemoNewsLetterList profile list with the email address example@oracle.com.

  /rest/api/v1.3/lists/DemoNewsLetterList/members/count?qa=e&id=example@oracle.com

Sample Response: Success

The count indicates there are 3 profile list recipients in this list with the email address example@oracle.com.

{
  "count": 3,
  "links": [
    {
      "rel": "self",
      "href": "/rest/api/v1.3/lists/DemoNewsLetterList/members/count?qa=e&id=example@oracle.com.com",
      "method": "GET"
    },
    {
      "rel": "mergeListRecipients",
      "href": "/rest/api/v1.3/lists/DemoNewsLetterList/members",
      "method": "POST"
    },
    {
      "rel": "retrieveListRecipients",
      "href": "/rest/api/v1.3/lists/DemoNewsLetterList/members?&qa=e&id=example@oracle.com.com",
      "method": "GET"
    }
  ]
}

Sample Request URL:

Retrieve a count of all profile list recipients within the DemoNewsLetterList profile list.

  /rest/api/v1.3/lists/DemoNewsLetterList/members/count

Sample Response: Success

The count indicates there are 100 profle list recipients in the profile list DemoNewsLetterList.

{
  "count": 100,
  "links": [
    {
      "rel": "self",
      "href": "/rest/api/v1.3/lists/DemoNewsLetterList/members/count",
      "method": "GET"
    },
    {
      "rel": "mergeListRecipients",
      "href": "/rest/api/v1.3/lists/DemoNewsLetterList/members",
      "method": "POST"
    }
  ]
}

Example Response Failures

404 Not Found Errors

No records found in the given list: Requests fail when no query attribute is specified and the count of profile list recipients in the list is 0. The error resembles:

{
  "type": "",
  "title": "Record not found",
  "errorCode": "RECORD_NOT_FOUND",
  "detail": "No records found in the given List",
  "errorDetails": []
}

No records found for the given id: Requests fail when no records are found in the list for the id specified. The error resembles:

{
  "type": "",
  "title": "Record not found",
  "errorCode": "RECORD_NOT_FOUND",
  "detail": "No records found in the list for given id",
  "errorDetails": []
}

List not found: Requests fail if the specified profile list is not found. The error resembles:

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

400 Bad Request Errors

Invalid value for the specified id data type: Requests fail when an invalid id value is provided. For example, if a string value is provided for riid, when the value should be an integer. The error resembles:

{
  "type": "",
  "title": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETER",
  "detail": "The value example@oracle.com is not valid for an integer field",
  "errorDetails": []
}

Invalid e_SHA256 is specified: Requests fail when the query attribute specified is e_sha256, and an invalid email SHA256 hash id is provided. Email SHA256 hashes are 64 characters. The error resembles:

{
  "type": "",
  "title": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETER",
  "detail": "The value [ 12345 ] is not a valid SHA256 Hash value.",
  "errorDetails": []
}

Invalid e_md5 is specified: Requests fail when the query attribute specified is e_md5, and an invalid email md5 hash id is provided. Email md5 hashes are 32 characters. The error resembles:

{
  "type": "",
  "title": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETER",
  "detail": "The value [ 12345678 ] is not a valid MD5 Hash value.",
  "errorDetails": []
}

Invalid query attribute: Requests fail if an invalid query attribute is specified. Query Attribute must be either r, e, c, m, e_md5 or e_sha256. 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": []
}

Too many query attributes specified: Requests fail if more than one query attribute is specified. The error resembles:

{
  "type": "",
  "title": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETER",
  "detail": "This query supports only one id",
  "errorDetails": []
}

A query attribute was not specified: Requests fail if no query attribute is specified. The error resembles:

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

No identifier specified: Requests fail if no id is specified. The error resembles:

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

Invalid profile list name length: Requests fail if the length of the profile list name exceeds 100 characters. The error resembles:

{
  "type": "",
  "title": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETER",
  "detail": "Max Length of listName allowed: 100",
  "errorDetails": []
}

Profile list name contains invalid characters: Requests fail if the profile list name contains invalid characters. The error resembles:

{
  "type": "",
  "title": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETER",
  "detail": "Invalid characters in the List Name",
  "errorDetails": []
}