Subscription Management

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	See all your subscriptions, their status, creation, and expiration dates
GET /v2/subscriptions/{subsription_id}	See the details of your active subscription
PATCH /v2/subscriptions/{subsription_id}	Edit your active subscription by adding or removing IDs
POST /v2/subscriptions/{subscription_id}/renew	Renew your subscriptions for up to 1 year
DELETE /v2/subscriptions/{subsription_id}	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:

Request template

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

1. Send the request.

2. Refer to the Body for information about your subscription status:

[
  {
    "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	Subscription identification key. Subscription ID is displayed in the response body after submitting a webhook subscription	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:

Request template

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

1. Send the request.

2. You will see the following information in the Response body:

{
  "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"
}

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)
entity	Subscription entity	String
es_dsl_query	Elasticsearch DSL query used to subscribe to changes in a list of profiles	Object
filters	Search filters used to subscribe to changes in a list of profiles	Object
last_webhook_sent	Time of the last message sent to your webhook URL in YYYY-MM-DD format	String (date)

---

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:

Request template

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]
}'

1. Send the request.

2. You will see the following information in the Response body:

{
  "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": []}
}

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)
entity	Subscription entity	String
tracked_ids_count	Number of IDs in subscription after update	Integers
type	Only "ids_list" type subscriptions can be patched	String
added	Added IDs list	Array of integers
removed	Removed IDs list	Array of integers
skipped	Information about skipped IDs from the request body	Array of objects
skipped.already_tracked	Skipped IDs because they are already in the list	Array of integers
skipped.not_tracked	Skipped IDs because they cannot be tracked	Array of integers

---

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.

A subscription can be renewed for up to 1 year. If subscription renewal exceeds this period, the request will be canceled.

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:

Request template

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

1. Send the request.

2. You will see the following information in the Response body:

Response

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

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:

Template

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