Getting Started with Iterable's API

You can use Iterable's REST API to interact with a project's users, templates, campaigns, journeys, and more.

This article describes how you can get started using Iterable's API.

# In this article

# TLS 1.2

To call Iterable's API, you must use a client that supports TLS 1.2.

# Authentication

To authenticate your request to Iterable's API, you can use a standard API key or a JWT-enabled key.

• Regular API keys: Include the key in an Api-Key or Api_Key header
• JWT-enabled keys: Follow the JWT authentication guide

# API keys

To authenticate your request, include an API key.

Each key is specific to one Iterable project and its associated data center, and has specific permissions assigned to it that determine what the key can and cannot do.

When creating an API key, use a key type that matches the permissions you need and is appropriate for the environment you're using the key in — server-side or client-side.

For detailed information about creating and managing API keys, their permissions, and which endpoints they can access, see API Keys.

# Base URLs

To call Iterable's API, use the base URL associated with the Iterable data center that hosts your project.

• USDC-based Iterable projects

  • Base URL: https://api.iterable.com
  • Example: https://api.iterable.com/api/events/track

• EDC-based Iterable projects

  • Base URL: https://api.eu.iterable.com
  • Example: https://api.eu.iterable.com/api/events/track

# API endpoints

Iterable's API endpoints are organized based on the resources they interact with. For a complete list of Iterable's endpoints and usage information, see Iterable API Endpoints and Sample Payloads. Reference this article to learn how you can use each of Iterable's endpoints, find implementation guidance with functional descriptions, and view sample requests and responses.

# API reference and testing

As an additional resource, Iterable provides an interactive API reference that includes detailed technical specifications for each API endpoint. You can use this resource to get complete schema information, rate limits, and additional technical information not included in Iterable API Endpoints and Sample Payloads.

Make sure to access the API reference docs for the Iterable data center that hosts your project:

• USDC-based Iterable projects: https://api.iterable.com/api/docs
• EDC-based Iterable projects: https://api.eu.iterable.com/api/docs

You can also send live API calls by entering a valid API key in the Authentication Header input in the API reference docs. Making an API call from the API reference isn't a mock call — it affects project data. If you're just testing, remember to use a project dedicated to testing or development.

# Rate limits

Iterable's API has rate limits in place to prevent abuse and ensure fair usage. The rate limits are published for the endpoints they apply to in the API reference docs.

# Handling rate limit errors

When you hit a rate limit, you will receive a 429 HTTP status code. To handle rate limit errors, implement an exponential backoff policy for retries.

# How rate limits are applied

Iterable endpoints have rate limits where noted in the API reference docs. These rate limits are applied to each endpoint in one of the following ways:

• Per project
• Per API key
• Per organization

Each endpoint with a rate limit will note which type of rate limit applies in the endpoint description.

# Per project

Some endpoints have rate limits that apply per project. This means that if you have multiple API consumers, they share the rate limit for the same endpoint.

For example, if you have an integration tracking events at the same time that Smart Ingest is syncing events, they share the rate limit for the POST /api/events/track endpoint and use from each source is additive.

# Per API key

Some endpoints have rate limits that apply per API key. This means that if you have multiple API consumers, they do not share the rate limit or compete for resources unless they share the same API key.

# Per organization

Some rate limits are applied per organization. Rate limits per organization are additive for requests across all projects in the organization. For example, the asynchronous export endpoint, POST /api/export/start, has a rate limit that considers requests from API keys for the entire organization.

# API responses

Many of Iterable's API endpoints return a content type of application/json with a JSON response body, however, some endpoints return a different content type, such as text/csv.

Iterable's API returns standard HTTP status codes to indicate the success or failure of a request. To learn more about Iterable's response codes, read API Response Codes.

# API response schemas

API responses vary based on the endpoint and are subject to change without prior notice.

# Data types

Iterable's API supports a variety of data types. When you send data to an existing field, Iterable validates the data types you send against the data types that Iterable expects. When you send data to a new field, Iterable automatically sets the data type of the field to the type of the first value you provide for it.

To learn about the data types that Iterable supports, read Field Data Types.

To learn more about viewing and managing your project's data schema, read Data Schema Management.

# Race conditions

Race conditions occur when multiple API requests attempt to modify the same data simultaneously, leading to unpredictable results, data loss, or inconsistent states. In Iterable's API, this can happen when:

• Multiple processes update the same user profile at the same time.
• New field names are being processed while data is being sent to those fields.
• Campaigns are triggered immediately after user updates.
• Other scenarios of simultaneous and near-simultaneous updates.

These conditions exist because of processing delays and the distributed nature of Iterable's systems, which require time to synchronize changes across different components.

# Avoiding race conditions when creating new fields

There's a slight processing delay when Iterable ingests a new field name. This creates the possibility of race conditions that may result in data loss. This may happen when a second API request is made in quick succession after the first.

For best results, allow a five-minute buffer after adding a new field before you start using it.

# Avoiding race conditions when updating users

When making multiple API calls to update the same user in quick succession, race conditions can occur that may result in data loss or inconsistent user profiles. This is particularly important when updating user data fields, subscriptions, or other user attributes.

To prevent race conditions with user updates:

• Allow at least 60 seconds between updates to the same user or before sending a campaign to the user based on the update.
• Use batch operations when possible to update multiple fields in a single request.
• Implement retry logic with exponential backoff if you receive error responses.
• Avoid concurrent updates to the same user from multiple processes or threads.

For best results, implement proper sequencing of user updates and avoid making rapid successive calls to update the same user profile.

# Identifying users in API requests

Many of Iterable's API endpoints require you to identify specific users (for example, to modify their user profile or fetch data about them). The method for identifying users varies based on your project type.

For complete information about identifying and creating users with Iterable's APIs, including detailed examples, validation rules, and project-specific behavior, read Creating and Identifying Users with Iterable APIs.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

• Foundations: Introduction to API

Support docs

• API Keys
• API Endpoints and Sample Payloads
• API Response Codes
• Creating and Identifying Users with Iterable APIs
• Responding to GDPR Requests