Create or update one or more people (merge)
The merge
Ortto endpoint of the person
entity is used to create or update one or more person 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.
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 person records in your Ortto account’s CDP.
{
"people": [
{
"fields": {
"str::first": "Chris",
"str::last": "Smith",
"str::email": "chris.smith@example.com",
"str:cm:job-title": "Technician"
},
"location": {
"source_ip": "119.18.0.218"
}
},
{
"fields": {
"str::first": "Alex",
"str::email": "alex@example.com"
},
"location": {
"source_ip": "119.18.0.218",
}
}
],
"async": false,
"merge_by": ["str::email"],
"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
Between 1 to 100 people (each as individual objects of this |
Object containing person field members |
The object containing the fields for a person being created or updated in your Ortto account’s CDP.
|
|
Object containing location field data |
The |
|
|
Each |
|
|
Each
Therefore, a construct like:
would result in Tag2 and Tag3 being applied to this person. |
|
|
|
|
|
The When the value of the person field member (determined by the relevant 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. |
|
|
When the |
|
|
|
The Find strategy determines how the |
|
|
The 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):
|
Person fields
In Ortto, a person field:
-
contains the data for a specific piece of information (i.e. field) about each person 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 person (within their respective
fields : { … }
object) submitted in the request to this endpoint.
The following built-in person fields are accessible through Ortto’s API when creating or updating people in the CDP.
Field name (in product) | Field ID | Example | Description |
---|---|---|---|
First name |
|
|
A string whose value is this person’s first name. |
Last name |
|
|
A string whose value is this person’s last name. |
Phone number |
|
|
A phone number object of two members consisting of valid country code digits ( |
|
|
A string whose value is this person’s email address.
This person field and its value is commonly used as the main |
|
City |
|
|
A geographical data object consisting of a member |
Country |
|
|
A geographical data object consisting of a member |
Birthday |
|
|
A date object consisting of members |
Region |
|
|
A geographical data object consisting of a member |
Postal |
|
|
A string whose value is this person’s current postal code. |
|
|
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 |
|
GDPR |
|
|
A boolean value where |
|
|
A boolean value where |
|
|
|
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 |
|
|
|
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 |
|
|
|
A boolean value where |
|
|
|
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 |
|
|
|
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 |
|
Language |
|
|
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. |
Person field ID format
Each person field is referenced by an ID.
Since Ortto integrates with many third-party products, references to person fields in Ortto’s CDP are both strongly-typed and namespace-specific. Therefore, each person field’s ID is based on the format:
-
type:namespace:field-name
For:
-
Ortto’s own built-in person fields, the
namespace
value is unnecessary and is omitted. Hence, these built-in fields are referenced by an ID based on the format:-
type::field-name
-
-
Your own custom person fields in Ortto, the
namespace
value iscm
, and hence, these custom fields are referenced by an ID based on the format:-
type:cm:field-name
-
Up to 100 custom fields can be added to an Ortto account/instance.
-
The
field-name
for custom fields is typically based on their configured names converted to kebab-case.
-
Person field type abbreviations
The following person field type abbreviations are used to form the first part (type
) of each person field’s ID for built-in fields:
Field type abbreviation | Type of value |
---|---|
|
Boolean |
|
Date (object) |
|
Geographical data (object) |
|
Integer. |
|
Phone number (object) |
|
String |
Merge strategy
The merge strategy determines how a person’s existing field values are merged.
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 one of the following merge_strategy
values in the request determines how the person’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).
|
||
2 |
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.
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
|
Find strategy
The find strategy determines how the merge_by
fields are used to detect an existing person 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 person match:
find_strategy (integer) |
Strategy | Description |
---|---|---|
0 |
Using this strategy, all
|
|
1 |
Next only if previous empty |
Using this strategy, the first
If the first field is not provided for a person in the request, only then will the second field be used to detect a match. |