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

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