Create or update one or more organizations (merge)

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.

→ tags

array of string values

Each string value in the tags array represents a tag that is applied to this organization in this request. Tags can be applied to a organization, regardless of whether their record is being created or updated in your Ortto account’s CDP. If a specified tag already exists in the CDP, then that tag is re-used when applied to this organization. If the organization does not yet exist in the CDP, it will be created before applying any tags.

→ unset_tags

array of string values

Each string value in the unset_tags array represents a tag that is removed from this organization in this request. Be aware that if the unset_tags array:

• is used in conjunction with the tags array in a single request, avoid specifying the same tag in both arrays, since the processing order of these arrays may differ from one request to the next, resulting in unpredictable tagging outcomes.
• contains tags which were not applied to this organization, then specifying them in this array has no effect.

Therefore, a construct like:

json
 
 "organizations": [
    {
      "fields": {
        "str:o:name": "Company1"

      },
      "tags": ["Tag2", "Tag3"],
      "unset_tags": ["Tag1"]
    }

would result in Tag2 and Tag3 being applied to this org. Tag1 would be removed if it had already been applied. Otherwise, if Tag1 were not applied to this organization, the tag’s explicit removal (as depicted in this code example), has no effect.

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.

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.

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

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.

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.