Configuring people’s subscription permissions

Learn how to use the Ortto API to configure email and SMS subscription permissions of people in your Ortto account’s customer data platform (CDP) through the examples on this page.

Requests to change people’s email and SMS subscription permissions in your Ortto CDP are submitted as a single POST method call to the following URL:


 https://api.ap3api.com/v1/person/merge

which is the same endpoint used to create and update people.

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/).

Each copyable code example on this page is annotated with callouts along with associated explanations.

Initial states

When people are initially created within the CDP, then by default:

the email subscription permission is set to true (i.e. subscribed), and
the SMS subscription permission is set to false (i.e. unsubscribed).

When submitting requests to create or update people in the CDP via the Ortto API, then at least ensure you have the consent of these people to subscribe them to email messages sent from Ortto.

Configure the email subscription permission

cURL example

cURL example request to set a person’s email subscription permission to false in the Ortto CDP

shell
 curl --request POST 'https://api.ap3api.com/v1/person/merge' \ <1>
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \ <2>
     --header 'Content-Type: application/json' \
     --data-raw '{
        "people": [
          { <3>
            "fields": {
              "str::email": "chris@example.com",
              "bol::p": false, <4>
              "str::u-ctx": "Unsubscribed from email using a custom context message" <5> 
            }
          }
        ]
      }'

1	The API endpoint for creating and updating people in Ortto.
2	The custom API key configured as part of the getting started process.
3	The first `people` array object containing a person’s data (as person fields) to be created or updated in your Ortto account’s CDP. This example assumes that this person already exists in the CDP.
4	The `bol::p` (email subscription permission) field's value of `false`, flags that this person has their Email permission set to false, or Unsubscribed through the Ortto user interface (UI).
5	An optional custom activity context message (`str::u-ctx`) to use when setting the `bol::p` (email subscription permission) field’s value to `false`.

Node.js example

Node.js example of the same cURL request (described above) to set a person’s email subscription permission to false in the CDP

javascript
 const people = [
  { <3>
    "fields": {
      "str::email": "chris.smith@example.com",
      "bol::p": false, <4>
      "str::u-ctx": "Unsubscribed from email using a custom context message" <5> 
    }
  }
];

const data = {
  people
};

request({
  url: 'https://api.ap3api.com/v1/person/merge', <1>
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR-CUSTOM-API-KEY', <2>
    'Content-Type': 'application/json'
  },
  json: data
}, (err, resp, body) => {
  console.log("API response:", body);
});

cURL example - set the email subscription permission back to true

cURL example request to set a person’s email subscription permission back to true in your Ortto CDP

shell
 curl --request POST 'https://api.ap3api.com/v1/person/merge' \
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "people": [
          {
            "fields": {
              "str::email": "chris@example.com",
              "bol::p": true, <1>
              "str::s-ctx": "Subscribed to email using a custom context message" <2> 
            }
          }
        ]
      }'

1	The `bol::p` (email subscription permission) field's value of `true`, flags that this person has their Email permission set to true, or Subscribed through the Ortto UI.
2	An optional custom activity context message (`str::s-ctx`) to use when setting the `bol::p` (email subscription permission) field’s value to `true`.

Node.js example - set the email subscription permission back to true

Node.js example of the same cURL request (described above) to set a person’s email subscription permission back to true in the CDP

javascript
 const people = [
  {
    "fields": {
      "str::email": "chris.smith@example.com",
      "bol::p": true, <1>
      "str::s-ctx": "Subscribed to email using a custom context message" <2>
    }
  }
];

const data = {
  people
};

request({
  url: 'https://api.ap3api.com/v1/person/merge',
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR-CUSTOM-API-KEY',
    'Content-Type': 'application/json'
  },
  json: data
}, (err, resp, body) => {
  console.log("API response:", body);
});

Configure the SMS subscription permission

cURL example

cURL example request to set a person’s SMS subscription permission to true in the Ortto CDP

shell
 curl --request POST 'https://api.ap3api.com/v1/person/merge' \ <1>
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \ <2>
     --header 'Content-Type: application/json' \
     --data-raw '{
        "people": [
          { <3>
            "fields": {
              "str::email": "chris@example.com",
              "bol::sp": true, <4>
              "str::soi-ctx": "Subscribed to SMS using a custom context message" <5> 
            }
          }
        ]
      }'

1	The API endpoint for creating and updating people in Ortto.
2	The custom API key configured as part of the getting started process.
3	The first `people` array object containing a person’s data (as person fields) to be created or updated in your Ortto account’s CDP. This example assumes that this person already exists in the CDP.
4	The `bol::sp` (SMS subscription permission) field's value of `true`, flags that this person has their SMS permission set to true, or Subscribed through the Ortto UI.
5	An optional custom activity context message (`str::soi-ctx`) to use when setting the `bol::sp` (SMS subscription permission) field’s value to `true`.

Node.js example

Node.js example of the same cURL request (described above) to set a person’s SMS subscription permission to true in the CDP

javascript
 const people = [
  { <3>
    "fields": {
      "str::email": "chris.smith@example.com",
      "bol::sp": true, <4>
      "str::soi-ctx": "Subscribed to SMS using a custom context message" <5>
    }
  }
];

const data = {
  people
};

request({
  url: 'https://api.ap3api.com/v1/person/merge', <1>
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR-CUSTOM-API-KEY', <2>
    'Content-Type': 'application/json'
  },
  json: data
}, (err, resp, body) => {
  console.log("API response:", body);
});

cURL example - set the SMS subscription permission back to false

cURL example request to set a person’s SMS subscription permission back to false in the Ortto CDP

shell
 curl --request POST 'https://api.ap3api.com/v1/person/merge' \
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "people": [
          {
            "fields": {
              "str::email": "chris@example.com",
              "bol::sp": false, <1>
              "str::soo-ctx": "Unsubscribed from SMS using a custom context message" <2> 
            }
          }
        ]
      }'

1	The `bol::sp` (SMS subscription permission) field's value of `false`, flags that this person has their SMS permission set to false, or Unsubscribed through the Ortto UI.
2	An optional custom activity context message (`str::soo-ctx`) to use when setting the `bol::sp` (SMS subscription permission) field’s value to `false`.

Node.js example - set the SMS subscription permission back to false

Node.js example of the same cURL request (described above) to set a person’s SMS subscription permission back to false in the CDP

javascript
 const people = [
  {
    "fields": {
      "str::email": "chris.smith@example.com",
      "bol::sp": false, <1>
      "str::soo-ctx": "Unsubscribed from SMS using a custom context message" <2> 
    }
  }
];

const data = {
  people
};

request({
  url: 'https://api.ap3api.com/v1/person/merge',
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR-CUSTOM-API-KEY',
    'Content-Type': 'application/json'
  },
  json: data
}, (err, resp, body) => {
  console.log("API response:", body);
});