Creating and updating people

Learn how to use the Ortto API to create new and update existing people's records in your Ortto account’s customer data platform (CDP) through the examples on this page.

Requests to create new and/or update people’s records in your Ortto CDP are submitted as a single POST method call to the following URL:

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

People (in a given request) are either created or updated in the CDP based on the merge_by and merge strategy values submitted in the same request.

Each copyable code example on this page is annotated with callouts along with associated explanations.

cURL example

cURL example request to create and/or update people in the Ortto CDP
curl --request POST 'https://api.ap3api.com/v1/person/merge' \ (1)
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \ (2)
     --header 'Content-Type: application/json' \
     --data-raw '{
        "people": [
          { (3)
            "fields": {
              "str::first": "Chris",
              "str::last": "Smith",
              "str::email": "chris.smith@example.com",
              "str:cm:job-title": "Technician" (4)
            },
            "location": {
              "source_ip": "119.18.0.218"
            }
          },
          { (5)
            "fields": {
              "str::first": "Alex",
              "str::email": "alex@example.com"
            },
            "location": {
              "source_ip": "119.18.0.218"
            }
          }
        ],
        "async": false,
        "merge_by": [ "str::ei", "str::email" ], (6)
        "merge_strategy": 2, (7)
        "find_strategy": 0
      }'
1 The API endpoint for creating and updating people in Ortto.
2 The custom API key configured as part of the getting started process.
3 The first people array object containing a person’s data (as person fields) to be created or updated in your Ortto account’s CDP.
If this person exists in the CDP and their email address matches the str::email value, determined by one of the merge_by field values in this request (), then this person’s record is updated in the CDP, using the default merge_strategy value of 2 (Overwrite existing). For instance, if this person’s last name (str::last) value was either empty or had the value "Johnson", then after submitting this request, the person’s last name value would be "Smith".
Person fields referenced throughout the Ortto API follow a strongly-typed, namespace-specific naming convention. Learn more about this in Person field ID format of the API reference docs.
4 An example of how to work with a person custom field, whose data can be updated or added, depending on whether or not (respectively) this person exists in the CDP.
Learn more about working with custom fields in the User guide, and how to derive their field IDs in the API reference docs.
5 The second people array object containing a person’s data to be created or updated in your Ortto account’s CDP.
If this person does not exist in the CDP and their email address does not match the str::email value (determined by the merge_by field value in this request), then this person’s record is created in the CDP.
Up to 100 people array objects can be included in a single request.
6 The merge_by field value/s in this request, which can be used to override the Merge strategy main and fallback associations configured for your custom API key. When this member is present and contains two values, the first value is the main association field, and the second is the fallback. If this member is not specified in the request, the Merge strategy associations configured for your custom API key in this request () are used instead.
7 The actual merge strategy, which can be used to override the default value of 2 (Overwrite existing). If this member is not specified in the request, then the default value of 2 (Overwrite existing) is used instead.

Node.js example

Node.js example of the same cURL request (described above) to create and/or update people in the CDP
const people = [
  { (3)
    "fields": {
      "str::email": "chris.smith@example.com",
      "str::first": "Chris",
      "str::last": "Smith",
      "str:cm:job-title": "Technician" (4)
    },
    "location": {
      "source_ip": "119.18.0.218"
    }
  },
  { (5)
    "fields": {
      "str::email": "alex@example.com",
      "str::first": "Alex"
    },
    "location": {
      "source_ip": "119.18.0.218"
    }
  }
];

const data = {
  people,
  "async": false,
  "merge_by": ["str::ei", "str::email"], (6)
  "merge_strategy": 2, (7)
  "find_strategy": 0
};

request({
  url: 'https://api.ap3api.com/v1/person/merge', (1)
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR-CUSTOM-API-KEY', (2)
    'Content-Type': 'application/json'
  },
  json: data
}, (err, resp, body) => {
  console.log("API response:", body);
});