Creating and updating organizations

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

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


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

Organizations (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 organizations in the Ortto CDP

shell
 curl --location\
     --request POST 'https://api.ap3api.com/v1/organizations/merge' \ <1>
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \ <2>
     --header 'Content-Type: application/json' \
     --data-raw '{
        "organizations": [
          { <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 organizations in Ortto.
2	The custom API key configured as part of the getting started process.
3	The first `organizations` array object containing an organization’s data (as organization fields) to be created or updated in your Ortto account’s CDP. If this organization 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 organization’s record is updated in the CDP, using the default `merge_strategy` value of `2` (Overwrite existing). For instance, if this organization’s employees (`int:o:employees`) value was either empty or had the value `50`, then after submitting this request, the organization’s employee value would be `60`. Organization fields referenced throughout the Ortto API follow a strongly-typed, namespace-specific naming convention. Learn more about this in Organization field ID format of the API reference docs.
4	The second `organizations` array object containing an organization’s data to be created or updated in your Ortto account’s CDP. If this organization 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 organization’s record is created in the CDP. NOTE: Up to 100 `organizations` array objects can be included in a single request.
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 organizations in the CDP

javascript
 const organizations = [
  { <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 = {
  organizations,
  "async": false,
  "merge_by": [ "str:o:name" ], <5>
  "merge_strategy": 2, <6>
  "find_strategy": 0
};

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