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:

request resource and method,
valid parameters, headers, and request body values, as well as
the response payload.

HTTP method and request resource


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

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

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

json
 {
  "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

json
 {
  "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`.