Create or update one or more people (merge)

people

array of objects

The people array consists of an array of objects, where each object contains data associated with a person being created or updated in your Ortto account’s CDP. Each of these objects can contain:

• fields and location objects.
• tags and unset_tags arrays.

Between 1 to 100 people (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 person field members

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

• If this fields object contains a person field member whose value matches the merge_by member’s value submitted in this request, and this person field’s value does not match that of an existing person in Ortto’s CDP, then Ortto creates this person as a new record.
• Otherwise, if the person field member’s value does already match that of an existing person in Ortto’s CDP, then Ortto updates the fields of that person’s record in the Ortto CDP, based on the merge_strategy value of this request.

→ location

Object containing location field data

The location object either accepts a single IP address (as a source_ip field member), or a full address (in either a custom or address object). The location object provides more flexible options for specifying a person’s location and address details rather than having to specify this information via geo-type person fields in a fields object (above).

→ tags

array of string values

Each string value in the tags array represents a tag that is applied to this person in this request. Tags can be applied to a person, 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 person. Otherwise, a new tag is automatically created in the CDP and applied to this person.

→ unset_tags

array of string values

Each string value in the unset_tags array represents a tag that is removed from this person 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 person, then specifying them in this array has no effect.

Therefore, a construct like:

json
 
"people": [
  {
    "fields": {
      "str::email": "chris.smith@example.com"
    },
    "tags": ["Tag2", "Tag3"],
    "unset_tags": ["Tag1"]
  }
]

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

→ clear_fields

Object containing person field members

The clear_fields object enables you to determine which person field values will be overwritten by the data provided in the payload at fields (when the merge_strategy is set to 2). Learn more about clearing and setting a person's field values.

async

boolean

When set to true, the async element enables you to queue the ingestion of merged person data. You will receive an immediate response confirming the queued ingestion.

merge_by

array of one or two string values

The merge_by element’s array allows up to three field ID values that specify the person fields used to determine whether the people’s records are either created or updated in your Ortto account’s CDP.

When the value of the person field member (determined by the relevant merge_by member value), submitted in this request matches that of an existing person in Ortto’s CDP, then this person’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 person’s record in the CDP.

These values respectively override the default person fields associated with the custom API key submitted in this request. These default field values are defined by the Merge strategy associations configured for this custom API key. If a merge_by element is not specified in the request, then these default person field values are utilized instead. The first of these values determines the main merge_by person field utilized by Ortto in the request, whereas the second (optional) value determines the fallback merge_by person field (which behaves as a backup should the first field - e.g. a custom field - not be available within the person’s record of Ortto’s CDP).

merge_strategy

integer (default value is 2 Overwrite existing)

When the merge_by member value (and its corresponding person field member value) submitted in this request determines that an existing person’s record in Ortto’s CDP will be updated, then this merge_strategy member value determines how the person’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 existing people to merge with. 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.

skip_non_existing

boolean

The skip_non_existing flag enables you to perform updates to existing contacts and not add contacts that do not already exist in your CDP.

For example, this is useful when you want to update the email address for a contact by their data source ID (in this example, a Chargebee customer ID):

 
"people": [
{
"fields": {
  "str::email": "customer@email.com",
  "str:cb:c_id": "123456789"
}
}
],
"async": false,
"merge_by": ["str:cb:c_id"],
"merge_strategy": 1,
"find_strategy": 0,
"skip_non_existing": true

skip_non_existing works at the record level, not the field level. As such, where the person exists in the CDP, the merge strategy comes into play. Using the example above, when used in conjunction with merge-strategy:

• with a value of 1 ("merge_strategy": 1; append), the API will only add email addresses to contact records if the email address does not already exist (it will not add new contacts).
• with a value of 2 ("merge_strategy": 2; overwrite), the API will only overwrite exiting contact records to update existing email addresses.

NOTE: When using. a merge key that is read-only (such as the Chargebee customer ID above: "str:cb:c_id"), you must use "merge strategy": 2 (with skip_non_existing), as the API cannot write updates to a new contact based on a read-only merge key.

suppression_list_field_id

string

The suppression_list_field_id enables you to skip creating new contacts who have an email address that already exists on your Email suppression list, so you don't create a contact you won't be able to send emails too.

The value of this setting should be the field that contains the email address you want to compare against the suppression list, which in most cases will be the default email address, for example:

"suppression_list_field_id": "str::email"

When a contact is skipped because their email address is suppressed, you will get this response:

json
 
{
 "status": "suppressed",
 "error": "Email is suppressed"
}

First name

"str::first": "Chris"

A string whose value is this person’s first name.

Last name

"str::last": "Smith"

A string whose value is this person’s last name.

Person ID

"str::person_id": "00647687d2f43b25b0261f00"

A string value representing a unique identifier for the person’s CDP record.

Phone number



json
 
"phn::phone": {  
  "c": "61",
  "n": "401234567"
}

or

json
 
"phn::phone": {
  "phone": 
    "61401234567",
  "parse_with_country_code": 
    true
}

A phone number field can be provided in one of two ways:

1 - an object of two members consisting of valid country code digits (c) and a phone number (n), representing this person’s phone number. For the phone number, omit the initial trunk prefix/digit (e.g. 0) that is typically dialed when calling the number locally.

2 - An object of two members consisting of the phone number (phone) and whether that number should be considered to start with a country code or not (parse_with_country_code). Use this object to provide the full phone number in one field, not split out between the number and the country code.

Email

"str::email": "chris.smith@example.com"

A string whose value is this person’s email address. This person field and its value is commonly used as the main merge_by field that determines whether a person’s record in Ortto’s CDP is either created or updated. This field is mandatory if the External ID field is not provided in the containing fields object.

City

json
 
"geo::city": {
  "name": "Melbourne"
}

A geographical data object consisting of a member name whose string value is this person’s current city.

Country

json
 
"geo::country": {
  "name": "Australia"
}

A geographical data object consisting of a member name whose string value is this person’s current country.

Birthday

json
 
"dtz::b": {
  "year": 1980,
  "month": 3,
  "day": 4,
  "timezone": "Australia/Sydney"
}

A date object consisting of members year, month and day whose respective integer values represent this person’s date of birth, along with a timezone string representing the person’s current time zone.

Region

json
 
"geo::region": {
  "name": "Victoria"
}

A geographical data object consisting of a member name whose string value is this person’s current region (e.g. state or province) within their country.

Postal

"str::postal": "90210"

A string whose value is this person’s current postal code.

External ID

"str::ei": "c533532fe5d16c7d4fa4c7f0"

A string whose value is any ID used to uniquely identify this person. This value is mandatory if the email field is not provided in the containing fields object.

GDPR

"bol::gdpr": true

A boolean value where true flags that GDPR is a requirement for this person, or false if not.

Email subscription permission

"bol::p": false (default value is true)

A boolean value where true flags that the person has their Email permission set to true, or Subscribed through the Ortto user interface (UI), and false flags that this person’s permission is set to false (or Unsubscribed). If this person field is not specified in the request, then this value is assumed to be true by default.

Custom context message for the email unsubscribe action

"str::u-ctx": "Unsubscribed from email using a custom context message" (default value is "Unsubscribed via API")

A string value that allows you to customize the default activity context message from Unsubscribed via API to something else, when setting the email subscription permission to false. These messages appear in people’s Activities updates in the Ortto UI.

Custom context message for the email subscribe action

"str::s-ctx": "Subscribed to email using a custom context message" (default value is "Subscribed via API")

A string value that allows you to customize the default activity context message from Subscribed via API to something else, when setting the email subscription permission to true. These messages appear in people’s Activities updates in the Ortto UI.

SMS subscription permission

"bol::sp": true (default value is false)

A boolean value where false flags that the person has their SMS permission set to false, or Unsubscribed through the Ortto UI, and true flags that this person’s permission is set to true (or Subscribed). If this person field is not specified in the request, then this value is assumed to be false by default.

Custom context message for the SMS subscribe action

"str::soi-ctx": "Subscribed to SMS using a custom context message" (default value is "Subscribed via API")

A string value that allows you to customize the default activity context message from Subscribed via API to something else, when setting the SMS subscription permission to true. These messages appear in people’s Activities updates in the Ortto UI.

Custom context message for the SMS unsubscribe action

"str::soo-ctx": "Unsubscribed from SMS using a custom context message" (default value is "Unsubscribed via API")

A string value that allows you to customize the default activity context message from Unsubscribed via API to something else, when setting the SMS subscription permission to false. These messages appear in people’s Activities updates in the Ortto UI.

Language

"str::language": "de"

A string which determines the person’s preferred language. This can be used to present email campaigns in the person’s preferred language (where supported) using Ortto’s multi-language feature.

See a list of available language values at List of languages.

Allow tracking

"bol::at": true

A boolean value where true flags that this person has actively granted permission for email open/click tracking, or false flags that this person has actively denied permission for email open/click tracking.

If this person field is not specified in the request, the value remains unset (no value), meaning the person hasn't yet been asked or hasn't made a choice.

Learn more about subscriber-level email tracking permission.

Allow tracking context

"str::at-ctx": "API update"

A string value that allows you to describe why or how this person's Allow tracking value was set (e.g. via a capture form, preference center, footer link, CSV import, or API update).

FCM iOS push notification token

"str::fcm_ios_token": "my-token"

If a user has already given push permission to your mobile app before implementing Ortto's SDK, you can use these fields to submit the notification token to Ortto so it can be re-used for sending Ortto's push notifications without having to ask the customer for permission again.

APN iOS push notification token

"str::apn_ios_token": "my-token"



Android push notification token

"str::android_token": "my-token"

bol

Boolean

dtz

Date (object)

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.

Note: Integers are processed as int64

phn

Phone number (object)

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:cm:place-of-birth, and the request contains the person field value: "str:cm:place-of-birth": "Oslo",

• If this person’s existing str:cm:place-of-birth 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 person’s existing str:cm:place-of-birth 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 person fields specified in the request are updated in Ortto’s CDP, even when existing values are present, and hence are overwritten. A person’s field in the CDP can be cleared by specifying the corresponding person field’s value in the request as null. For example, assuming you have a custom field str:cm:place-of-birth and this person’s existing str:cm:place-of-birth value in the CDP is "Sydney", then a request containing the person field value:

• "str:cm:place-of-birth": "Oslo" would be changed to "Oslo" in the CDP after the request is submitted,
• "str:cm:place-of-birth": null would be cleared and made empty in the CDP after the request is submitted.

Any person fields which are not specified in the request are not cleared (and retain their value) in the person’s CDP record.

3

Ignore

Using this strategy, no updates are applied to the existing person’s record in Ortto’s CDP, but a new person will be created if it doesn’t exist. If you do not wish to create a new person you need to provide the skip_non_existing to true.

0

Any (default)

Using this strategy, all merge_by fields are used in detecting an existing person to merge with. For example, assuming you have str::email and phn::phone as your two merge_by fields, and provide both fields in your request:

• Starting with the first merge_by field (in this case, str::email), try to find an existing person 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, phn::phone) to try and find a match, and if found, merge.
• If neither of the provided values find a match, then a new record would be created (depending on your merge_strategy)

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 had no value for the existing contact. For example, assuming you have str::email and phn::phone as your two merge_by fields, and provide both fields in your request:

• Starting with the first merge_by field (in this case, str::email), try to find an existing person match using that field, and if a match is found, merge.

If a match is not found using the first field, there are 2 scenarios that can happen:

1. There are no existing contacts who do not have a value for the first merge key (str::email). In this case the second field (phn::phone) is ignored and we do not check for a match.
2. There are existing contacts who do not have a value for the first merge key (str::email). In this case, because the first value is empty, we check the second merge key (phn::phone) for a match, and if a contact with no email address does match on phone number, we merge.

2

All

Using this strategy, all merge_by fields are used in detecting an existing person to merge with. For example, assuming you have str::email and phn::phone as your two merge_by fields, and provide both fields in your request:

• Try and find an existing person who has the same email AND phone number, and match with them.
• If a match is not found on both email and phone number, then a new contact will be created.

If only one of the merge_by fields are provided for the contact in the request, then we will just match on that single field against the existing contacts.