What is the API?

The Dotdigital API is a family of REST web services that provides programmatic access to a huge range of Dotdigital's functionality.

The API allows you to automate many everyday tasks you might otherwise have to carry out manually, and send real-time messages to your customers across a wide array of channels. This is useful if you want to increase your productivity within the Dotdigital, and enhance your customer engagement.

You can use the API to connect almost any system to Dotdigital. Provided your CRM, website or any back office system also has an API, then it can be quickly connected, allowing you to keep your data easily in sync. Data can be imported and exported on a schedule, and most common tasks available in Dotdigital can be automated using the API.

We provide omnichannel messaging and transactional email APIs to send messages from your systems or applications to engage and serve your customers. You can send to any messaging or notification channel like SMS, Facebook Messenger, WhatsApp, in-app messaging or push notifications, and more... all through one simple API.

API Functional areas

The API has the following major functional areas:

• Accounts and utilities - calls that manage or get details about your Dotdigital account and that provide utility functions for you.
• Contacts and data - calls that allow you to manage your contacts and associated additional data.
• Insight data - calls that allow you to create, read, update and delete Insight data.
• Marketing and automation - calls to support marketing campaigns, pages and forms and automation programs.
• Communications - real-time high volume transactional communications across a variety of channels.

The following diagrams show additional details of the available methods in the functional areas:

Accounts and utilities

Contacts and data

Insight data

Marketing and automation

Communications

📘

API training videos

To learn more about our API and its common uses, check out our API training videos here

API Versions

Our API functionality is delivered over a range of services which are either implemented on our v2 API framework or v3 API framework. Both API frameworks are RESTful and are secured using the same API users, but do differ slightly in their capabilities and calling conventions.

With the launch of unified contacts we have started to introduce our v3 services that are specifically designed to work with unified contacts and use the latest industry best practices for RESTful services.

You are likely to require a combination of v2 and v3 services to achieve your integration goals, however we would encourage the use of the v3 services wherever possible due to the advantages they offer.

What are the key differences?

The key differences in v3 services are as follows:

• They support referring to contacts using your specified identifier type; choose from contact id, email or phone number.
• They use a slightly different pagination mechanism; see API conventions for more details.
• They use a different error response that provides more information in both human and machine readable formats; see API conventions for more details.

How to identify if a call is on v2 or v3

It's simple to identify if a call is provided by a v2 or v3 service by looking at the calls URI. If the URI contains /v2/ it is provided by an API v2 service, and if the URI contains /v3/ then it is provided by a API v3 service.

Example: API v2 service URI

https://r1-api.dotdigital.com/v2/contacts/with-consent-and-preferences

Example: API v3 service URI

https://r1-api.dotdigital.com/contacts/v3

Setting up your API user

To get started using our API, you need to create an API user. These API user credentials (username and password) are required to authenticate each operation/method call you make and to make sure you are connected to the correct account. Setting up an API user is a simple process.

📘

User permissions

To create an API user, you must be an account owner, or a managed user with the Can manage account permission enabled.

To create an API user:

1. Log in to Dotdigital with your normal login credentials.
2. Select Settings ( ⋮ ), and go to Access > API users.

3. Select NEW USER.

4. The username (email address) is automatically generated for you and must not be edited. You can add a description to differentiate between API users, which is useful if you have more than one.

5. Enter a password and confirm it. Your password must be at least eight characters in length and contain at least one digit or non-alphanumeric character. Please avoid including your email address or company name as part of your password.
6. For Status, select Enabled.
7. Select SAVE.

📘

Find out more about API User management

If you want to know more about API user management, check out our guide in the Help Centre.

You can only access the API using your API user credentials, although you can have more than one API user per Dotdigital account.

Please note: When creating API users, it's best practice to create one user per system (for instance, one for a Magento integration and another one for a Dynamics integration) and not share an API user for different integrations. This makes it easier to revoke individual API users should you need to, as well as isolate and diagnose problems with integrations.