All Cognism API requests require authentication using an API token. Your API usage is governed by available Credits and API rate limits.
This article explains how authentication works, when 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 Credits work
The Cognism API uses Credits to access full contact data.
Credits are only consumed when redeeming contact records using the Redeem API.
The following APIs do not consume 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 Credits consumed?
Credits are consumed when:
- A contact is redeemed using the Redeem API.
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.
This allows you to continue enriching previously redeemed contacts without consuming additional 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 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 Credits.
- Monitor your Credit usage if you're processing large volumes of data.