Create or update one or more accounts (previously organizations) (merge)

accounts

array of objects

The accounts array consists of objects containing their own fields objects, where each of these objects contains data associated with an account being created or updated in your Ortto account’s CDP. Between 1 to 100 accounts (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 account field members

The object containing the fields for an account being created or updated in your Ortto account’s CDP. This account is either created or updated in Ortto’s CDP based on these criteria:

• If this fields object contains an account field member whose value matches the merge_by member’s value submitted in this request, and this account field’s value does not match that of an existing account in Ortto’s CDP, then Ortto creates this organization as a new record.
• Otherwise, if the account field member’s value does already match that of an existing account in Ortto’s CDP, then Ortto updates the fields of that accounts 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 account in this request. Tags can be applied to a account, 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 account. If the account 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 account 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 account, then specifying them in this array has no effect.

Therefore, a construct like:

json
 
 "accounts": [
    {
      "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 account, 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 account 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 account fields used to determine whether the organizations' records are either created or updated in your Ortto account’s CDP.

When the value of the account field member (determined by the relevant merge_by member value), submitted in this request matches that of an existing account in Ortto’s CDP, then this accounts record is updated in the CDP and where appropriate, existing field values are merged according to the strategy below. Otherwise, Ortto creates a new accounts 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 account field member value) submitted in this request determines that an existing accounts record in Ortto’s CDP will be updated, then this merge_strategy member value determines how the accounts 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 account 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 account. This account field and its value is commonly used as the main merge_by field that determines whether an accounts record in Ortto’s CDP is either created or updated.

Account ID

str:o:account_id

"str:o:account_id": "Ortto"

A string value representing a unique identifier for the o CDP record.

Employees

int:o:employees

"int:o:employees": 60

An integer whose value is the number of employees within the account.

Industry

str:o:industry

"str:o:industry": "SaaS"

A string whose value briefly categorizes the accounts type of industry.

Website

str:o:website

"str:o:website": "https://ortto.com"

A string whose value is the URL for the accounts 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 accounts current city.

Address

str:o:address

"str:o:address": "28 O’Connell St"

A string whose value is the accounts 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 accounts 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 accounts current country.

Postal

str:o:postal

"str:o:postal": "2000"

A string whose value is this accounts current postal code.

Source

str:o:source

"str:o:source": "Google AdWords"

A string whose value represents the data source that created this accounts record. For manually created accounts 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 account field value: "str:oc:head-office-city": "Oslo",

• If this accounts 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 accounts 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 account fields specified in the request are updated in Ortto’s CDP, even when existing values are present, and hence are overwritten. An accounts field in the CDP can be cleared by specifying the corresponding account field’s value in the request as null.

For example, assuming you have a custom field str:oc:head-office-city and this accounts existing str:oc:head-office-city value in the CDP is "Sydney", then a request containing the account 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 accounts fields which are not specified in the request are not cleared (and retain their value) in the accounts CDP record.

3

Ignore

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

0

Any (default)

Using this strategy, all merge_by fields are used in detecting an existing account 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 account 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 account 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 account in the request, only then will the second field be used to detect a match.