Developer guide

The Ortto developer guide shows you how to start interacting with the Ortto API, and provides use-case guidelines on how your own applications can interact with Ortto to perform all possible interactions with the Ortto API.

Getting started

Ortto requires your application to interact with the Ortto API using a custom API key. This key is required to authenticate every request made to the Ortto API. Without this key, all requests are automatically rejected.

Each custom API key:

  • is unique and tied to a single Ortto account (aka Ortto instance),
  • does not require or involve any user authentication, but in itself, the key should be treated as a private key,
  • contains its own configurable default merge_by settings, when updating one or more people via the Ortto API, and
  • which is configured as a data source, can be disconnected at any time through your Ortto account’s user interface (UI), thereby preventing and rejecting any requests made to the Ortto API until the custom API key is reconnected.

Therefore, create a separate custom API key for each application that will interact with your appropriate Ortto account.


The code examples used throughout this Developer guide are presented as cURL commands, along with equivalent Node.js/JavaScript implementations.

You can work directly with the Ortto API using the cURL command. Learn more about using cURL from the curl website and its documentation and man page reference guide.

Copying code examples

Some code examples contain code callouts that provide annotated explanations, usually appearing immediately underneath the code blocks themselves.

If you manually copy and paste such code examples by clicking the copy icon or by clicking and dragging with your cursor to select the code then using your keyboard or mouse to copy and paste the text, any callouts in the code you copied may also be copied as extra space or line break characters.

These extra characters can cause issues with the execution of the code after pasting it directly into console/terminal windows; this is especially true of the cURL code examples throughout these developer docs.

API methods and endpoints

The relevant method and URL for each available API endpoint will be listed on each page, in the introduction and/or within the copyable code examples.

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:
  • Europe:

For example:

All other Ortto users will use the default service endpoint (

Use-case guidelines