Basics & Fundamentals

The basics

The Docs Marketing API provides programmatic access to Docs data and functionality, allowing developers to build custom features to do things like sync email activity and campaign analytics with their database, manage audiences and campaigns, and more.

To use the Docs API, you need a Docs account. What you can do with the API depends on what level of Docs plan you have. Once you have an account and are logged in, you can get an API key and begin making calls to the API.

Using Docs

Whether you're managing your own campaigns, providing Docs services to your customers or clients, or writing a mobile app, the Docs Marketing API has features to manage and sync your contact data.

You can also use the Docs API to handle data in different ways for different purposes. If you are syncing a large amount of data with Docs, you can use batches to avoid hitting the API request limits. For building integrations that let other users access data from their own Docs accounts, you should authenticate with OAuth 2. And if you're developing an app for iOS or Android, the Mobile SDK provides an easy way to work with a mobile-focused subset of the Docs API's functionality.

API structure

The Marketing API generally follows REST conventions, with some deviations.

• Resources are typically nouns like subscribers or campaigns.
• Subresources can be multiply nested under resources.
• Actions are usually represented by HTTP methods.
• Responses use the generic JSON content type.

We use the API Specification to describe each endpoint. The API self-description also contains type information to help you error-check your requests.

The root url for the API is https://<dc>.api.docs.com/3.0/. The <dc> part of the URL corresponds to the data center for your account. For example, if the data center for your account is us6, all API endpoints for your account are available relative to https://us6.api.docs.com/3.0/.

There are a few ways to find your data center. It's the first part of the URL you see in the API keys section of your account; if the URL is https://us6.docs.com/account/api/, then the data center subdomain is us6. It's also appended to your API key in the form key-dc; if your API key is 0123456789abcdef0123456789abcde-us6, then the data center subdomain is us6. And finally, if you're connecting via OAuth 2, you can find the data center associated with the token via the OAuth Metadata endpoint; for more information, see the OAuth guide.

Connecting to the API

You can authenticate requests using either your API key or an OAuth access token, depending on your use case. You should use an API key if you're writing code that tightly couples your application data to your Docs account data; if you ever need to access someone else's Docs account data, you should use OAuth 2.

For more information on the Docs OAuth 2 flow, see Access Data on Behalf of Other Users with OAuth 2.

If you're integrating with the Docs API using one of the official client libraries, you won't need to worry about the implementation details for authentication.

Authenticate with an API key or OAuth 2 token

API keys and OAuth 2 tokens can be used to make authenticated requests the same way. We'll refer to both as tokens.

You can either use HTTP Basic Authentication or Bearer Authentication.

HTTP Basic Authentication:

curl --request GET \

--url 'https://<dc>.api.docs.com/3.0/' \

--user 'anystring:TOKEN

API limits

To improve the experience for all our users, we impose some limits on API requests. These limits prevent a single user from making too many expensive calls at once. Exceeding the limits can result in your API access being disabled, so be cognizant of the quantity and complexity of your requests. Currently there are no options to raise the limit on a per-customer basis.

Throttling

The Marketing API has a limit of 10 simultaneous connections. You'll receive a 429 error if you reach the limit. At exceptionally high volumes, you may receive an HTTP 429 or 403 without a JSON body.

We recommend that you cache frequently accessed values that do not change often in your application's data store. This will prevent your application from bumping up against the throttling limitations and will likely provide faster access to that data.

Stream timeouts

The Marketing API has a 120-second timeout on API calls. You may see this type of timeout after you've made a network socket connection and are already sending and receiving data.

Response times are dependent on the complexity of your request and the general load across Docs. Some endpoints in the Marketing API return values that are large and slow to calculate. Once you know what data you need, use the pagination and partial response capabilities to request only what is essential to you.