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

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

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

shell
 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. NOTE: Up to 100 `people` array objects can be included in a single request. Person fields that have a value of `0` or `""` will be returned as results in a search using the has any value filter condition. Learn more about empty values.
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

javascript
 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);
});