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:

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

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

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 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

json
 {
  "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

json
 {
"filter": {
  "$str::contains":{
    "field_id": "str::email",
    "value": "smithco"
}
},
"organization_id": "1062bbe691283847f475c800"
}

NOTE:

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: json `"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: json `"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).