Tagging and untagging organizations

Overview

Learn how to use the Ortto API to add tags to (or remove existing tags from) organizations 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 organizations in your Ortto CDP, submit a POST method request to the following endpoint:


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

This endpoint is also used to create and update organizations, allowing you to manage tags seamlessly alongside other organization 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 organization in the Ortto CDP

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

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

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

const data = {
  organizations
};

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

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

shell
 curl --request POST 'https://api.ap3api.com/v1/organization/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
 {
    "organizations": [
        {
            "id": "1066fc2592c5e98d5ecbc800",
            "fields": {
                "tags": [
                    "tag1",
                    "tag2"
                ]
            }
        }
    ],
    "meta": {
        "total_contacts": 47,
        "total_organizations": 554,
        "total_matches": 1,
        "total_subscribers": 0
    },
    "offset": 0,
    "next_offset": 1,
    "cursor_id": "1067216e0df3cd2386ce6b6a",
    "has_more": false
}

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