> ## 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.

# Sequences

> Sequences v3 endpoints

Sequences are automated email courses that deliver content to subscribers over time. They help you nurture leads and deliver value through a series of scheduled emails.

<Note>`Sequences` were formerly referred to as `Courses`. API V3 retains the previous naming conventions, but will accept requests to `sequences` as the endpoint as well. </Note>

## List sequences

Returns a list of sequences for your account.

### Endpoint

`GET /v3/sequences`

### 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/sequences?api_key=<your_public_api_key>
  ```

  ```json Response theme={null}
  {
    "courses": [
      {
        "id": 1,
        "name": "My First Sequence",
        "created_at": "2016-02-28T08:07:00Z"
      },
      {
        "id": 2,
        "name": "My Second Sequence",
        "created_at": "2016-02-28T08:07:00Z"
      }
    ]
  }
  ```
</CodeGroup>

## Add subscriber to a sequence

Subscribe an email address to one of your sequences.

### Endpoint

`POST /v3/sequences/#{sequence_id}/subscribe`

### Parameters

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

<ParamField path="sequence_id" type="integer" required={true}>
  The ID of the sequence you want to subscribe 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 each course individually.
</ParamField>

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

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

<CodeGroup>
  ```shell Request theme={null}
  curl -X POST https://api.convertkit.com/v3/sequences/<sequence_id>/subscribe\
       -H "Content-Type: application/json; charset=utf-8"\
       -d '{ 
              "api_key": "<your_public_api_key>",
              "email": "jonsnow@example.com"
           }'
  ```

  ```json Response theme={null}
  {
    "subscription": {
      "id": 2,
      "state": "inactive",
      "created_at": "2016-02-28T08:07:00Z",
      "source": null,
      "referrer": null,
      "subscribable_id": 1,
      "subscribable_type": "course",
      "subscriber": {
        "id": 1
      }
    }
  }
  ```
</CodeGroup>

## List subscriptions to a sequence

List subscriptions to a sequence including subscriber data.

### Endpoint

`GET /v3/sequences/#{sequence_id}/subscriptions`

### Parameters

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

<ParamField path="sequence_id" type="integer" required={true}>
  The ID of the sequence you want to retrieve subscriptions for
</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="integer">
  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/sequences/<sequence_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": "course",
        "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": "course",
        "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>