Manage account (previously organizations) association (add/remove)

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

Learn more about managing people associated with accounts.

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/accounts/contacts/add

Remove endpoint


 PUT https://api.ap3api.com/v1/accounts/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 account records in your Ortto account’s CDP.

Example add people to accounts request body from Ortto’s CDP

json
 {
  "inclusion_ids": [
    "00609384fa6de6e7a8d89d01", "006046baa37f2e24cc56f122"
  ],
  "accounts_id": "106051701f79e14b592cee00"
}

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

EX: To add all contacts with an email address from a specific account, you can use a request like this:

In this example, we’re adding all contacts with email addresses containing smithco (e.g. jenny@smithco.com) to the account Smith & Co, which has the account ID 1062bbe691283847f475c800.

Example using a filter to add people to an account

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

NOTE:

You can add up to 3,000 people to a single account.
Each contact can only be linked to one account at a time.
If you add a contact to a new account, they’ll be automatically removed from the previous one.

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 account. 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-`).
`account_id`	`array` of `string` values	The account to add people to or remove people from. You can obtain the account ID using the `get` endpoint to retrieve one or more accounts. Or, find the contact ID in the Ortto app by viewing the accounts profile and copying the ID from the URL (e.g. `https://ortto.app/myinstance/cdp/accounts/10626f6dfba865ba45d9c200/activities?from=cdp-filter&key=accounts-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).