Tagging and untagging accounts (previously organizations)

Overview

Learn how to use the Ortto API to add tags to (or remove existing tags from) accounts in your Ortto account’s customer data platform (CDP). Follow the examples in this article for step-by-step instructions.

To add or remove tags for accounts in your Ortto CDP, submit a POST method request to the following endpoint:


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

This endpoint is also used to create and update accounts, allowing you to manage tags seamlessly alongside other account information.

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/

EX: 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 an account in the Ortto CDP

shell
 curl --request POST 'https://api.ap3api.com/v1/accounts/merge' \  <1>
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \  <2>
     --header 'Content-Type: application/json' \
     --data-raw '{
        "accounts": [
          { <3>
            "fields": {
              "str:o:name": "Ortto"
            },
            "tags": ["tag3", "tag4"],  <4>
            "unset_tags": ["tag1", "tag2"] <5>
          }
        ]
      }'

1	The API endpoint for creating and updating accounts in Ortto.
2	The custom API key configured as part of the getting started process.
3	The first account array object containing an account data in your Ortto account’s CDP. This example assumes that this account already exists in the CDP.
4	The `tags` array specifies each tag to be added to this account in the request. If a specified tag already exists in your Ortto account’s CDP, that tag is re-used when applied to the account. Otherwise, a new tag is automatically created in the CDP and applied to the account. If the account does not yet exist in the CDP, it will be created before applying any tags.
5	The `unset tags` array specifies each tag to be removed from the this account 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 an accounts in the CDP

javascript
 const accounts = [
  {  //<3>
    "fields": {
      "str:o:name": "Ortto"
    },
    "tags": ["tag3", "tag4"], //<4>
    "unset_tags": ["tag1", "tag2"] //<5>
  }
];

const data = {
  accounts
};

request({
  url: 'https://api.ap3api.com/v1/accounts/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 an accounts tags

To get an accounts tags (or account' tags) specify tags in the list of fields, here’s an example:

shell
 curl --request POST 'https://api.ap3api.com/v1/accounts/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:o:name",
          "value": "Ortto"
        }
      }
    }'

And an example response:

json
 {
    "accounts": [
        {
            "id": "1066fc2592c5e98d5ecbc800",
            "fields": {
                "tags": [
                    "tag1",
                    "tag2"
                ]
            }
        }
    ],
    "meta": {
        "total_contacts": 47,
        "total_accounts": 554,
        "total_matches": 1,
        "total_subscribers": 0
    },
    "offset": 0,
    "next_offset": 1,
    "cursor_id": "1067216e0df3cd2386ce6b6a",
    "has_more": false
}

Our resource for retrieving accounts can also be found: here.