Create or update one or more people (merge)

The merge Autopilot endpoint of the person entity is used to create or update one or more people in Autopilot’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:

HTTP method and request resource

POST https://api.ap3api.com/v1/person/merge

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 Autopilot can recognize to create or update one or more people in your Autopilot account’s CDP.

Example create/update people in Autopilot’s CDP
{
  "people": [
    {
      "fields": {
        "str::email": "chris.smith@example.com",
        "str::first": "Chris",
        "str::last": "Smith"
      },
      "location": {
        "source_ip": "119.18.0.218"
      }
    },
    {
      "fields": {
        "str::email": "alex@example.com",
        "str::first": "Alex"
      },
      "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

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 Autopilot account’s CDP. Each of these objects can contain:

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 Autopilot account’s CDP.
This person is either created or updated in Autopilot’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 Autopilot’s CDP, then Autopilot creates this person as a new record.

  • Otherwise, if the person field member’s value does already match that of an existing person in Autopilot’s CDP, then Autopilot updates the fields of that person’s record in the Autopilot 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 Autopilot 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:

"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.

async

boolean

mergy_by

array of one or two string values

The merge_by element/s whose field ID values specify the person fields used to override the default person fields associated with the custom API key submitted in this request. These default values are defined by the Merge strategy associations configured for this custom API key.
If this 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 Autopilot 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 Autopilot’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 Autopilot’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, Autopilot creates a new person’s record in the 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 Autopilot’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 this merge_strategy element is not specified in the request, then this value is assumed to be 2 (Overwrite existing) by default.

find_strategy

integer

Person fields

In Autopilot, a person field:

  • contains the data for a specific piece of information (i.e. field) about each person in Autopilot’s CDP,

  • is referenced via the Autopilot API using a specific ID format,

  • could be a built in Autopilot 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 Autopilot’s API when creating or updating people in the CDP.

Field name (in product) field_id Example Description

First name

str::first

"str::first" : "Chris"

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

Last name

str::last

"str::last" : "Smith"

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

Phone number

phn::phone

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

A phone number 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.

Email

str::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 Autopilot’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

geo::city

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

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

Country

geo::country

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

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

Birthday

dtz::b

"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

geo::region

"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

"str::postal" : "90210"

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

External ID

str::ei

"str::ei" : "c533532fe5d16c7d4fa4c7f081514b0c"

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

"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

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

A boolean value where true flags that the person has their Email marketing permission set to true, and false flags that this person’s permission is set to false.
If this person field is not specified in the request, then this value is assumed to be true by default.

For this permission to be visible through the Autopilot user interface (UI), an audience must be created/available where the membership condition Email marketing permission is true.

Person field ID format

Since Autopilot integrates with many third-party products, references to person fields in Autopilot’s CDP are both strongly-typed and namespace-specific. Therefore, each person field is referenced by an ID (known as a field_id) based on the format:

  • type:namespace:field-name

For:

  • Autopilot’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 Autopilot, the namespace value is cm, 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 Autopilot account/instance.

Person field type abbreviations

The following person field type abbreviations are used to form the first part (type) of each person field’s ID:

Field type abbreviation Type of value

bol

Boolean

dtz

Date (object)

geo

Geographical data (object)

int

Integer.
For internal operations and calculations, the Autopilot API treats decimal values as integers multiplied by 1,000. This is done to preserve the precision of values resulting from these calculations.

phn

Phone number (object)

str

String

Merge strategy

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 Autopilot’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 Autopilot’s CDP are not changed. Autopilot 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 Autopilot’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 Autopilot’s CDP.

Use this merge strategy to enforce only adding new people to the CDP, leaving existing people’s records untouched.