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.