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:
-
valid parameters, headers, and request body values, as well as
-
the response payload.
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:
For example: https://api.eu.ap3api.com/v1/<entity/endpoint> All other Ortto users will use the default service endpoint (https://api.ap3api.com/). |
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.
{
"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 |
---|---|---|
|
|
The |
Object containing organization field members |
The object containing the fields for an organization being created or updated in your Ortto account’s CDP.
|
|
|
|
|
|
The When the value of the organization field member (determined by the relevant Unlike the |
|
|
When the |
|
|
|
The Find strategy determines how the |
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 |
|
|
A string whose value is the name of the organization.
This organization field and its value is commonly used as the main |
Employees |
|
|
An integer whose value is the number of employees within the organization. |
Industry |
|
|
A string whose value briefly categorizes the organization’s type of industry. |
Website |
|
|
A string whose value is the URL for the organization’s web site. |
City |
|
|
A geographical data object consisting of a member |
Address |
|
|
A string whose value is the organization’s actual street address. |
Region |
|
|
A geographical data object consisting of a member |
Country |
|
|
A geographical data object consisting of a member |
Postal |
|
|
A string whose value is this organization’s current postal code. |
Source |
|
|
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 iso
. 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 isoc
, 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 |
---|---|
|
Geographical data (object) |
|
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. |
|
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
|
||
2 |
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 For example, assuming you have a custom field
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.
|
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 |
Using this strategy, all For example, assuming you have
|
|
1 |
Next only if previous empty |
Using this strategy, the first For example, assuming you have
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. |