Retrieve a list of tags (get)

The get Ortto endpoint of the tags entity is used to retrieve a list of the person or organization tags in Ortto’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:

request resource and method,
valid parameters, headers, and request body values, as well as
the response payload.

HTTP method and request resource


 POST https://api.ap3api.com/v1/tags/get

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/).

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object with an optional search term.

json
 {
  "q": "search-term"
}

Response payload

The response payload consists of a JSON object with the elements listed in the table below.

The following JSON object is an example of the tag data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example get tags response payload from Ortto’s CDP

json
 {
    {
        "id": 1,
        "instance_id": "orttodocs",
        "name": "VIP",
        "source": "csv",
        "created_by_id": "123456789012345678901234",
        "created_by_name": "Team Ortto",
        "created_by_email": "help@ortto.com",
        "created_at": "2022-03-15T01:48:51.164Z",
        "last_used": "2022-08-10T05:56:57.697Z",
        "count": 43,
        "sms_opted_in": 20,
        "subscribers": 42,
        "type": ""
    }
}

Response payload elements

The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.

Element	Description
`id`	The ID of the tag, useful for applying as a filter when getting a group of contacts.
`instance_id`	The instance name of the account where this request is being made.
`name`	The name of the tag.
`source`	The name of the source where the tag was created, possible values include: csv, api, manual, zapier.
`created_by_id`	If the tag was created by a user (e.g. csv or api source), returns the ID of that user.
`created_by_name`	If the tag was created by a user (e.g. csv or api source), returns the name of that user.
`created_by_email`	If the tag was created by a user (e.g. csv or api source), returns the email of that user.
`created_at`	A timestamp of the date the tag was created.
`last_used`	A timestamp of the last time this tag was used.
`count`	The total contacts assigned this tag.
`sms_opted_in`	The total contacts assigned this tag and with SMS permission set to true.
`subscribers`	The total contacts assigned this tag and with Email permission set to true.
`type`	Specifies if this is a person tag, or an organization tag. An empty response signifies a 'person' tag, and "organization" signifies an `organization' tag.