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
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 objectsThe
organizations
array consists of objects containing their ownfields
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 thisarray
) 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 thisfields
object contains an organization field member whose value matches themerge_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 themerge_strategy
value of this request.
async
boolean
When set to
true
, theasync
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 twostring
valuesThe
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 onemerge_by
element is mandatory.
merge_strategy
integer
(default value is2
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 thismerge_strategy
member value determines how the organization’s existing field values are merged. Learn more about this value in Merge strategy below. Ifmerge_strategy
is not specified in the request, then the default value of2
(Overwrite existing) is used.
find_strategy
integer
(default value is0
[any])The Find strategy determines how the
merge_by
fields are used in finding an existing organization to merge with, in particular, whether bothmerge_by
fields are used, or just one. Learn about the different options in Find strategy below. Iffind_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 arenull
.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 existingnull
to0
or""
. Exclude an empty value from search: set an existing""
or0
value tonull
.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 respectivefields : { … }
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, thenamespace
value iso
. 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
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 followingmerge_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 existingstr: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 existingstr: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 existingstr: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.
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 2merge_by
fields are provided, thefind_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
andstr:o:website
as your twomerge_by
fields, and provide both fields in your request:
Starting with the firstmerge_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
andstr:o:website
as your twomerge_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.