Tagging and untagging people

Learn how to use the Ortto API to add tags to (or remove existing tags from) people in your Ortto account’s customer data platform (CDP) through the examples on this page.

Requests to add/remove tags to/from people 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.

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

cURL example

cURL example request to add new tags and remove existing ones from a person in the Ortto CDP
curl --request POST 'https://api.ap3api.com/v1/person/merge' \ (1)
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \ (2)
     --header 'Content-Type: application/json' \
     --data-raw '{
        "people": [
          { (3)
            "fields": {
              "str::email": "chris.smith@example.com"
            },
            "tags": ["tag3", "tag4"], (4)
            "unset_tags": ["tag1", "tag2"] (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 tags array, specifying each tag to be added to the this person in this request.
If a specified tag already exists in your Ortto account’s CDP, then that tag is re-used when applied to this person. Otherwise, a new tag is automatically created in the CDP and applied to this person.
If the person does not exist in the CDP, you can specify a tags array in the request, which either re-uses existing tags in the CDP or creates new tags, and applies them to the person upon their creation in the CDP.
5 The unset_tags array, specifying each tag to be removed from the this person in this request.

Node.js example

Node.js example of the same cURL request (described above) to add new tags and remove existing ones from a person in the CDP
const people = [
  { (3)
    "fields": {
      "str::email": "chris.smith@example.com"
    },
    "tags": ["tag3", "tag4"], (4)
    "unset_tags": ["tag1", "tag2"] (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);
});

Retrieving a person’s tags

To get a person (or people’s tags) specify "tags" in the list of fields, here’s an example:

curl --request POST 'https://api.ap3api.com/v1/person/get' \
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "limit": 1,
      "fields": ["tags"],
      "filter": {
        "$str::is": {
          "field_id": "str::email",
          "value": "chris@ortto.com"
        }
      }
    }'

And an example response:

{
  "contacts": [
    {
      "id": "00624536230993474f078a00",
      "fields": {
        "tags": [
          "mytag1",
          "mytag2"
        ]
      }
    }
  ],
  "meta": {
    "total_contacts": 7,
    "total_organizations": 0,
    "total_matches": 1,
    "total_subscribers": 0
  },
  "offset": 0,
  "next_offset": 1,
  "cursor_id": "00625f75d5aad233008daead",
  "has_more": false
}