Create or update one or more organizations (merge)

The merge Ortto endpoint of the organizations entity is used to create or update one or more organization records in Ortto’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:

request resource and method,
valid parameters, headers, and request body values.

HTTP method and request resource


 POST https://api.ap3api.com/v1/organizations/merge

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 create or update one or more organization records in your Ortto account’s CDP.

Example create/update organizations request body in Ortto’s CDP

json
 {
  "organizations": [
    {
      "fields": {
        "str:o:name": "Ortto",
        "int:o:employees": 60,
        "str:o:industry": "SaaS",
        "str:o:website": "https://ortto.com",
        "geo:o:city": {"name": "San Francisco"},
        "str:o:address": "1390 Market St",
        "geo:o:region": {"name": "California"},
        "geo:o:country": {"name": "United States"},
        "str:o:postal": "94102",
        "str:o:source": "API"
      }
    },
    {
      "fields": {
        "str:o:name": "My Online Store",
        "int:o:employees": 200,
        "str:o:industry": "E-commerce",
        "str:o:website": "https://www.myonlinestore.studio",
        "geo:o:city": {"name": "San Francisco"},
        "str:o:address": "9000 O'Dea Ave",
        "geo:o:region": {"name": "California"},
        "geo:o:country": {"name": "USA"},
        "str:o:postal": "94123",
        "str:o:source": "API"
      }
    }
  ],
  "async": false,
  "merge_by": ["str:o:name"],
  "merge_strategy": 2,
  "find_strategy": 0
}

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
`organizations`	`array` of objects	The `organizations` array consists of objects containing their own `fields` objects, where each of these objects contains data associated with an organization being created or updated in your Ortto account’s CDP. Between 1 to 100 organizations (each as individual objects of this `array`) can be created and/or updated in a single request body call to this endpoint.
→ `fields`	Object containing organization field members	The object containing the fields for an organization being created or updated in your Ortto account’s CDP. This organization is either created or updated in Ortto’s CDP based on these criteria: If this `fields` object contains an organization field member whose value matches the `merge_by` member’s value submitted in this request, and this organization field’s value does not match that of an existing organization in Ortto’s CDP, then Ortto creates this organization as a new record. Otherwise, if the organization field member’s value does already match that of an existing organization in Ortto’s CDP, then Ortto updates the fields of that organization’s record in the Ortto CDP, based on the `merge_strategy` value of this request.
`async`	`boolean`	When set to `true`, the `async` element enables you to queue the ingestion of merged organization data. You will receive. animmediate response confirming the queued ingestion.
`merge_by`	`array` of one or two `string` values	The `merge_by` element/s whose field ID values specify the organization fields used to determine whether the organizations' records are either created or updated in your Ortto account’s CDP. When the value of the organization field member (determined by the relevant `merge_by` member value), submitted in this request matches that of an existing organization in Ortto’s CDP, then this organization’s record is updated in the CDP and where appropriate, existing field values are merged according to the strategy below. Otherwise, Ortto creates a new organization’s record in the CDP. Unlike the `merge_by` value for the `/v1/person/merge` endpoint, there are no default field values associated with the custom API key submitted along with the request. Therefore, specifying at least one `merge_by` element is mandatory.
`merge_strategy`	`integer` (default value is `2` Overwrite existing)	When the `merge_by` member value (and its corresponding organization field member value) submitted in this request determines that an existing organization’s record in Ortto’s CDP will be updated, then this `merge_strategy` member value determines how the organization’s existing field values are merged. Learn more about this value in Merge strategy below. If `merge_strategy` is not specified in the request, then the default value of `2` (Overwrite existing) is used.
`find_strategy`	`integer` (default value is `0` [any])	The Find strategy determines how the `merge_by` fields are used in finding an existing organization to merge with, in particular, whether both `merge_by` fields are used, or just one. Learn about the different options in Find strategy below. If find_strategy" is not specified in the request, then the default value of `0 ([any]) is used.

About empty values

When you use a filter to search for organizations, the Has any value filter option will find matches for field values that have a value of 0 or "" (empty string). However, Has any value won’t find attribute or field values that are null.

You can set values according to your needs by updating a organization's data using this API endpoint (v1/organizations/merge). To:

Include an empty value in a search: set an existing null to 0 or "".
Exclude an empty value from search: set an existing "" or 0 value to null.

For example, updating an organization's field value to exclude it from search can look like this:

json
 "organizations": [
    {
      "fields": {
        "str:o:name": "Oscar's Pet Supplies",
        "str:o:industry": null
      }

Organization fields

In Ortto, an organization field:

contains the data for a specific piece of information (i.e. field) about each organization in Ortto’s CDP,
is referenced via the Ortto API using a specific ID format,
could be a built in Ortto field or a custom field you have defined yourself (which also has its own ID format), and
is defined as a member for each organization (within their respective fields : { … } object) submitted in the request to this endpoint.

The following built-in organization fields are accessible through Ortto’s API when creating or updating organizations in the CDP.

Field name (in product)	Field ID	Example	Description
Name	`str:o:name`	`"str:o:name": "Ortto"`	A string whose value is the name of the organization. This organization field and its value is commonly used as the main `merge_by` field that determines whether an organization’s record in Ortto’s CDP is either created or updated.
Employees	`int:o:employees`	`"int:o:employees": 60`	An integer whose value is the number of employees within the organization.
Industry	`str:o:industry`	`"str:o:industry": "SaaS"`	A string whose value briefly categorizes the organization’s type of industry.
Website	`str:o:website`	`"str:o:website": "https://ortto.com"`	A string whose value is the URL for the organization’s web site.
City	`geo:o:city`	json `"geo:o:city": { "name": "Melbourne" }`	A geographical data object consisting of a member `name` whose string value is this organization’s current city.
Address	`str:o:address`	`"str:o:address": "28 O’Connell St"`	A string whose value is the organization’s actual street address.
Region	`geo:o:region`	json `"geo:o:region": { "name": "Victoria" }`	A geographical data object consisting of a member `name` whose string value is this organization’s current region (e.g. state or province) within its country.
Country	`geo:o:country`	json `"geo:o:country": { "name": "Australia" }`	A geographical data object consisting of a member `name` whose string value is this organization’s current country.
Postal	`str:o:postal`	`"str:o:postal": "2000"`	A string whose value is this organization’s current postal code.
Source	`str:o:source`	`"str:o:source": "Google AdWords"`	A string whose value represents the data source that created this organization’s record. For manually created organization records, this value is typically Manually created.

Organization field ID format

Each organization field is referenced by an ID.

Since Ortto integrates with many third-party products, references to organization fields in Ortto’s CDP are both strongly-typed and namespace-specific. Therefore, each organization field’s ID is based on the format:

type:namespace:field-name

For:

Ortto’s own built-in organization fields, the namespace value is o. Hence, these built-in fields are referenced by an ID based on the format:
- type:o:field-name
Up to 100 custom fields can be added to an Ortto account/instance.
- type:oc:field-name

Organization field type abbreviations

The following organization field type abbreviations are used to form the first part (type) of each organization field’s ID for built-in fields:

Field type abbreviation	Type of value
`geo`	Geographical data (object)
`int`	Integer. For internal operations and calculations, the Ortto API treats decimal values as integers multiplied by 1,000. This is done to preserve the precision of values resulting from these calculations.
`str`	String

Field type abbreviation

Type of value

geo

Geographical data (object)

int

Integer.

For internal operations and calculations, the Ortto API treats decimal values as integers multiplied by 1,000. This is done to preserve the precision of values resulting from these calculations.

str

String

Merge strategy

The merge strategy determines how an organization’s existing field values are merged.

When the merge_by member value (and its corresponding organization field member value) submitted in this request determines that an existing organization’s record in Ortto’s CDP will be updated, then one of the following merge_strategy values in the request determines how the organization’s existing field values are merged:

merge_strategy (integer)	Strategy	Description
1	Append only	Using this strategy, all fields with existing values in Ortto’s CDP are not changed. Ortto only adds new data (for fields without a value). For example, assuming you have a custom field `str:oc:head-office-city`, and the request contains the organization field value: `"str:oc:head-office-city": "Oslo"`, If this organization’s existing `str:oc:head-office-city` value is `"Sydney"` in the CDP, then this existing value would not be changed after the request is submitted, and the value would remain `"Sydney"` in the CDP. If, however, this organization’s existing `str:oc:head-office-city` value is empty in the CDP, then this empty field would be updated to "Oslo" in the CDP.
2	Overwrite existing (default)	Using this strategy, any organization fields specified in the request are updated in Ortto’s CDP, even when existing values are present, and hence are overwritten. An organization’s field in the CDP can be cleared by specifying the corresponding organization field’s value in the request as `null`. For example, assuming you have a custom field `str:oc:head-office-city` and this organization’s existing `str:oc:head-office-city` value in the CDP is `"Sydney"`, then a request containing the organization field value: `"str:oc:head-office-city": "Oslo"` would be changed to `"Oslo"` in the CDP after the request is submitted, `"str:oc:head-office-city": null` would be cleared and made empty in the CDP after the request is submitted. Any organization fields which are not specified in the request are not cleared (and retain their value) in the organization’s CDP record.
3	Ignore	Using this strategy, no updates are applied to the existing organization’s record in Ortto’s CDP. TIP: Use this merge strategy to enforce only adding new organizations to the CDP, leaving existing organizations' records untouched.

merge_strategy (integer)

Strategy

Description

Append only

Using this strategy, all fields with existing values in Ortto’s CDP are not changed. Ortto only adds new data (for fields without a value).

For example, assuming you have a custom field str:oc:head-office-city, and the request contains the organization field value: "str:oc:head-office-city": "Oslo",

If this organization’s existing str:oc:head-office-city value is "Sydney" in the CDP, then this existing value would not be changed after the request is submitted, and the value would remain "Sydney" in the CDP.
If, however, this organization’s existing str:oc:head-office-city value is empty in the CDP, then this empty field would be updated to "Oslo" in the CDP.

Overwrite existing (default)

Using this strategy, any organization fields specified in the request are updated in Ortto’s CDP, even when existing values are present, and hence are overwritten. An organization’s field in the CDP can be cleared by specifying the corresponding organization field’s value in the request as null.

For example, assuming you have a custom field str:oc:head-office-city and this organization’s existing str:oc:head-office-city value in the CDP is "Sydney", then a request containing the organization field value:

"str:oc:head-office-city": "Oslo" would be changed to "Oslo" in the CDP after the request is submitted,
"str:oc:head-office-city": null would be cleared and made empty in the CDP after the request is submitted.

Any organization fields which are not specified in the request are not cleared (and retain their value) in the organization’s CDP record.

Ignore

Using this strategy, no updates are applied to the existing organization’s record in Ortto’s CDP.

TIP: Use this merge strategy to enforce only adding new organizations to the CDP, leaving existing organizations' records untouched.

Find strategy

The find strategy determines how the merge_by fields are used to detect an existing organization match.

The find strategy is only relevant if you have 2 merge_by fields provided. When you have only 1 field, this setting makes no difference to the outcome. When 2 merge_by fields are provided, the find_strategy value determines if we utilise both fields or just one, in detecting an existing organization match:

find_strategy (integer)	Strategy	Description
0	Any (default)	Using this strategy, all `merge_by` fields are used in detecting an existing organization to merge with. For example, assuming you have `str:o:name` and `str:o:website` as your two `merge_by` fields, and provide both fields in your request: Starting with the first `merge_by` field (in this case, `str:o:name`), try to find an existing organization match using that field, and if a match is found, merge. If a match is not found using the first field, the second field is then used (in this case, `str:o:website`) to try and find a match, and if found, merge.
1	Next only if previous empty	Using this strategy, the first `merge_by` field is prioritized, and the second field is only used if the first field was not provided. For example, assuming you have `str:o:name` and `str:o:website` as your two `merge_by` fields, and provide both fields in your request: Starting with the first `merge_by field (in this case, `str:o:name`), try to find an existing organization match using that field, and if a match is found, merge. If a match is not found using the first field, the second field is ignored (even if there would be a match). If the first field is not provided for an organization in the request, only then will the second field be used to detect a match.

find_strategy (integer)

Strategy

Description

Any (default)

Using this strategy, all merge_by fields are used in detecting an existing organization to merge with.

For example, assuming you have str:o:name and str:o:website as your two merge_by fields, and provide both fields in your request:

Starting with the first merge_by field (in this case, str:o:name), try to find an existing organization match using that field, and if a match is found, merge.
If a match is not found using the first field, the second field is then used (in this case, str:o:website) to try and find a match, and if found, merge.

Next only if previous empty

Using this strategy, the first merge_by field is prioritized, and the second field is only used if the first field was not provided.

For example, assuming you have str:o:name and str:o:website as your two merge_by fields, and provide both fields in your request:

Starting with the first `merge_by field (in this case, str:o:name), try to find an existing organization match using that field, and if a match is found, merge.
If a match is not found using the first field, the second field is ignored (even if there would be a match).

If the first field is not provided for an organization in the request, only then will the second field be used to detect a match.