CINXE.COM

<!DOCTYPE html> <html lang="en-US" dir="ltr"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <title>GetResponse REST Web Service Interface | GR API Docs</title> <meta name="description" content="GetResponse API DOCS"> <meta name="generator" content="VitePress v1.0.0-rc.44"> <link rel="preload stylesheet" href="/assets/style.CVypmggt.css" as="style"> <script type="module" src="/assets/app.DiDxTzq1.js"></script> <link rel="preload" href="/assets/inter-roman-latin.Bu8hRsVA.woff2" as="font" type="font/woff2" crossorigin=""> <link rel="modulepreload" href="/assets/chunks/theme.BfDLsxgB.js"> <link rel="modulepreload" href="/assets/chunks/framework.CObUeWMv.js"> <link rel="modulepreload" href="/assets/v3.md.CB5Z0BAS.lean.js"> <link rel="icon" href="/favicon-32x32.png"> <meta name="keywords" content="GetResponse API DOCS"> <meta name="robots" content="noodp"> <meta name="author" content="GetResponse"> <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script> </head> <body> <div id="app"><div class="Layout" data-v-5d98c3a5><span tabindex="-1" data-v-0f60ec36></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-0f60ec36> Skip to content </a><header class="VPNav" data-v-5d98c3a5 data-v-ae24b3ad><div class="VPNavBar has-sidebar" data-v-ae24b3ad data-v-19c990f1><div class="wrapper" data-v-19c990f1><div class="container" data-v-19c990f1><div class="title" data-v-19c990f1><div class="VPNavBarTitle has-sidebar" data-v-19c990f1 data-v-ab179fa1><a class="title" href="/" data-v-ab179fa1><img class="VPImage logo" src="/logo.webp" alt data-v-8426fc1a><span data-v-ab179fa1>GR API Docs</span></a></div></div><div class="content" data-v-19c990f1><div class="content-body" data-v-19c990f1><div class="VPNavBarSearch search" data-v-19c990f1><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-19c990f1 data-v-7f418b0f><span id="main-nav-aria-label" class="visually-hidden" data-v-7f418b0f>Main Navigation</span></nav></div></div></div></div><div class="divider" data-v-19c990f1><div class="divider-line" data-v-19c990f1></div></div></div></header><div class="VPLocalNav has-sidebar empty" data-v-5d98c3a5 data-v-a6f0e41e><div class="container" data-v-a6f0e41e><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-a6f0e41e><span class="vpi-align-left menu-icon" data-v-a6f0e41e></span><span class="menu-text" data-v-a6f0e41e>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-a6f0e41e data-v-d2ecc192><button data-v-d2ecc192>Return to top</button></div></div></div><aside class="VPSidebar" data-v-5d98c3a5 data-v-575e6a36><div class="curtain" data-v-575e6a36></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-575e6a36><span class="visually-hidden" id="sidebar-aria-label" data-v-575e6a36> Sidebar Navigation </span><div class="group" data-v-575e6a36><div data-v-575e6a36><div class="menu-item-wrapper"><a href="/v3" class="menu-item-name isActive">Home</a></div><div class="menu-item-wrapper"><a href="https://apireference.getresponse.com/" class="menu-item-name">API Reference</a></div><div class="menu-item-wrapper"><a href="/v3/authentication" class="menu-item-name">Authentication</a></div><div class="menu-item-wrapper"><a href="/v3/errors" class="menu-item-name">Errors</a></div><div class="menu-item-wrapper"><a href="/v3/limits" class="menu-item-name">Limits & throttling</a></div><div class="menu-item-wrapper"><a href="/v3/dynamic-content" class="menu-item-name">Dynamic content</a></div><div class="menu-item-wrapper"><a href="/v3/callbacks" class="menu-item-name">Callbacks</a></div><div class="menu-item-wrapper"><a href="/v3/webhooks" class="menu-item-name">Webhooks</a></div><div class="menu-item-wrapper"><a href="/v3/case-study" class="menu-item-name">Case Study</a></div></div></div></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-5d98c3a5 data-v-1428d186><div class="VPDoc has-sidebar has-aside" data-v-1428d186 data-v-39a288b8><div class="container" data-v-39a288b8><div class="aside" data-v-39a288b8><div class="aside-curtain" data-v-39a288b8></div><div class="aside-container" data-v-39a288b8><div class="aside-content" data-v-39a288b8><div class="VPDocAside" data-v-39a288b8 data-v-3f215769><div class="VPDocAsideOutline" role="navigation" data-v-3f215769 data-v-935f8a84><div class="content" data-v-935f8a84><div class="outline-marker" data-v-935f8a84></div><div class="outline-title" role="heading" aria-level="2" data-v-935f8a84>On this page</div><nav aria-labelledby="doc-outline-aria-label" data-v-935f8a84><span class="visually-hidden" id="doc-outline-aria-label" data-v-935f8a84> Table of Contents for current page </span><ul class="VPDocOutlineItem root" data-v-935f8a84 data-v-b933a997></ul></nav></div></div><div class="spacer" data-v-3f215769></div></div></div></div></div><div class="content" data-v-39a288b8><div class="content-container" data-v-39a288b8><main class="main" data-v-39a288b8><div style="position:relative;" class="vp-doc _v3" data-v-39a288b8><div><h1 id="getresponse-rest-web-service-interface" tabindex="-1">GetResponse REST Web Service Interface <a class="header-anchor" href="#getresponse-rest-web-service-interface" aria-label="Permalink to "GetResponse REST Web Service Interface""></a></h1><p>GetResponse API gives you basically the same functionality as in our web panels - you can perform the same set of actions: manage campaigns, newsletters, gather statistics and more (and yes we have segments in here!).</p><h2 id="api-endpoint" tabindex="-1">API Endpoint <a class="header-anchor" href="#api-endpoint" aria-label="Permalink to "API Endpoint""></a></h2><p>Api endpoint (or base url) is always the same for all retail users and looks like follows:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes light-plus github-dark vp-code"><code><span class="line"><span>https://api.getresponse.com/v3</span></span></code></pre></div><p>The only thing to remember is that the last part of it (v3 in this case) is the version number of our API. If in the future we introduce some backward incompatible changes we will increment our API version to give you time to migrate from v3 to (let's say) v4. But don't worry we will keep stable version for a long time and most of future updates will be backward compatible.</p><h2 id="getresponse-max-platform" tabindex="-1">GetResponse MAX platform <a class="header-anchor" href="#getresponse-max-platform" aria-label="Permalink to "GetResponse MAX platform""></a></h2><p>For GetResponse MAX platform users endpoint looks different. There are two different url's and any GetResponse MAX user who wants to connect to our api should contact his account manager and which one he should use.</p><ul><li><code>https://api3.getresponse360.pl/v3</code></li><li><code>https://api3.getresponse360.com/v3</code></li></ul><h2 id="authentication" tabindex="-1">Authentication <a class="header-anchor" href="#authentication" aria-label="Permalink to "Authentication""></a></h2><p>All request you want to send to our API must contain authentication information. For example, if your api-key is: <code>84fsne83yrths947r6sfgg7w4he8</code>, then the custom authentication header should look like:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes light-plus github-dark vp-code"><code><span class="line"><span>X-Auth-Token: api-key 84fsne83yrths947r6sfgg7w4he8</span></span></code></pre></div><p><strong>For security reasons, unused API keys expire after 90 days. When that happens, you’ll need to generate a new key to use our API.</strong> For more detailed information, mobile authentication and GetResponse MAX platform authentication please, go to our <a href="./authentication">authentication</a> page</p><h2 id="basics" tabindex="-1">Basics <a class="header-anchor" href="#basics" aria-label="Permalink to "Basics""></a></h2><p>This is REST API, all request follows REST rules in terms of resource naming convention, use of HTTP method as action description and use of custom headers to convey additional infomration.</p><p>In order to correctly configure your app you need to remember couple of things.</p><h3 id="methods-https" tabindex="-1">Methods (HTTPS) <a class="header-anchor" href="#methods-https" aria-label="Permalink to "Methods (HTTPS)""></a></h3><p>We accept 3 methods GET, POST and DELETE. Every POST request <strong>MUST HAVE</strong> Content-Type header. Currently we accept only 'application/json' content-type</p><p>GET if to obtain information. There should not be any "body" data sent with that request. This will not trigger error, but we just simply don't look there in GET request. Only query string parameters ale allowed. This request will never change anything, you can call it as many times as you want. It is called that GET is IDEMPOTENT request.</p><p>POST is to add new or modify existing information. If request url doesn't contain resource ID then we will treat that as new data that must be inserted. If you want to modify existing data you need to specify an ID in the Rrequest URL (like POST /contacts/hg5fF). POST is NOT IDEMPOTENT, you need to be carefull to not send the same request twice...</p><p>DELETE is only to remove infomration. As a general rule we do not allow to add any "body" data to that type of request nor we allow any query string. This should be just simply DELETE /contacts/hg5fF.</p><h3 id="resources-and-representations" tabindex="-1">Resources and Representations <a class="header-anchor" href="#resources-and-representations" aria-label="Permalink to "Resources and Representations""></a></h3><p>We present data as JSON strings. Those information are named "representation" of a "resource". Each url in our API represents an "resource".</p><p>Each representation has its own unique ID - naming convention is very easy: ID of a newsletters is called newsletterId 😃. We stick to json <strong>camelCase</strong> for field names in json data. When you call <strong>GET /newsletters/V</strong> we will return json data which represents a resource called "newsletter" where it's ID is equal to 'V'. </p><p>When you call GET /newsletters we will return a <strong>Collection</strong> of resources. This is simply a list of resources representations presented as json array. You need to remember that in a collection we could ommit some of the fileds that are there in single resource. You should treat collection as a brief information of a resource not a full package 😃.</p><p>When you call POST /newsletters you need to send to us the same structure of json-encoded representation of a newsletter resource. This is very important! If you change name of a field, add some new fields of ommit some of the mandatory fields we will return 400 response with special "error" resource which will contain all validation errors that we discovered in your request. Sometimes you can ommit the field (if it isn't mandatory), but if you set some field with empty value we will treat this as normal and simply set this value to empty string or null. If you don't want to modify some field just don't include it in json representation.</p></div></div></main></div></div></div></div></div></div></div> <script>window.__VP_HASH_MAP__=JSON.parse("{\"v3_case-study_conditions_email.md\":\"D4G1bzN1\",\"v3_callbacks_survey.md\":\"CdsTTF_r\",\"v3_case-study_conditions_gdpr.md\":\"DRvfZUkC\",\"v3_case-study_conditions_engagement_score.md\":\"CWE75s-2\",\"v3_dynamic-content.md\":\"Czv6PbT0\",\"v3_errors_1016.md\":\"CEO5-2ob\",\"v3_dynamic-content_dates.md\":\"CYasxXAr\",\"v3_errors_1011.md\":\"B3JWmxy3\",\"v3_errors_1005.md\":\"DBRH5r0e\",\"v3_errors_1001.md\":\"lfFZenE-\",\"v3_case-study_conditions_tag.md\":\"pTKVo445\",\"v3_errors_1027.md\":\"qz-U_bXm\",\"v3_errors_1021.md\":\"DwnuDGiR\",\"v3_errors_1019.md\":\"DeRpGZZN\",\"v3_errors_1028.md\":\"-otdMb-A\",\"v3_authentication.md\":\"DOBD2xwS\",\"v3_dynamic-content_contact.md\":\"DD7JqIc4\",\"v3_limits.md\":\"CEDZnpnj\",\"v3_errors_1010.md\":\"CBnjficH\",\"v3.md\":\"CB5Z0BAS\",\"v3_callbacks_goal.md\":\"CbaGo7fa\",\"v3_errors_1006.md\":\"CeFyKvXj\",\"v3_case-study_conditions_not_clicked.md\":\"BkN6HubR\",\"v3_errors_1013.md\":\"CDzDkEiL\",\"v3_case-study_conditions_clicked.md\":\"1Aspgdem\",\"v3_case-study_conditions_sms_sent.md\":\"DVLQf3ML\",\"v3_errors.md\":\"BZgM3lVW\",\"v3_payloads_contact_removed_link.md\":\"DFcAVzgH\",\"v3_case-study_conditions_ecommerce_total_spent.md\":\"Y143SnnO\",\"v3_case-study_adding-batch-contacts.md\":\"CMiahndd\",\"v3_case-study_conditions_scoring.md\":\"BhHkgg-2\",\"v3_dynamic-content_external-content.md\":\"CeVpzgxr\",\"v3_dynamic-content_conditions.md\":\"DQ6KwhGD\",\"v3_errors_1009.md\":\"B-w_lqux\",\"v3_errors_1017.md\":\"S5klcHKL\",\"v3_errors_1012.md\":\"Bo5rpIwf\",\"v3_errors_1.md\":\"B5ajg6Nf\",\"v3_payloads_contact_custom_field_changed.md\":\"DbQBGwcG\",\"v3_errors_1000.md\":\"BXaOegA2\",\"v3_case-study_conditions_phase.md\":\"CtD1ocqk\",\"v3_errors_1015.md\":\"DpkU7bAJ\",\"v3_errors_1018.md\":\"gg3jrXhr\",\"v3_case-study_conditions_name.md\":\"D4PHGuaG\",\"v3_case-study_conditions_sms_link_not_clicked.md\":\"xve_L9Y_\",\"v3_errors_1008.md\":\"CiNx9Zu2\",\"v3_case-study_smb-vs-mx.md\":\"D3b4D9f0\",\"v3_callbacks.md\":\"Bl9CpLi9\",\"v3_case-study_oauth2-client-credentials.md\":\"D5Ql5ycV\",\"v3_dynamic-content_prettifiers.md\":\"CkFuU56P\",\"v3_errors_1002.md\":\"D3RY2Dju\",\"v3_payloads_contact_removed_bounce.md\":\"D6tIiQ5_\",\"v3_case-study_conditions_ecommerce_number_of_purchases.md\":\"Eds-IW0g\",\"v3_dynamic-content_external-lexpad.md\":\"BeEjWcUq\",\"v3_callbacks_unsubscribe.md\":\"c7NrSryt\",\"v3_case-study_conditions_opened.md\":\"ClZQq5l7\",\"v3_payloads_contact_copied.md\":\"b2bMo1lI\",\"v3_errors_1014.md\":\"_TE_jATN\",\"v3_errors_1023.md\":\"Cfp4RdMS\",\"v3_dynamic-content_links.md\":\"C1EziU10\",\"v3_payloads_headers.md\":\"DTBOoWdE\",\"v3_case-study_conditions_ecommerce_brand_purchased.md\":\"DpH-mzOl\",\"v3_case-study_conditions_sms_link_clicked.md\":\"DKfjxRFw\",\"v3_callbacks_click.md\":\"DhlnO0XM\",\"v3_case-study_conditions_subscription_date.md\":\"BanJg21k\",\"v3_case-study_conditions_not_sent.md\":\"Df8DGCvv\",\"v3_payloads_contact_clicked_sms_link.md\":\"BKyTom_o\",\"v3_payloads_contact_clicked_message_link.md\":\"B5yIyUHC\",\"v3_errors_1004.md\":\"DoHBBohC\",\"v3_case-study_adding-contacts.md\":\"CHzBfV0J\",\"v3_case-study_conditions_webinar.md\":\"BYndort8\",\"v3_errors_1024.md\":\"BpwoiaEn\",\"v3_case-study_conditions_geo.md\":\"CzJake4-\",\"v3_payloads_contact_email_changed.md\":\"z3hNUccQ\",\"v3_case-study_conditions_sent.md\":\"BS9Ll_y0\",\"v3_errors_1007.md\":\"C5Soewjc\",\"v3_dynamic-content_randoms.md\":\"D5BXwD8d\",\"v3_errors_1003.md\":\"CgutZcdu\",\"v3_case-study_conditions_last_open_date.md\":\"j_P-HyQv\",\"v3_payloads_contact_rejected.md\":\"CD6Awh5g\",\"v3_payloads_contact_moved.md\":\"BPjhZp64\",\"v3_payloads_contact_added.md\":\"BbxcaG2w\",\"v3_payloads_contacts_import_finished.md\":\"BmkYr58I\",\"v3_case-study_conditions_last_send_date.md\":\"BGUhn-ZG\",\"v3_errors_1029.md\":\"Ta6467_S\",\"v3_case-study_conditions_ecommerce_product_purchased.md\":\"DWLfBLKe\",\"v3_dynamic-content_campaign.md\":\"BbhvF8b2\",\"v3_case-study_conditions_last_click_date.md\":\"Drg2_BSC\",\"v3_callbacks_open.md\":\"CYehw9S3\",\"v3_case-study_search-contacts-guide.md\":\"Cd6T1u6f\",\"v3_case-study_conditions_custom.md\":\"_5hTKv0E\",\"v3_case-study_conditions_subscription_method.md\":\"Dm4XEYfa\",\"v3_authentication_oauth2.md\":\"DYN67pjY\",\"v3_case-study_conditions_ecommerce_abandoned_cart.md\":\"wJbMpVkZ\",\"v3_payloads_contact_opened_message.md\":\"m6NLVx-d\",\"v3_callbacks_subscribe.md\":\"UNbQRbcK\",\"v3_case-study_conditions_custom_event.md\":\"DIcT96bl\",\"v3_case-study_oauth2-authorization-code.md\":\"Dq0cNeRM\",\"v3_webhooks.md\":\"BKYj5N7s\",\"v3_case-study_conditions_not_opened.md\":\"wNEvPpIb\",\"v3_case-study.md\":\"DRLNLM6v\",\"v3_case-study_create-import.md\":\"BlTzKVAK\",\"v3_payloads.md\":\"B2xQWk-k\",\"v3_case-study_segments-manual.md\":\"DSXmAuzN\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"GR API Docs\",\"description\":\"GetResponse API DOCS\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":false,\"themeConfig\":{\"nav\":[],\"logo\":\"/logo.webp\",\"docFooter\":{\"next\":false,\"prev\":false},\"search\":{\"provider\":\"local\"},\"sidebar\":[{\"text\":\"main\",\"items\":[{\"link\":\"/v3\",\"text\":\"Home\"},{\"link\":\"https://apireference.getresponse.com/\",\"text\":\"API Reference\"},{\"text\":\"Authentication\",\"link\":\"/v3/authentication\",\"items\":[{\"text\":\"OAuth 2.0\",\"link\":\"/v3/authentication/oauth2\"}]},{\"text\":\"Errors\",\"link\":\"/v3/errors\"},{\"text\":\"Limits & throttling\",\"link\":\"/v3/limits\"},{\"text\":\"Dynamic content\",\"link\":\"/v3/dynamic-content\",\"items\":[{\"text\":\"Campaign\",\"link\":\"/v3/dynamic-content/campaign\"},{\"text\":\"Conditions\",\"link\":\"/v3/dynamic-content/conditions\"},{\"text\":\"Contact\",\"link\":\"/v3/dynamic-content/contact\"},{\"text\":\"Dates\",\"link\":\"/v3/dynamic-content/dates\"},{\"text\":\"External content\",\"link\":\"/v3/dynamic-content/external-content\"},{\"text\":\"External lexpad\",\"link\":\"/v3/dynamic-content/external-lexpad\"},{\"text\":\"Prettifiers\",\"link\":\"/v3/dynamic-content/prettifiers\"},{\"text\":\"Randoms\",\"link\":\"/v3/dynamic-content/randoms\"},{\"text\":\"Links\",\"link\":\"/v3/dynamic-content/links\"}]},{\"text\":\"Callbacks\",\"link\":\"/v3/callbacks\",\"items\":[{\"text\":\"Subscribe\",\"link\":\"/v3/callbacks/subscribe\"},{\"text\":\"Open\",\"link\":\"/v3/callbacks/open\"},{\"text\":\"Click\",\"link\":\"/v3/callbacks/click\"},{\"text\":\"Goal\",\"link\":\"/v3/callbacks/goal\"},{\"text\":\"Survey\",\"link\":\"/v3/callbacks/survey\"},{\"text\":\"Unsubscribe\",\"link\":\"/v3/callbacks/unsubscribe\"}]},{\"text\":\"Webhooks\",\"link\":\"/v3/webhooks\",\"items\":[{\"text\":\"Webhook payloads\",\"link\":\"/v3/payloads\"}]},{\"text\":\"Case Study\",\"link\":\"/v3/case-study\",\"items\":[{\"text\":\"GetResponse and GetResponse MAX API - differences\",\"link\":\"/v3/case-study/smb-vs-mx\"},{\"text\":\"OAuth 2.0 - Authorization Code\",\"link\":\"/v3/case-study/oauth2-authorization-code\"},{\"text\":\"OAuth 2.0 - Client Credentials\\n\",\"link\":\"/v3/case-study/oauth2-client-credentials\"},{\"text\":\"Adding contacts\",\"link\":\"/v3/case-study/adding-contacts\"},{\"text\":\"Adding multiple contacts\",\"link\":\"/v3/case-study/adding-batch-contacts\"},{\"text\":\"How to schedule a contact import\",\"link\":\"/v3/case-study/create-import\"},{\"text\":\"Segments (search contacts)\",\"link\":\"/v3/case-study/search-contacts-guide\"},{\"text\":\"Segments (search contacts) reference manual\",\"link\":\"/v3/case-study/segments-manual\"}]}]}],\"outline\":{\"level\":\"deep\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script> </body> </html>