Retrieve people’s subscription statuses (subscriptions)

The subscriptions Ortto endpoint of the person entity is used to retrieve subscription statuses from one or more person records in Ortto’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:

HTTP method and request resource

POST https://api.ap3api.com/v1/person/subscriptions

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

  • X-Api-Key: CUSTOM-PRIVATE-API-KEY

  • Content-Type: application/json

Request body

The request body consists of a JSON object whose valid elements are listed in the table below.

The following JSON object is an example of field and object data that Ortto can recognize to get data from one or more person records in your Ortto account’s CDP.

Example subscription status request body from Ortto’s CDP
{
  "people": [
    {
      "email": "chris@example.com"
    }
  ]
}

Valid request body elements

The following table lists all valid request body elements (arrays, objects, or fields), which are available to this endpoint.

Element Type Required Description

people

array of objects

Required

The people array consists of an array of objects, where each object contains data associated with the person whose subscription status you wish to retrieve.

people must contain at least one of the optional objects: person_id, email, or external_id.

The API will defer to person_id first (if set), then email, then external_id. You will receive an error if none of the strings are provided.

email

string

Optional (at least one string required)

The email address of the person whose subscription statuses you wish to retrieve.

person_id

string

Optional (at least one string required)

A string identifying the person by their unique ID number.

external_id

string

Optional (at least one string required)

A string identifying the person by their external ID number.

Response payload

The response payload consists of a JSON object whose elements are listed in the table below.

The following JSON object is an example of people’s data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example subscription status response payload from Ortto’s CDP
{
  "people": [
    {
      "person_status": "merged",
      "person_id": "00624536230993474f078a00",
      "subscriptions": [
        {
          "audience_id": "625f7213a914327aa1999b43",
          "audience_name": "Weekly updates",
          "member_from": "2022-04-20T02:38:11Z",
          "subscribed": true,
          "subscribed_from": "2022-04-20T02:38:11Z",
          "sms_opted_in": false
        },
        {
          "audience_id": "6241681069639ee210f8a298",
          "audience_name": "Subscribers",
          "member_from": "2022-03-31T05:03:31Z",
          "subscribed": true,
          "subscribed_from": "2022-03-31T05:03:31Z",
          "sms_opted_in": false
        },
        {
          "audience_id": "6241681069639ee210f8a29a",
          "audience_name": "Engaged subscribers",
          "member_from": "2022-03-31T12:56:14Z",
          "subscribed": true,
          "subscribed_from": "2022-03-31T12:56:15Z",
          "sms_opted_in": false
        }
      ],
      "email_permissions": true,
      "sms_permissions": false
    }
  ]
}

Response payload elements

The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.

Element Type Description

people

array of objects

The people array consists of an array of objects, where each object contains data associated with the person specified in the response. Each of these objects can contain:

* person_status and person_id objects

* subscriptions arrays

* email_permissions and sms_permissions booleans.

person_status

string

Identifies the person’s data as having been merged into your customer data platform (CDP).

person_id

string

A string identifying the person by their unique ID number.

subscriptions

array of objects

An array of fields identifying the audiences the person is a member of, and their email and SMS subscription status for those audiences.

audience_id

string

The unique identification number for the audience.

audience_name

string

The name of the audience in your Ortto account (note, this is not the public audience name).

member_from

string

The date and time the person became a member of the audience. Format is ISO 8601.

subscribed

boolean

If true, the person is subscribed to the audience. Otherwise, false.

subscribed_from

string

The date and time the person became a subscriber of the audience. Format is ISO 8601.

unsubscribed_from

string

The date and time the person became unsubscribed from the audience. Format is ISO 8601.

sms_opted_in

boolean

If true, the person is opted-in to SMS to the audience. Otherwise, false.

sms_opted_out_from

string

The date and time the person became opted-out from SMS for the audience. Format is ISO 8601.

email_permissions

boolean

If true, the person is subscribed to all email. Otherwise, false.

sms-permissions

boolean

If true, the person is opted-in to all SMS. Otherwise, false.