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 | |
2 | The custom API key configured as part of the getting started process. |
3 | The first |
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 NOTE:
|
6 | The |
7 | The actual merge strategy, which can be used to override the default value of |
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); });