Developer guide

Overview

The Ortto Developer Guide helps you get started with the Ortto API. It includes use-case examples and best practices for how your applications can interact with Ortto across all available API functions.

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.

Tools

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 include callouts (explanations shown below the code).

If you copy the code using the copy icon or by selecting it manually, these callouts might also be copied, sometimes as extra spaces or line breaks.

This can cause issues when pasting the code into a terminal or console, especially with cURL commands.

To avoid errors, double-check and clean up the code before using it.

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.

Use-case guidelines

• Creating and updating people
  • Configuring people’s subscription permissions
  • Tagging and untagging people
• Retrieving people’s data
  • Retrieving data from a single person
• Creating and updating accounts (previously organizations)
• Adding and removing people from accounts (previously organizations)
• Custom activities guide
• Custom activities guide (website)
• Rate limits
• List of timezones
• List of languages
• Geo location
• Email subscription permission from activities
• Archiving and deleting people
• Using the API to send emails
• Using the API to send SMS messages
• Push notifications for Android and iOS
• Create a verified Talk session
• Talk messenger methods