> For the complete documentation index, see [llms.txt](https://docs.coresignal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coresignal.com/api-introduction/webhooks/subscription-management.md).

# Subscription Management

View, renew, update and delete webhook subscriptions using the subscription management endpoints.

The subscription management endpoints allow you to:

* See all available webhook subscriptions and related information
* See detailed information about your webhook subscriptions
* Update your subscriptions
* Renew your subscriptions
* Delete subscriptions

See the endpoints and their functions below:

| Endpoint                                                                                   | Function                                                                 |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| GET [*/v2/subscriptions*](#i-want-to-see-all-my-active-subscriptions)                      | See all your subscriptions, their status, creation, and expiration dates |
| GET [*/v2/subscriptions/{subsription\_id}*](#i-want-to-see-the-details-of-my-subscription) | See the details of your active subscription                              |
| PATCH [*/v2/subscriptions/{subsription\_id}*](#i-want-to-edit-my-subscription)             | Edit your active subscription by adding or removing IDs                  |
| POST [*/v2/subscriptions/{subscription\_id}/renew*](#i-want-to-renew-my-subscription)      | Renew your subscriptions for up to 1 year                                |
| DELETE [*/v2/subscriptions/{subsription\_id}*](#i-want-to-delete-my-subscription)          | Delete your subscriptions                                                |

## I want to see all my active subscriptions

Use the endpoint `GET /v2/subscriptions` to see all your available subscriptions, their statuses, creation and expiration dates:

1. Indicate whether you want to see details for only active subscriptions (`?expired=false`, default option) or for all subscriptions (`?expired=true`, including expired). In this request, the response header `"x-total-subscriptions"` matches the expired parameter and returns the count of active or all subscriptions.\
   You will automatically see only active subscriptions if you omit the expired parameter.
2. Specify the page number you want to see. Each page contains approximately 1,000 subscriptions, so if you have more than 1,000 subscriptions, you may need to specify the page number.
3. Replace `{API Key}` with your API Key in the template below:

{% code title="Request template" %}

```json
curl -X 'GET' \
  'https://api.coresignal.com/cdapi/v2/subscriptions?expired={false/true}&page={integer}' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}'
```

{% endcode %}

4. Send the request.
5. Refer to the *Body* for information about your subscription status:

```json
[
  {
    "id": "c8e295c0-2f85-473d-8bef-350526e6b30a",
    "status": "active",
    "created_at": "2026-09-08T12:40:40.182Z",
    "expiring_at": "2026-12-08T12:40:40.182Z"
  },
  {
    "id": "a85b2528-6190-4c91-8489-364b27ccbf81",
    "status": "active",
    "created_at": "2026-09-08T12:40:40.182Z",
    "expiring_at": "2026-12-08T12:40:40.182Z"
  }
]
```

| Data field    | Description                                                                                                                          | Data type     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `id`          | <p>Subscription identification key.<br>Subscription ID is displayed in the response body after submitting a webhook subscription</p> | String        |
| `status`      | Subscription status (active or expired)                                                                                              | String        |
| `created_at`  | Subscription start date                                                                                                              | String (date) |
| `expiring_at` | Subscription expiry date                                                                                                             | String (date) |

***

## I want to see the details of my subscription

Use the endpoint `GET /v2/subscriptions/{subscription_id}` to see the details of your expired or active subscriptions:

1. Find your subscription ID, which appears in the response body after you successfully submit a webhook subscription.
2. Replace `{API Key}` with your API Key and `{subscription_id}` with your subscription ID in the template below:

{% code title="Request template" %}

```json
curl -X 'GET' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/{subscription_id}' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}'
```

{% endcode %}

3. Send the request.
4. You will see the following information in the *Response body:*

```json
{
  "id": "c8e295c0-2f85-473d-8bef-350526e6b30a",
  "status": "active",
  "created_at": "2026-08-18T13:16:10.155Z",
  "expiring_at": "2026-11-18T13:16:10.155Z",
  "entity": "employee_base",
  "es_dsl_query": null, 
  "filters": null,
  "last_webhook_sent": "2026-09-05"
}
```

<table data-search="false"><thead><tr><th>Data field</th><th>Description</th><th>Data type</th></tr></thead><tbody><tr><td><code>id</code></td><td>Subscription identification key</td><td>String</td></tr><tr><td><code>status</code></td><td>Subscription status (active or expired)</td><td>String</td></tr><tr><td><code>created_at</code></td><td>Subscription start date</td><td>String (date)</td></tr><tr><td><code>expiring_at</code></td><td>Subscription expiry date</td><td>String (date)</td></tr><tr><td><code>entity</code></td><td>Subscription entity</td><td>String</td></tr><tr><td><code>es_dsl_query</code></td><td>Elasticsearch DSL query used to subscribe to changes in a list of profiles</td><td>Object</td></tr><tr><td><code>filters</code></td><td>Search filters used to subscribe to changes in a list of profiles</td><td>Object</td></tr><tr><td><code>last_webhook_sent</code></td><td>Time of the last message sent to your webhook URL in <code>YYYY-MM-DD</code> format</td><td>String (date)</td></tr></tbody></table>

***

## I want to edit my subscription

Use the endpoint `PATCH /v2/subscriptions/{subscription_id}` to update your active subscription without creating a new one by adding or removing IDs:

1. Find your subscription ID, which appears in the response body after you successfully submit a webhook subscription.
2. Replace `{API Key}` with your API Key, `{subscription_id}` with your subscription ID, and provide a request body with `"add":[]` list of new IDs you want to track and `"remove":[]` of IDs you want to remove from the subscription in the template below:

{% code title="Request template" %}

```json
curl -X 'PATCH' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/{subscription_id}' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "add": [123, 456],
  "remove": [789]
}'
```

{% endcode %}

3. Send the request.
4. You will see the following information in the *Response body:*

```json
{
  "id": "c8e295c0-2f85-473d-8bef-350526e6b30a",
  "status": "active",
  "created_at": "2026-09-03T12:37:33.755Z",
  "expiring_at": "2026-12-03T12:37:33.755Z",
  "entity": "employee_base",
  "type": "ids_list",
  "tracked_ids_count": 42,
  "added": [123, 456],
  "removed": [789],
  "skipped": {"already_tracked": [], "not_tracked": []}
}
```

<table data-search="false"><thead><tr><th>Data field</th><th>Description</th><th>Data type</th></tr></thead><tbody><tr><td><code>id</code></td><td>Subscription identification key</td><td>String</td></tr><tr><td><code>status</code></td><td>Subscription status (active or expired)</td><td>String</td></tr><tr><td><code>created_at</code></td><td>Subscription start date</td><td>String (date)</td></tr><tr><td><code>expiring_at</code></td><td>Subscription expiry date</td><td>String (date)</td></tr><tr><td><code>entity</code></td><td>Subscription entity</td><td>String</td></tr><tr><td><code>tracked_ids_count</code></td><td>Number of IDs in subscription after update</td><td>Integers</td></tr><tr><td><code>type</code></td><td>Only <code>"ids_list"</code> type subscriptions can be patched</td><td>String</td></tr><tr><td><code>added</code></td><td>Added IDs list</td><td>Array of integers</td></tr><tr><td><code>removed</code></td><td>Removed IDs list</td><td>Array of integers</td></tr><tr><td><code>skipped</code></td><td>Information about skipped IDs from the request body</td><td>Array of objects</td></tr><tr><td><code>skipped.already_tracked</code></td><td>Skipped IDs because they are already in the list</td><td>Array of integers</td></tr><tr><td><code>skipped.not_tracked</code></td><td>Skipped IDs because they cannot be tracked</td><td>Array of integers</td></tr></tbody></table>

***

## I want to renew my subscription

Use the endpoint `POST /v2/subscriptions/{subscription_id}/renew` to renew your subscriptions. A webhook subscription is valid for 91 days from the date it is created. To keep webhook delivery uninterrupted beyond this window, renew subscriptions before they expire.

You can schedule renewals in advance, allowing coverage for up to about 1 year from the initial subscription start date.

{% hint style="info" %}
A subscription can be renewed for up to 1 year. If subscription renewal exceeds this period, the request will be canceled.
{% endhint %}

1. Find your subscription ID, which appears in the response body after you successfully submit a webhook subscription.
2. Replace `{API Key}` with your API Key and `{subscription_id}` with your subscription ID in the template below:

{% code title="Request template" %}

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/{subscription_id}/renew' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}'
```

{% endcode %}

3. Send the request.
4. You will see the following information in the Response body:

{% code title="Response" %}

```json
{
    "id": "4e11dcae-9bfb-4edb-b4f6-a0991b20fb50",
    "status": "active",
    "created_at": "2026-04-24T12:00:00.000000",
    "expiring_at": "2026-10-24T12:00:00.000000",
}
```

{% endcode %}

| Data field    | Description                             | Data type     |
| ------------- | --------------------------------------- | ------------- |
| `id`          | Subscription identification key.        | String        |
| `status`      | Subscription status (active or expired) | String        |
| `created_at`  | Subscription start date                 | String (date) |
| `expiring_at` | Subscription expiry date                | String (date) |

## I want to delete my subscription

Use the endpoint `DELETE /v2/subscriptions/{subscription_id}` to make your subscriptions inactive.

Use the subscription ID you want to delete as input, and refer to the template below:

{% code title="Template" %}

```json
curl -X 'DELETE' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/{subscription_id}' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}'
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coresignal.com/api-introduction/webhooks/subscription-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.