Retrieve one or more accounts (previously organizations)(get)

The get Ortto endpoint of the accounts entity is used to retrieve one or more accounts records in Ortto’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:


HTTP method and request resource

POST https://api.ap3api.com/v1/accounts/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 whose valid elements are listed in the table below.

The following JSON objects are examples of field and object data that Ortto can recognize to get data from one or more account records in your Ortto account’s CDP.

Example get account request body from Ortto’s CDP

json

{ "limit": 100, "sort_by_field_id": "str:o:name", "sort_order": "asc", "offset": 0, "fields": ["int:o:employees", "str:o:industry"], "filter": { "$has_any_value": { "field_id": "geo:o:country" } } }

NOTE: The $has_any_value filter option will return results that have a value of 0 or "". Learn more about empty values.

Example get account request body from Ortto’s CDP

json

{ "q": "ortto" }

Generating filters using the browser's dev tools

Depending on the number of conditions, fields, or activities in your filter, creating it reliably can become complex. Fortunately, we have a trick that lets you copy an already created filter from the browser's dev tools. You can follow these steps if you're using Google Chrome. If you're using a different browser, you may need to adjust the steps accordingly.

Follow the steps below to do this:

  1. Open the browser's dev tools and select the Network tab.
  2. Create the filter in-app on the Account page.
  3. Locate the create request and click on it.
  4. In the Preview tab, right-click on the filter and select either Copy value or Copy object.
  5. Paste the object into your API call.
Example of where to locate the 'create' request after building the filter in-app.

Example filter retrieved from the network tab

json

{ "$and": [ { "$and": [ { "$str::contains": { "label": "Website contains ortto.com", "field_id": "str:o:website", "timezone": "Italy", "value": "ortto.com" } }, { "$act::has_occurred": { "formData": { "mode": "hasOccurred", "label": "Opened email has occurred", "hasOccurred": { "op": "$act::has_occurred", "label": "has occurred" } }, "label": "Opened email has occurred", "field_id": "act::o", "timezone": "Italy", "name": "Opened email", "icon": "audience-newsletter-icon" } } ] } ] }

TIP: When copying the object from the network tab, some non-required fields (e.g. nametimezoneicon) may be included. You can exclude these to keep your API call cleaner, or send the call as is and it will still work.


Retrieve accounts based on Account ID

To retrieve Account records based on their IDs, use the following endpoint

POST https://api.ap3api.com/v1/accounts/get-by-ids

Simply include the IDs of the Accounts you want to retrieve within the account_ids parameter.

Example get account request body based on Account ID

json

{ "account_ids": ["10668b9d5c7d7d6dd895e100", "1066276f1272c7d821defc00"], "fields": ["str:o:name"] }

Valid request body elements

The following table lists all valid request body elements (arrays, objects, or fields), which are available to this endpoint.

Element

Type

Description

cursor_id

string containing a UUID value (e.g. 00609c898a4490c5800a5453)

The cursor_id element is the UUID for the start of the first account record in the next page of accounts (defined by the limit member value). This value is retrieved from the previous /v1/account/get endpoint request.

sort_by_field_id

string

The sort_by_field_id element whose account field ID value specifies the account fields used to sort the people returned from your Ortto account’s CDP.

sort_order

string with value asc or desc (default value is desc)

The sort_order element determines the order in which the people returned are sorted, based on the sort_by_field_id member value. Specifying this sort_order member is only relevant when the sort_by_field_id member is also specified.

fields

array of string values

The fields array contains account field ID values that define the account fields of the accounts records returned by Ortto from the request.

inclusion_ids

array of string values

A list of account_ids to include in the search.

exclusion_ids

array of string values

A list of account_ids to exclude from the search.

limit

integer between 1 to 500 (default value is 50)

The limit element value determines the number of people to be returned by Ortto from the request. This value also represents the page length of people (for pagination purposes), since potentially many thousands of people records could be retrieved from a single request. This element can be used in conjunction with offset to retrieve subsequent pages of people records. If this limit element is not specified in the request, or an integer value beyond the permitted maximum is specified, then this value is assumed to be 50.

offset

integer with a default value of 0

The offset element represents the count of people records in your Ortto account’s CDP for pagination purposes, and is the point from which the next page of people (defined by the limit member value) is retrieved.

q

string

The q element is a search parameter used only to find accounts by name.

If you wish to search for accounts by ID, for example, you would need to use the filter` element.

type

string

The type element is a valid text string used to filter the account records returned by Ortto from the request.

type can accept the following values:

  • "" (this the default value and will search for all accounts. It can be used with other elements described in this table, including filters as required)
  • account
  • archived_account

If you are pairing type with archived_account, you cannot use filters or other elements (only the query string is accepted).

To retrieve a list of archived accounts:

json

{ "type": "archived_accounts" }

Or to use type with a filter, you can construct the body something like this:

json

{ "type": "accounts", "filter": { "$str::is": { "field_id": "str:o:name", "value": "Bobs Burgers" } } }

account_id

string

The unique identifier for an account in Ortto’s CDP. This value is retrieved from the previous /v1/accounts/get endpoint request.

filter

Object containing a accounts field ID (representing an account field) used for filtering

The filter element contains a field member that determines whether records are filtered with ($has_any_value) or without ($has_no_value) a person field’s value.


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 accounts response payload from Ortto’s CDP

json

{ "accounts": [ { "id": "10626f6df9a865ba45d95300", "fields": { "int:o:employees": 9000, "str:o:industry": "Apparel" } }, { "id": "10626f6df9a865ba45d95900", "fields": { "int:o:employees": 120, "str:o:industry": "Consulting" } }, { "id": "10626f6df9a865ba45d95600", "fields": { "int:o:employees": 2680, "str:o:industry": "Construction" } }, { "id": "10626f6df9a865ba45d96800" } ], "meta": { "total_contacts": 25, "total_accounts": 33, "total_matches": 4, "total_subscribers": 0 }, "offset": 0, "next_offset": 4, "cursor_id": "106332a05d1fde21791d9c9b", "has_more": false }

Response payload elements

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

Element

Description

accounts

An array of accounts with an id and a fields hash which contacts the list of fields you requested to be returned.

meta

A hash of meta data containing information about the matches to your contacts GET request, including:

  • total_contacts — Number of contacts associated with accounts in your database in total
  • total_accounts — Number of accounts in your database in total
  • total_matches — Number of accounts matching your query or filter
  • total_subscribers — Will return 0 for accounts (if retrieving contacts, this would return the number of contacts subscribed to email marketing).

offset

The offset which was set on this request.

next_offset

The offset for fetching the next page of contacts.

cursor_id

When retrieving the next page of contacts, provide this cursor_id.

has_more

Whether or not there is a next page of contacts.