Forms are used to collect subscriber information and can be embedded on your website or used as hosted landing pages.

List forms

Returns a list of all the forms for your account.

Endpoint

GET /v3/forms

Parameters

api_key
string
required
Your account API key
curl https://api.convertkit.com/v3/forms?api_key=<your_public_api_key>

Add subscriber to a form

Subscribe an email address to one of your forms.

Endpoint

POST /v3/forms/#{form_id}/subscribe

Parameters

api_key
string
required
Your account API key
form_id
integer
required
The ID for the form you want to add the subscriber to
email
string
required
Subscriber email address
first_name
string
Subscriber first name
fields
object
Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.
tags
array
Array of tag ids to subscribe to

Deprecated Parameters

courses
array
Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly.
forms
array
Array of form ids to subscribe to. You should add the subscriber to each form individually.
name
string
Subscriber first name. You should prefer using first_name listed above.
curl -X POST https://api.convertkit.com/v3/forms/<form_id>/subscribe\
     -H "Content-Type: application/json; charset=utf-8"\
     -d '{ 
           "api_key": "<your_public_api_key>",
           "email": "[email protected]"
         }'

List subscriptions to a form

List subscriptions to a form including subscriber data.

Endpoint

GET /v3/forms/#{form_id}/subscriptions

Parameters

api_secret
string
required
Your API secret key
form_id
integer
required
The ID for the form you want to list subscribers from
sort_order
string
Sort order for results (asc or desc). asc to list subscribers added oldest to newest, desc to list subscribers added newest to oldest. Default is asc.
subscriber_state
string
Filter by subscriber state (active or cancelled). Receive only active subscribers or cancelled subscribers.
page
string
The page of results being requested. Default value is 1. Each page of results will contain up to 50 subscriptions.
curl https://api.convertkit.com/v3/forms/<form_id>/subscriptions?api_secret=<your_secret_api_key>