Manage organization association (add/remove)

The add and remove Ortto endpoints of the organizations entity are used to manage the association of one or more people (contacts) records with organization records in Ortto’s customer data platform (CDP).

Learn more about managing people associated with organizations under Adding and removing people from organizations.

This page provides descriptions of these endpoint:

HTTP method and request resources

Add endpoint
PUT https://api.ap3api.com/v1/organizations/contacts/add
Remove endpoint
PUT https://api.ap3api.com/v1/organizations/contacts/remove

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 object is an example of field and object data that Ortto can recognize to manage the association of one or more people records with organization records in your Ortto account’s CDP.

Example add people to organizations request body from Ortto’s CDP
{
  "inclusion_ids": [
    "00609384fa6de6e7a8d89d01", "006046baa37f2e24cc56f122"
  ],
  "organization_id": "106051701f79e14b592cee00"
}

You can also add/remove people using a filter, where all contacts who match the filter will be added/removed from the organization.

For example, if you want to add all contacts with an email address belonging to a particular organization, you could construct a request like the following. In this example, we are going to add all contacts with an email address containing "smithco" (e.g. "jenny@smithco.com") to the organization "Smith & Co" (which has an organization ID of "1062bbe691283847f475c800").

Example using a filter to add people to an organization
{
"filter": {
  "$str::contains":{
    "field_id": "str::email",
    "value": "smithco"
}
},
"organization_id": "1062bbe691283847f475c800"
}

  • You can add up to 3000 people per organization.

  • A contact can be added (linked) to only 1 organization.

    If a contact is linked to Organization A and you add them to Organization B, the contact will be automatically removed from Organization A.

Valid request body elements

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

Element Type Description

inclusion_ids

array of string values

A list of people to add to or remove from an organization.

You can obtain the contact ID using the get endpoint to retrieve one or more people. Or, find the contact ID in the Ortto app by viewing the contact’s profile and copying the ID from the URL (e.g. https://ortto.app/myinstance/cdp/people/00626f6dfba865ba45d9c200/activities?from=cdp-filter&key=people-all-).

organization_id

array of string values

The organization to add people to or remove people from.

You can obtain the organization ID using the get endpoint to retrieve one or more organizations. Or, find the contact ID in the Ortto app by viewing the organization’s profile and copying the ID from the URL (e.g. https://ortto.app/myinstance/cdp/organizations/10626f6dfba865ba45d9c200/activities?from=cdp-filter&key=organizations-all-).

filter

Object containing a person’s field_ID (representing a person field) used for filtering

The filter element contains a field member that determines how records are filtered.

Therefore, a construct like:

"filter": {
  "$str::contains":{
    "field_id": "str::email",
    "value": "smithco"
}
}

where str::email is the person’s email field would filter and return people who have an email address containing "smithco".

→ field_id

string

The field_id element enables you to filter results by a field ID. This returns records that have the specified field populated and can be used in conjunction with value to filter records by specific field values.

→ value

string

Use value to specify a specific field value you wish to return contact records by. For example, this can be helpful if you are looking for a specific contact and filter by the contact’s email address:

"filter": {
  "$str::is":{
    "field_id": "str::email",
    "value": "contact@email.com"
}
}

Response payload

If your request is successful, the response payload will be empty (consisting of an empty set of curly braces).