> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

> Forms v3 endpoints

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

<ParamField path="api_key" type="string" required={true}>
  Your account API key
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/forms?api_key=<your_public_api_key>
  ```

  ```json Response theme={null}
  {
    "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."
      }
    ]
  }
  ```
</CodeGroup>

## Add subscriber to a form

Subscribe an email address to one of your forms.

### Endpoint

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

### Parameters

<ParamField path="api_key" type="string" required={true}>
  Your account API key
</ParamField>

<ParamField path="form_id" type="integer" required={true}>
  The ID for the form you want to add the subscriber to
</ParamField>

<ParamField path="email" type="string" required={true}>
  Subscriber email address
</ParamField>

<ParamField path="first_name" type="string">
  Subscriber first name
</ParamField>

<ParamField path="fields" type="object">
  Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.
</ParamField>

<ParamField path="tags" type="array">
  Array of tag ids to subscribe to
</ParamField>

### Deprecated Parameters

<ParamField path="courses" type="array">
  Array of sequence ids to subscribe to. You should [add the subscriber to the sequence directly](/api-reference/v3/sequences).
</ParamField>

<ParamField path="forms" type="array">
  Array of form ids to subscribe to. You should add the subscriber to each form individually.
</ParamField>

<ParamField path="name" type="string">
  Subscriber first name. You should prefer using `first_name` listed above.
</ParamField>

<CodeGroup>
  ```shell Request (Basic) theme={null}
  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"
           }'
  ```

  ```shell Request (With Tags) theme={null}
  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]
           }'
  ```

  ```json Response theme={null}
  {
    "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
      }
    }
  }
  ```
</CodeGroup>

## List subscriptions to a form

List subscriptions to a form including subscriber data.

### Endpoint

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

### Parameters

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="form_id" type="integer" required={true}>
  The ID for the form you want to list subscribers from
</ParamField>

<ParamField path="sort_order" type="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`.
</ParamField>

<ParamField path="subscriber_state" type="string">
  Filter by subscriber state (`active` or `cancelled`). Receive only active subscribers or cancelled subscribers.
</ParamField>

<ParamField path="page" type="string">
  The page of results being requested. Default value is `1`. Each page of results will contain up to 50 subscriptions.
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/forms/<form_id>/subscriptions?api_secret=<your_secret_api_key>
  ```

  ```json Response theme={null}
  {
    "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"
          }
        }
      }
    ]
  }
  ```
</CodeGroup>