All Cognism API requests require authentication using an API token. Your API usage is governed by available Bulk Credits and API rate limits.
This article explains how authentication works, when Bulk Credits are consumed, and the limits that apply when using the Cognism API.
API authentication
The Cognism API uses Bearer Token authentication.
Every request must include your API token in the Authorization header.
Authorization: Bearer <YOUR_API_TOKEN>Requests made without a valid API token, or with an expired token, will fail.
For instructions on generating an API token, see Generate an API Token.
How Bulk Credits work
The Cognism API uses Bulk Credits to access full contact data.
Bulk Credits are only consumed when redeeming contact records using the Redeem API.
The following APIs do not consume Bulk Credits:
- Search API
- Enrich API
These APIs return preview data, allowing you to verify that you've found the correct record before redeeming it.
When are Bulk Credits consumed?
Bulk Credits are consumed when:
- A contact is redeemed using the Redeem API.
Bulk Credits are not consumed when:
- Searching for contacts or companies.
- Enriching contacts or companies.
- Redeeming company records.
- Redeeming a contact that has already been redeemed previously.
This allows you to continue enriching previously redeemed contacts without consuming additional Bulk Credits.
API rate limits
The Cognism API applies rate limits to ensure consistent performance.
Current limits include:
| API | Limit |
|---|---|
| Search API | 20–100 records per request |
| Redeem API | 1–20 Redeem IDs per request |
| Redeem throughput | Up to 1,000 records per minute |
Additional endpoint-specific limits may apply.
Your available Bulk Credits and subscription determine the volume of API activity your organisation can perform. For the latest rate limits and endpoint specifications, refer to the Cognism Developer Portal.
Example
A typical workflow looks like this:
- Search for matching contacts.
- Review the preview results.
- Select the records you want.
- Redeem those contacts.
- Bulk Credits are consumed only during the redemption step.
Best practices
To optimise API usage:
- Use the Search or Enrich API to identify the correct record before redeeming it.
- Redeem only the contacts you need.
- Reuse previously redeemed contacts where possible, as repeat redemptions do not consume additional Bulk Credits.
- Monitor your Bulk Credit usage if you're processing large volumes of data.