Creating and updating accounts (previously organizations)

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

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


 https://api.ap3api.com/v1/accounts/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/).

Accounts (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 accounts in the Ortto CDP

shell
 curl --location\
     --request POST 'https://api.ap3api.com/v1/accounts/merge' \ <1>
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \ <2>
     --header 'Content-Type: application/json' \
     --data-raw '{
        "accounts": [
          { <3>
            "fields": {
              "str:o:name": "Ortto",
              "int:o:employees": 60,
              "str:o:industry": "SaaS",
              "str:o:website": "https://ortto.com",
              "geo:o:city": {"name": "San Francisco"},
              "str:o:address": "1390 Market St",
              "geo:o:region": {"name": "California"},
              "geo:o:country": {"name": "United States"},
              "str:o:postal": "94102",
              "str:o:source": "API"
            }
          },
          { <4>
            "fields": {
              "str:o:name": "My Online Store",
              "int:o:employees": 200,
              "str:o:industry": "E-commerce",
              "str:o:website": "https://www.myonlinestore.studio",
              "geo:o:city": {"name": "San Francisco"},
              "str:o:address": "9000 O'Dea Ave",
              "geo:o:region": {"name": "California"},
              "geo:o:country": {"name": "USA"},
              "str:o:postal": "94123",
              "str:o:source": "API"
            }
          }
        ],
        "async": false,
        "merge_by": [ "str:o:name" ], <5>
        "merge_strategy": 2, <6>
        "find_strategy": 0
      }'

1	The API endpoint for creating and updating accounts in Ortto.
2	The custom API key configured as part of the getting started process.
3	The first `accounts` array object containing an accounts data (as accounts fields) to be created or updated in your Ortto account’s CDP. If this accounts exists in the CDP and its name matches the `str:o:name` value, determined by one of the `merge_by` field values in this request (), then this accounts record is updated in the CDP, using the default `merge_strategy` value of `2` (Overwrite existing). For instance, if this accounts employees (`int:o:employees`) value was either empty or had the value `50`, then after submitting this request, the accounts employee value would be `60`. Accounts fields referenced throughout the Ortto API follow a strongly-typed, namespace-specific naming convention. Learn more about this in Accounts field ID format of the API reference docs.
4	The second `accounts` array object containing an Accounts data to be created or updated in your Ortto account’s CDP. If this account does not exist in the CDP and its name does not match the `str:o:name` value (determined by the `merge_by` field value in this request), then this accounts record is created in the CDP. NOTE: Up to 100 `people` array objects can be included in a single request. Accounts 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.
5	The `merge_by` field value/s in this request.
6	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 accounts in the CDP

javascript
 const accounts = [
  { <3>
    "fields": {
      "str:o:name": "Ortto",
      "int:o:employees": 60,
      "str:o:industry": "SaaS",
      "str:o:website": "https://ortto.com",
      "geo:o:city": {"name": "San Francisco"},
      "str:o:address": "1390 Market St",
      "geo:o:region": {"name": "California"},
      "geo:o:country": {"name": "United States"},
      "str:o:postal": "94102",
      "str:o:source": "API"
    }
  },
  { <4>
    "fields": {
      "str:o:name": "My Online Store",
      "int:o:employees": 200,
      "str:o:industry": "E-commerce",
      "str:o:website": "https://www.myonlinestore.studio",
      "geo:o:city": {"name": "San Francisco"},
      "str:o:address": "9000 O'Dea Ave",
      "geo:o:region": {"name": "California"},
      "geo:o:country": {"name": "USA"},
      "str:o:postal": "94123",
      "str:o:source": "API"
    }
];

const data = {
  accounts,
  "async": false,
  "merge_by": [ "str:o:name" ], <5>
  "merge_strategy": 2, <6>
  "find_strategy": 0
};

request({
  url: 'https://api.ap3api.com/v1/accounts/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);
});