How to Integrate Retool with ConvertKit

ConvertKit uses a single API secret for authentication — there is no OAuth application to configure and no token expiry to manage. To find your API secret, log in to your ConvertKit account and navigate to Account Settings → Advanced. You will see an API Secret section with your secret displayed (or a button to reveal it). Copy the API secret value. This is a long alphanumeric string that should be treated like a password — it grants full access to your ConvertKit account via the API. Do not share it publicly or commit it to code repositories. You will also see an API Key on this page — the API Key is used only for read-only public operations like listing forms. The API Secret is required for all subscriber write operations (adding tags, subscribing, unsubscribing) and for accessing subscriber-level data. For your Retool integration, you will use the API Secret. Immediately store this value in a Retool Configuration Variable: in Retool, navigate to Settings → Configuration Variables, click Add Variable, name it CONVERTKIT_API_SECRET, paste the value, and check the 'Is Secret' checkbox to prevent it from being exposed in query logs or the frontend. Save the configuration variable before continuing to the resource setup step.

In Retool, navigate to the Resources tab using the plug icon in the left sidebar or via the top navigation bar. Click Add Resource and select REST API from the resource type options. Name the resource 'ConvertKit API'. Set the Base URL to https://api.convertkit.com/v3. ConvertKit's authentication works by appending api_secret as a URL parameter to every request rather than using an Authorization header. To configure this, scroll to the URL Parameters section in the resource configuration and add a default URL parameter: Parameter Name → api_secret, Value → {{ retoolContext.configVars.CONVERTKIT_API_SECRET }}. This ensures every query sent through this resource automatically includes the API secret as a URL parameter without you having to add it manually to each individual query. Also add a second default URL parameter: api_key → {{ retoolContext.configVars.CONVERTKIT_API_KEY }} — some ConvertKit read-only endpoints require the API key rather than the secret, so having both pre-configured makes query creation easier. Do not add the API secret as a header — ConvertKit's API specifically expects it as a URL parameter. Click Save Resource. Test the connection by creating a query with Method GET and Path /subscribers — a successful response confirms the resource is correctly configured.

Create the subscriber management queries for your dashboard. First, create a query named 'getSubscribers'. Set Method to GET and Path to /subscribers. Add URL parameters: page → {{ pagination.page || 1 }} (ConvertKit uses 1-indexed pagination), sort_field → created_at, sort_order → desc. ConvertKit returns 50 subscribers per page by default. The response object contains subscribers (an array of subscriber objects), total_subscribers (integer), page (current page), total_pages (total page count). Create a transformer to normalize the subscriber data. Each subscriber has: id, email_address, first_name, state (active, unsubscribed, bounced, complained), created_at, and fields (custom fields as a key-value object). The transformer flattens custom fields into named columns so they display correctly in Retool's Table. For email search, create a separate query named 'searchSubscriberByEmail'. Set Method to GET, Path to /subscribers, and add URL parameter email_address → {{ emailSearchInput.value }}. ConvertKit's email search on the subscribers endpoint returns the matching subscriber or an empty array. For tag-based filtering, create a query named 'getSubscribersByTag'. Set Method to GET and Path to /tags/{{ tagFilter.value }}/subscriptions. Add URL parameters: page → {{ pagination.page || 1 }}, subscriber_state → Active. This endpoint returns only subscribers with the specified tag who are in the active state.

1// Transformer: normalize ConvertKit subscribers
2const subscribers = data.subscribers || [];
3return subscribers.map(sub => ({
4  id: sub.id,
5  email: sub.email_address,
6  first_name: sub.first_name || '',
7  state: sub.state,
8  created: new Date(sub.created_at).toLocaleDateString(),
9  // Flatten custom fields
10  ...Object.fromEntries(
11    Object.entries(sub.fields || {}).map(([key, val]) => [
12      'field_' + key, val || ''
13    ])
14  )
15}));

Create queries for the analytics section of your dashboard. Create a query named 'getSequences'. Set Method to GET and Path to /sequences. This returns all email sequences in your account with their id, name, hold (whether the sequence is paused), repeat (whether subscribers can repeat), and created_at. Create a query named 'getForms'. Set Method to GET and Path to /forms. The response includes form id, name, type (hosted, inline, modal, slide_in), format, embed_js, embed_url, archived status, and subscriber counts. Create a query named 'getTags'. Set Method to GET and Path to /tags. This returns all tags with their id, name, and created_at. For subscriber counts per tag (not included in the tags list), create a JavaScript transformer that computes totals from the getSubscribersByTag query results, or accept that exact counts require individual requests per tag and display the tag list without counts for the initial view. Create a transformer named 'formatForms' for the forms query that computes useful display values from the raw data: humanize the form type name (capitalize and add spaces), flag archived forms with a label, and sort forms by subscriber count descending so the highest-converting forms appear at the top of the list.

1// Transformer: format ConvertKit forms with enriched display data
2const forms = data.forms || [];
3const TYPE_LABELS = {
4  hosted: 'Hosted Page',
5  inline: 'Inline',
6  modal: 'Modal Popup',
7  slide_in: 'Slide-In'
8};
9return forms
10  .filter(form => !form.archived)
11  .map(form => ({
12    id: form.id,
13    name: form.name,
14    type: TYPE_LABELS[form.type] || form.type,
15    total_subscribers: form.total_subscriptions || 0,
16    active_subscribers: form.active_subscriptions || 0,
17    status: form.archived ? 'Archived' : 'Active'
18  }))
19  .sort((a, b) => b.total_subscribers - a.total_subscribers);

Build the complete dashboard using Retool's component library. Organize the app into two tabs using a Tab component: 'Subscribers' and 'Analytics'. In the Subscribers tab: add a Text Input named 'emailSearchInput' with placeholder 'Search by email address', a Select component named 'tagFilter' populated with getTags.data (value = tag id, label = tag name), and a Table named 'subscribersTable' bound to getSubscribers.data. Configure the state column with conditional tag formatting: green for 'active', red for 'unsubscribed', orange for 'bounced'. Add row actions: 'View Details' (opens a Modal showing the full subscriber profile), 'Unsubscribe' (triggers a DELETE /subscribers/{id}/unsubscribe query with a confirmation modal). For tag management, in the subscriber detail Modal add a multi-select component for tag assignment. Create queries: 'addTagToSubscriber' (POST /tags/{tagId}/subscriptions, body { email: subscribersTable.selectedRow.email }) and 'removeTagFromSubscriber' (DELETE /subscribers/{id}/tags/{tagId}). In the Analytics tab: add a Stat bar at the top showing total subscriber count from getSubscribers.data total_subscribers. Below, place a Table of sequences on the left and a Table of forms on the right. Add a Bar Chart below the forms table showing subscribers per form — use getForms.data as the dataset with name as the X axis and total_subscribers as the Y axis. Run all four base queries on page load.

1// Query config: subscribe a user to a tag
2// POST /tags/{tagId}/subscriptions
3{
4  "email": "{{ subscribersTable.selectedRow.email }}",
5  "first_name": "{{ subscribersTable.selectedRow.first_name }}"
6}