{"article":{"id":41044692130196,"url":"https://iterable.zendesk.com/api/v2/help_center/en-us/articles/41044692130196.json","html_url":"https://support.iterable.com/hc/en-us/articles/41044692130196-Getting-Started-with-Iterable-s-API","author_id":5490936793748,"comments_disabled":true,"draft":false,"promoted":false,"position":0,"vote_sum":0,"vote_count":0,"upvote_count":0,"downvote_count":0,"section_id":360008913351,"created_at":"2025-09-08T23:44:16Z","updated_at":"2026-10-06T19:52:02Z","name":"Getting Started with Iterable's API\n","title":"Getting Started with Iterable's API\n","source_locale":"en-us","locale":"en-us","outdated":false,"outdated_locales":[],"edited_at":"2026-10-06T19:52:02Z","user_segment_id":null,"permission_group_id":149426,"content_tag_ids":[],"label_names":[],"body":"<main class=\"page\"> <div class=\"theme-default-content content__default\"> <p>You can use Iterable's REST API to interact with a project's users, templates, campaigns, journeys, and more.</p> <p>This article describes how you can get started using Iterable's API.</p> <h2 id=\"in-this-article\">\n<a href=\"#in-this-article\" class=\"header-anchor\">#</a> In this article</h2> \n<div class=\"table-of-contents\"><ul>\n\n<li><a href=\"#tls-1-2\">TLS 1.2</a></li>\n<li>\n<a href=\"#authentication\">Authentication</a><ul><li><a href=\"#api-keys\">API keys</a></li></ul>\n</li>\n<li><a href=\"#base-urls\">Base URLs</a></li>\n<li>\n<a href=\"#api-endpoints\">API endpoints</a><ul><li><a href=\"#api-explorer\">API Explorer</a></li></ul>\n</li>\n<li>\n<a href=\"#rate-limits\">Rate limits</a><ul>\n<li><a href=\"#handling-rate-limit-errors\">Handling rate limit errors</a></li>\n<li><a href=\"#how-rate-limits-are-applied\">How rate limits are applied</a></li>\n</ul>\n</li>\n<li>\n<a href=\"#api-responses\">API responses</a><ul><li><a href=\"#api-response-schemas\">API response schemas</a></li></ul>\n</li>\n<li><a href=\"#data-types\">Data types</a></li>\n<li>\n<a href=\"#race-conditions\">Race conditions</a><ul>\n<li><a href=\"#avoiding-race-conditions-when-creating-new-fields\">Avoiding race conditions when creating new fields</a></li>\n<li><a href=\"#avoiding-race-conditions-when-updating-users\">Avoiding race conditions when updating users</a></li>\n</ul>\n</li>\n<li><a href=\"#identifying-users-in-api-requests\">Identifying users in API requests</a></li>\n<li><a href=\"#want-to-learn-more\">Want to learn more?</a></li>\n</ul></div>\n <h2 id=\"tls-1-2\">\n<a href=\"#tls-1-2\" class=\"header-anchor\">#</a> TLS 1.2</h2> <p>To call Iterable's API, you must use a client that supports TLS 1.2.</p> <h2 id=\"authentication\">\n<a href=\"#authentication\" class=\"header-anchor\">#</a> Authentication</h2> <p>To authenticate your request to Iterable's API, you can use a standard API key\nor a JWT-enabled key.</p> <ul>\n<li>\n<strong>Regular API keys</strong>: Include the key in an <code>Api-Key</code> or <code>Api_Key</code> header</li> <li>\n<strong>JWT-enabled keys</strong>: Follow the <a href=\"https://support.iterable.com/hc/articles/360050801231\">JWT authentication guide</a>\n</li>\n</ul> <h3 id=\"api-keys\">\n<a href=\"#api-keys\" class=\"header-anchor\">#</a> API keys</h3> <p>To authenticate your request, include an API key.</p> <p>Each key is specific to one Iterable project and its associated data center,\nand has specific permissions assigned to it that determine what the key can and\ncannot do.</p> <p>When creating an API key, use a key type that matches the permissions you need\nand is appropriate for the environment you're using the key in — server-side\nor client-side. If you need to know which API key type(s) are required to call\nan endpoint, you can check the <a href=\"#api-explorer\">API Explorer</a>.</p> <div class=\"custom-block warning\">\n<p class=\"custom-block-title\">IMPORTANT</p> <p>Don't use server-side API keys in client-side (web, mobile, or otherwise) code.</p>\n</div> <p>For detailed information about creating and managing API keys, their\npermissions, and which endpoints they can access, see <a href=\"https://support.iterable.com/hc/articles/360043464871\">API Keys</a>.</p> <h2 id=\"base-urls\">\n<a href=\"#base-urls\" class=\"header-anchor\">#</a> Base URLs</h2> <p>To call Iterable's API, use the base URL associated with the Iterable data\ncenter that hosts your project.</p> <ul>\n<li>\n<p>USDC-based Iterable projects</p> <ul>\n<li>Base URL: <code>https://api.iterable.com</code>\n</li> <li>Example: <code>https://api.iterable.com/api/events/track</code>\n</li>\n</ul>\n</li> <li>\n<p><a href=\"https://support.iterable.com/hc/articles/17572750887444\">EDC-based</a> Iterable\nprojects</p> <ul>\n<li>Base URL: <code>https://api.eu.iterable.com</code>\n</li> <li>Example: <code>https://api.eu.iterable.com/api/events/track</code>\n</li>\n</ul>\n</li>\n</ul> <h2 id=\"api-endpoints\">\n<a href=\"#api-endpoints\" class=\"header-anchor\">#</a> API endpoints</h2> <p>Iterable's API endpoints are organized based on the resources they interact\nwith. For a complete list of Iterable's endpoints and usage information, see\n<a href=\"https://support.iterable.com/hc/articles/204780579\">Iterable API Endpoints and Sample Payloads</a>.\nReference this article to learn how you can use each of Iterable's endpoints,\nfind implementation guidance with functional descriptions, and view sample\nrequests and responses.</p> <h3 id=\"api-explorer\">\n<a href=\"#api-explorer\" class=\"header-anchor\">#</a> API Explorer</h3> <p>As an additional resource, Iterable provides the API Explorer, an interactive\nreference that includes detailed technical specifications for each API endpoint.\nYou can use it to get complete schema information, rate limits, the API key\ntype(s) required for each endpoint, and additional technical information not\nincluded in <a href=\"https://support.iterable.com/hc/articles/204780579\">Iterable API Endpoints and Sample Payloads</a>.</p> <p>Make sure to open the API Explorer for the Iterable data center that hosts your\nproject:</p> <ul>\n<li>USDC-based Iterable projects: <a href=\"https://api.iterable.com/api/docs\" target=\"_blank\" rel=\"noopener noreferrer\">https://api.iterable.com/api/docs</a>\n</li> <li>EDC-based Iterable projects: <a href=\"https://api.eu.iterable.com/api/docs\" target=\"_blank\" rel=\"noopener noreferrer\">https://api.eu.iterable.com/api/docs</a>\n</li>\n</ul> <p>You can also send live API calls by entering a valid API key in the\nAuthentication Header input in the API Explorer. Making an API call from\nthe API Explorer isn't a mock call — it <em>affects project data</em>. If you're just\ntesting, remember to use a project dedicated to testing or development.</p> <h2 id=\"rate-limits\">\n<a href=\"#rate-limits\" class=\"header-anchor\">#</a> Rate limits</h2> <p>Iterable's API has rate limits in place to prevent abuse and ensure fair usage.\nThe rate limits are published for the endpoints they apply to in the <a href=\"#api-explorer\">API Explorer</a>.</p> <div class=\"custom-block warning\">\n<p class=\"custom-block-title\">IMPORTANT</p> <p>Beginning November 10, 2025, API calls that provide the key in the query string\nor request body will be subject to <strong>stricter rate limiting</strong>. This change only\nimpacts legacy projects with exceptions to make API calls using the query\nstring or request body. To learn more, see <a href=\"https://support.iterable.com/hc/articles/360043464871#providing-api-keys-in-http-requests\">API Keys</a>.</p>\n</div> <h3 id=\"handling-rate-limit-errors\">\n<a href=\"#handling-rate-limit-errors\" class=\"header-anchor\">#</a> Handling rate limit errors</h3> <p>When you hit a rate limit, you will receive a <a href=\"https://support.iterable.com/hc/articles/39629320560148#_429\">429 HTTP status code</a>.\nTo handle rate limit errors, implement an exponential backoff policy for\nretries.</p> <h3 id=\"how-rate-limits-are-applied\">\n<a href=\"#how-rate-limits-are-applied\" class=\"header-anchor\">#</a> How rate limits are applied</h3> <p>Iterable endpoints have rate limits where noted in the API Explorer.\nThese rate limits are applied to each endpoint in one of the following ways:</p> <ul>\n<li>Per project</li> <li>Per API key</li> <li>Per organization</li>\n</ul> <p>Each endpoint with a rate limit will note which type of rate limit applies in\nthe endpoint description.</p> <h4 id=\"per-project\">\n<a href=\"#per-project\" class=\"header-anchor\">#</a> Per project</h4> <p>Some endpoints have rate limits that apply per project. This means that if you\nhave multiple API consumers, they share the rate limit for the same endpoint.</p> <p>For example, if you have an integration tracking events at the same time that\nSmart Ingest is syncing events, they share the rate limit for the\n<a href=\"https://support.iterable.com/hc/articles/204780579#post-api-events-track\"><code>POST /api/events/track</code></a>\nendpoint and use from each source is additive.</p> <h4 id=\"per-api-key\">\n<a href=\"#per-api-key\" class=\"header-anchor\">#</a> Per API key</h4> <p>Some endpoints have rate limits that apply per API key. This means that if you\nhave multiple API consumers, they do not share the rate limit or compete for\nresources unless they share the same API key.</p> <h4 id=\"per-organization\">\n<a href=\"#per-organization\" class=\"header-anchor\">#</a> Per organization</h4> <p>Some rate limits are applied per organization. Rate limits per organization are\nadditive for requests across all projects in the organization. For example, the\nasynchronous export endpoint, <a href=\"https://support.iterable.com/hc/articles/204780579#post-api-export-start\"><code>POST /api/export/start</code></a>,\nhas a rate limit that considers requests from API keys for the entire\norganization.</p> <h2 id=\"api-responses\">\n<a href=\"#api-responses\" class=\"header-anchor\">#</a> API responses</h2> <p>Many of Iterable's API endpoints return a content type of <code>application/json</code>\nwith a JSON response body, however, some endpoints return a different content\ntype, such as <code>text/csv</code>.</p> <p>Iterable's API returns standard HTTP status codes to indicate the success or\nfailure of a request. To learn more about Iterable's response codes, read\n<a href=\"https://support.iterable.com/hc/articles/39629320560148\">API Response Codes</a>.</p> <h3 id=\"api-response-schemas\">\n<a href=\"#api-response-schemas\" class=\"header-anchor\">#</a> API response schemas</h3> <p>API responses vary based on the endpoint and are subject to change without\nprior notice.</p> <div class=\"custom-block warning\">\n<p class=\"custom-block-title\">IMPORTANT</p> <p>Iterable may occasionally <em>add</em> fields to API response bodies without prior\nnotice. Make sure that any dependencies you have on Iterable's APIs don't\nbreak if and when new fields are <em>added</em>.</p> <p>Iterable won't <em>rename</em> or <em>remove</em> existing, documented fields from an API\nresponse body without prior communication.</p>\n</div> <h2 id=\"data-types\">\n<a href=\"#data-types\" class=\"header-anchor\">#</a> Data types</h2> <p>Iterable's API supports a variety of data types. When you send data to an\nexisting field, Iterable validates the data types you send against the data\ntypes that Iterable expects. When you send data to a new field, Iterable\nautomatically sets the data type of the field to the type of the first value\nyou provide for it.</p> <p>To learn about the data types that Iterable supports, read <a href=\"https://support.iterable.com/hc/articles/208183076\">Field Data Types</a>.</p> <p>To learn more about viewing and managing your project's data schema, read\n<a href=\"https://support.iterable.com/hc/articles/26678893969812\">Data Schema Management</a>.</p> <h2 id=\"race-conditions\">\n<a href=\"#race-conditions\" class=\"header-anchor\">#</a> Race conditions</h2> <p>Race conditions occur when multiple API requests attempt to modify the same\ndata simultaneously, leading to unpredictable results, data loss, or\ninconsistent states. In Iterable's API, this can happen when:</p> <ul>\n<li>Multiple processes update the same user profile at the same time.</li> <li>New field names are being processed while data is being sent to those fields.</li> <li>Campaigns are triggered immediately after user updates.</li> <li>Other scenarios of simultaneous and near-simultaneous updates.</li>\n</ul> <p>These conditions exist because of processing delays and the distributed nature\nof Iterable's systems, which require time to synchronize changes across\ndifferent components.</p> <h3 id=\"avoiding-race-conditions-when-creating-new-fields\">\n<a href=\"#avoiding-race-conditions-when-creating-new-fields\" class=\"header-anchor\">#</a> Avoiding race conditions when creating new fields</h3> <p>There's a slight processing delay when Iterable ingests a new field name.\nThis creates the possibility of race conditions that may result in data loss.\nThis may happen when a second API request is made in quick succession after the\nfirst.</p> <p>For best results, allow a five-minute buffer after adding a new field before\nyou start using it.</p> <h3 id=\"avoiding-race-conditions-when-updating-users\">\n<a href=\"#avoiding-race-conditions-when-updating-users\" class=\"header-anchor\">#</a> Avoiding race conditions when updating users</h3> <p>When making multiple API calls to update the same user in quick succession,\nrace conditions can occur that may result in data loss or inconsistent user\nprofiles. This is particularly important when updating user data fields,\nsubscriptions, or other user attributes.</p> <p>To prevent race conditions with user updates:</p> <ul>\n<li>\n<strong>Allow at least 60 seconds</strong> between updates to the same user or before\nsending a campaign to the user based on the update.</li> <li>\n<strong>Use batch operations</strong> when possible to update multiple fields in a single\nrequest.</li> <li>\n<strong>Implement retry logic</strong> with exponential backoff if you receive error\nresponses.</li> <li>\n<strong>Avoid concurrent updates</strong> to the same user from multiple processes or\nthreads.</li>\n</ul> <p>For best results, implement proper sequencing of user updates and avoid making\nrapid successive calls to update the same user profile.</p> <h2 id=\"identifying-users-in-api-requests\">\n<a href=\"#identifying-users-in-api-requests\" class=\"header-anchor\">#</a> Identifying users in API requests</h2> <p>Many of Iterable's API endpoints require you to identify specific users (for\nexample, to modify their user profile or fetch data about them). The method for\nidentifying users varies based on your project type.</p> <p>For complete information about identifying and creating users with Iterable's\nAPIs, including detailed examples, validation rules, and project-specific\nbehavior, read <a href=\"https://support.iterable.com/hc/articles/29156459027348\">Creating and Identifying Users with Iterable APIs</a>.</p> <h2 id=\"want-to-learn-more\">\n<a href=\"#want-to-learn-more\" class=\"header-anchor\">#</a> Want to learn more?</h2> <p>For more information about some of the topics in this article, check out these\nresources. Iterable Academy is open to everyone—you don't need to be an\nIterable customer!</p> <p><strong>Iterable Academy</strong></p> <ul><li><a href=\"https://academy.iterable.com/learn/courses/36/foundations-introduction-to-api\" target=\"_blank\" rel=\"noopener noreferrer\">Foundations: Introduction to API</a></li></ul> <p><strong>Support docs</strong></p> <ul>\n<li><a href=\"https://support.iterable.com/hc/articles/360043464871\">API Keys</a></li> <li><a href=\"https://support.iterable.com/hc/articles/204780579\">API Endpoints and Sample Payloads</a></li> <li><a href=\"https://support.iterable.com/hc/articles/39629320560148\">API Response Codes</a></li> <li><a href=\"https://support.iterable.com/hc/articles/29156459027348\">Creating and Identifying Users with Iterable APIs</a></li> <li><a href=\"https://support.iterable.com/hc/articles/360029174171\">Responding to Data Subject Requests</a></li>\n</ul>\n</div>   </main>","user_segment_ids":[]}}