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.

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.

cURL example

cURL example request to add new tags and remove existing ones from a person in the Ortto CDP

shell
 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

javascript
 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:

shell
 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:

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