Subscribe or unsubscribe people to/from an audience (subscribe)

The subscribe Ortto endpoint of the audience entity is used to update subscription statuses for 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.

HTTP method and request resource


 PUT https://api.ap3api.com/v1/audience/subscribe

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.

To change the Email permission status for a certain audience, provide the subscribed parameter.
To change the SMS permission status, provide the sms_opted_in parameter.

Example Email permission status request body

json
 {
  "audience_id": "61380ac92593ecf2de4fd705",
  "people": [
    {
      "email": "person1@example.com",
      "subscribed": true
    },
    {
      "email": "person2@example.com",
      "subscribed": false
    }
  ],
  "async": true
}

Example SMS permission status request body

json
 {
  "audience_id": "61380ac92593ecf2de9ab302",
  "people": [
    {
      "email": "person3@example.com",
      "sms_opted_in": true
    },
    {
      "email": "person4@example.com",
      "sms_opted_in": false
    }
  ],
  "async": true
}

TIP: You can include both the subscribed and sms_opted_in parameters in the same call.

NOTE:

To modify permissions for a contact in an audience, they must already be a member of that audience. Changes will not apply automatically to contacts who are not a member.
For a contact to appear in the SMS subscribers list for an audience, they need to have opted in to receive SMS messages globally, as well as specifically for that audience.

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	Description
`audience_id`	`string`
`people`	`array` of objects
`subscribed`	`boolean`	It updates the Email permission for the contact within that specific audience. Sending it as `True` will subscribe the contact, while sending it as `False` will unsubscribe.
`sms_opted_in`	`boolean`	It updates the SMS permission for the contact within that specific audience. Sending it as `True` will subscribe the contact, while sending it as `False` will unsubscribe.