add-subscriber-to-kit-form-via-api.md

Add Subscriber To Kit Form Via API

Because the Kit API is a bit sparse in words, I found it difficult to figure out exactly what I needed to do to add a subscriber via a custom form. After some experimenting and reading through Course Builder code, I was able to figure out that with the Kit v4 API there are two separate calls that need to be made.

First, you need to create an inactive subscriber with the user's email (and first name if given) via the Create a subscriber endpoint.

async function createSubscriber(
  data: SubscriberData,
  apiKey: string,
): Promise<Response> {
  return fetch('https://api.convertkit.com/v4/subscribers', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Kit-Api-Key': apiKey,
    },
    body: JSON.stringify({
      email_address: data.email,
      first_name: data.name,
      state: 'inactive',
    }),
  })
}

Since this subscriber is inactive, they won't show up in the Kit dashboard, but a subscriber record of them has been created.

Second, you need to add the subscriber to something, like a form or a sequence. In my case, I had already created a form via the Kit dashboard, so I grab that Form ID and stick it in my .env. That way I am able to add the subscriber to the form by email address.

async function addSubscriberToForm(
  email: string,
  apiKey: string,
  formId: string,
): Promise<Response> {
  const url = `https://api.convertkit.com/v4/forms/${formId}/subscribers`
  return fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Kit-Api-Key': apiKey,
    },
    body: JSON.stringify({ email_address: email }),
  })
}

This will send a confirmation email to the email address. Once the person has opened the email and hit 'Confirm', their corresponding subscriber record will be marked as active and they will be added to the list of subscribers for that form.