Retrieve one or more organizations (get)

The get Ortto endpoint of the organizations entity is used to retrieve one or more organization 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/organizations/get

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 organization records in your Ortto account’s CDP.

Example get organizations request body from Ortto’s CDP
{
  "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"
    }
  }
}
Example get organizations request body from Ortto’s CDP
{
  "q": "ortto"
}

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 organization record in the next page of organizations (defined by the limit member value). This value is retrieved from the previous /v1/organizations/get endpoint request.

sort_by_field_id

string

The sort_by_field_id element whose organization field ID value specifies the organization 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 organization field ID values that define the organization fields of the organization records returned by Ortto from the request.

inclusion_ids

array of string values

A list of organization_ids to include in the search.

exclusion_ids

array of string values

A list of organization_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 organizations by name.

If you wish to search for organizations 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 organization records returned by Ortto from the request.

type can accept the following values:

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

  • organization

  • archived_organization

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

To retrieve a list of archived organizations:

{
  "type": "archived_organization"
}

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

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

organization_id

string

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

filter

Object containing a organizations’s field ID (representing an organization 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 organizations response payload from Ortto’s CDP
{
    "organizations": [
        {
            "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_organizations": 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

organizations

An array of organizations 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 organizations in your database in total

  • total_organizations - Number of organizations in your database in total

  • total_matches - Number of organizations matching your query or filter

  • total_subscribers - Will return 0 for organizations (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.