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:

HTTP method and request resource

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

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

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.

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

 
"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

 
"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

 
"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

  • Your own custom organization fields in Ortto, the namespace value is oc, and hence, these custom fields are referenced by an ID based on the format:

    • type:oc:field-name

    Up to 100 custom fields can be added to an Ortto account/instance.

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

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.

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.