Forms are used to collect subscriber information and can be embedded on your website or used as hosted landing pages.
Returns a list of all the forms for your account.
Endpoint
GET /v3/forms
Parameters
curl https://api.convertkit.com/v3/forms?api_key=<your_public_api_key>
{
"forms": [
{
"id": 1,
"name": "A Form",
"created_at": "2016-02-28T08:07:00Z",
"type": "embed",
"url": "https://app.convertkit.com/landing_pages/1",
"embed_js": "http://api.convertkit.dev/v3/forms/1.js?api_key=<your_public_api_key>",
"embed_url": "http://api.convertkit.dev/v3/forms/1.html?api_key=<your_public_api_key>",
"title": "Join the newsletter",
"description": "Form description text.",
"sign_up_button_text": "Subscribe",
"success_message": "Success! Now check your email to confirm your subscription."
},
{
"id": 2,
"name": "A Landing Page",
"created_at": "2016-02-28T08:07:00Z",
"type": "hosted",
"url": "https://app.convertkit.com/r4ndom_url/TWWDNTHT",
"embed_js": "http://api.convertkit.dev/v3/forms/2.js?api_key=<your_public_api_key>",
"embed_url": "http://api.convertkit.dev/v3/forms/2.html?api_key=<your_public_api_key>",
"title": "Join the newsletter",
"description": "<p>Landing page description text.</p>",
"sign_up_button_text": "Subscribe",
"success_message": "Success! Now check your email to confirm your subscription."
}
]
}
Endpoint
POST /v3/forms/#{form_id}/subscribe
Parameters
The ID for the form you want to add the subscriber to
Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.
Array of tag ids to subscribe to
Deprecated Parameters
Array of form ids to subscribe to. You should add the subscriber to each form individually.
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": "jonsnow@example.com"
}'
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": "jonsnow@example.com",
"tags": [1234, 5678]
}'
{
"subscription": {
"id": 1,
"state": "inactive",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "form",
"subscriber": {
"id": 1
}
}
}
Endpoint
GET /v3/forms/#{form_id}/subscriptions
Parameters
The ID for the form you want to list subscribers from
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.
Filter by subscriber state (active or cancelled). Receive only active subscribers or cancelled subscribers.
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>
{
"total_subscriptions": 2,
"page": 1,
"total_pages": 1,
"subscriptions": [
{
"id": 1,
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "form",
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
}
},
{
"id": 2,
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "form",
"subscriber": {
"id": 2,
"first_name": "Arya",
"email_address": "arya@example.com",
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"fields": {
"last_name": "Stark"
}
}
}
]
}
