Cognism API: What You Can Automate and What You Can't

A RevOps engineer sits down to wire Cognism enrichment into a CRM, opens the developer docs, and hits a blocker that is not an endpoint at all. It is a sentence in the Entitlements section: "Cognism API cannot be used unless Entitlements are properly set up." Entitlements are configured by Cognism's support team, not by you, and they decide which fields you are allowed to search on and which fields come back. Before a single request works, someone at the vendor has to define your data surface.

That is the shape of building on this API. The mechanics are well documented and unfussy. The constraints are commercial ones expressed in technical form, and they land in a different order than most integrations.

Everything below comes from Cognism's published developer documentation at developers.cognism.com, fetched 13 August 2026. That documentation is published through Postman and rendered client-side, so each figure here was also confirmed against the collection payload the page itself loads, which is a second surface rather than a second reading of the same one.

What the API surface actually contains

The published collection breaks into six groups, and the group list is more informative than any individual endpoint.

Search covers Search Contacts and Search Accounts. It returns preview data: enough to see that a record exists and decide whether you want it. Each array field in a search request accepts up to 1,000 search terms in a single request, which is generous for building large filtered pulls.

Redeem covers Redeem Contacts by IDs and Redeem Accounts by IDs. This is where you buy the record. The documentation describes the normal workflow plainly: search first, find the IDs you want, then redeem those. One call takes one to twenty IDs.

Enrich covers Enrich Contact and Enrich Account. This is the append path: you send what you know about a person or company, and it returns the single best match.

Entitlement exposes two read-only endpoints so you can query how your own entitlements are configured, which is the only way to discover your allowed field set programmatically.

Filter is fourteen lookup endpoints returning the valid values for the filterable dimensions: technologies, management levels, company sizes, industries, job functions, regions, countries, states, SIC, ISIC and NAICS codes, skills, company types and seniority. Treat these as required reading rather than convenience, because a search request using an unrecognised value returns a 400 rather than an empty result.

Compliance exposes three endpoints for opt-out status: a full opt-out list, lookup by email, and lookup by Cognism ID. The convention on the lookups is worth memorising because it inverts the usual reading: HTTP 200 means the contact has opted out, and 404 means they have not.

SearchFind and preview

• Returns preview data, not full records
• Up to 1,000 terms per array field per request
• Draws on the preview limit, roughly 20 per request at default index size
• Pagination runs first to last only

RedeemBuy the record

• One to twenty IDs per call
• Spends standard credits
• Does not decrease the preview limit
• Uses the redeemId returned by Search or Enrich

EnrichAppend to what you have

• Returns a single best match, scored
• Draws on the preview limit by 1 per call
• Default minMatchScore of 30 for contacts
• Returns nothing at all below your threshold

Authentication, and the six-month cliff

Authentication is an API key issued to you by Cognism. You can pass it as an Authorization: Bearer header or as an api_key query parameter, and the documentation recommends the header for the obvious reason that query strings end up in logs.

The detail that catches teams is the expiry. The documentation states that API keys have a time to live of six months. Keys are generated and revoked through Cognism Prospector or Cognism Refresh, so rotation is a console task rather than an API call.

Six months is long enough that whoever built the integration has moved on to other work by the time it expires, and short enough that it will expire while the integration is still load bearing. Put the rotation date in a calendar the day you generate the key, and make the 401 path loud. An enrichment job that silently starts returning unauthorised looks identical to an enrichment job finding nothing, which is the failure mode that quietly poisons a CRM with empty fields.

Two meters, not one

The cost model has two independent allowances, and confusing them is the most common budgeting error.

Credits are the commercial unit. A credit is spent when you redeem a contact. Cognism's pricing page states the same credits work across the prospecting platform, Enrich and the API without extra cost, so there is no separate API wallet to buy.

The preview limit is the guardrail on looking. The documentation defines it as your credit count multiplied by ten, and gives the worked example directly: one million credits produces a ten million preview limit. A search request decreases it by 20 at the default index size, an Enrich call decreases it by 1, and the documentation is explicit that the Redeem endpoint spends standard credits and does not decrease the preview limit at all.

The practical consequence: exploratory searching is cheap in credits and expensive in previews, and a badly built pagination loop can exhaust ten times your credit allowance without ever redeeming a single contact. Budget both.

On top of both sits a rate limit, documented at a maximum of 1,000 requests per minute, exposed through x-rate-total-limit and related response headers, and returning HTTP 429 with error code 88 when exceeded. There is a separate per-endpoint ceiling as well, so a job that stays under the global limit can still trip an individual endpoint.

1. Step 1Look up filter values

   Call the Filter endpoints for valid industries, seniorities, technologies and codes. An unrecognised value returns a 400, not an empty set.

2. Step 2Search for candidates

   Preview data comes back. Each request decreases the preview limit by 20 at the default index size.

3. Step 3Decide, then redeem

   Send one to twenty redeemIds. This spends credits and leaves the preview limit untouched.

4. Step 4Check opt-out status

   The Compliance endpoints answer 200 for opted out and 404 for not opted out. Treat that inversion carefully in code.

Enrich is a scored guess, and the score is yours to set

The Enrich endpoint does not do exact lookup. The documentation describes a scoring model where each input field contributes to a match score, constant fields such as first name, last name and email carry consistent weight, and dynamic fields such as job title are weighted by specificity. A more distinctive title contributes more than a generic one.

You set the floor. The documented default minMatchScore for Enrich Contact is 30, and for Enrich Account it is 40. The documentation publishes a tuning table for contacts: 38 to 50 for high accuracy with fewer but more reliable results, 29 to 38 as the balanced default range, and 25 to 29 for a higher match rate that may include ambiguous matches. It also advises against going above 45, on the grounds that accuracy barely improves past that point.

The sentence that matters most is the one about failure: if no profile meets your threshold, the API returns no data. That is a deliberate silence rather than an error, so an integration that logs only errors will record a perfectly healthy run while enriching nothing. Log the no-match rate separately from the failure rate, and alert on it.

The documentation also notes that a single unique identifier such as an email address effectively bypasses the scoring model, since there is nothing to weigh, and points you to Search instead for that case. That is a useful hint for anyone building a lookup service rather than an enrichment pass, and it echoes the general point in our waterfall enrichment guide: identity resolution and record appending are different jobs with different failure modes.

One more field to design around: redeemId. The documentation explains that it identifies a contact in a specific job title at a specific account, so it changes when the person changes title or company. Old IDs still work, because the API falls back to the current one and returns it alongside the data, which makes it a usable job-change signal if you store it. A redeemId that comes back different from the one you sent tells you the person moved.

What you cannot automate

This is the honest half of the promise, and the collection makes it clear by omission. Enumerated across all six published groups, there is no endpoint for any of the following.

There is no export or list-management endpoint. You cannot create, name or manage saved lists in the platform through the API; redeemed records come back in the response for you to store yourself.

There is no intent-data endpoint. Intent is a Pro package feature inside the platform, sourced from Bombora, and it does not appear in the published collection.

There is no webhook or push mechanism. Everything is request and response, so job-change monitoring means re-enriching on a schedule and diffing the result yourself rather than being told.

There is no CRM sync endpoint. The native Salesforce, HubSpot, Pipedrive, Bullhorn and Dynamics integrations are separate products, and CRM Enrichment is a paid add-on on the pricing page rather than an API capability.

There is no bulk file delivery. That is the Data-as-a-Service add-on, and the pricing page carries a constraint that shapes the whole build: "API access requires a Prospecting seat". Bulk delivery is available standalone, but the API is not. A data team that wants programmatic access only still has to buy at least one prospecting seat.

And the documentation carries an accuracy caveat worth quoting in any internal design doc: API responses may differ from the results retrieved via Prospector search in the web application. If a rep and a pipeline disagree about whether a contact exists, that is documented behaviour, not a bug to chase.

Can the API do it?

• ✓Yes: Search contacts and accounts on firmographic, technographic and signal filters
• ✓Yes: Redeem full records against credits, up to twenty IDs per call
• ✓Yes: Enrich a known person or company to a scored best match
• ✓Yes: Check a contact's opt-out status before sending
• ✕No: Receive a webhook when a contact changes job
• ✕No: Pull intent data programmatically
• ✕No: Manage saved lists or push records straight to a CRM
• ✕No: Buy API access without a prospecting seat

The compliance endpoints are useful, and they are not your compliance

The Compliance group is a genuinely good piece of API design. Being able to check opt-out status by email before a send, rather than discovering it afterwards, is exactly the check that belongs in a pipeline. The contact schema also carries a privacyNotificationSent flag, and Cognism's compliance page states it notifies business contacts of their inclusion in the database within GDPR timeframes and screens against 15 Do Not Call and preference lists globally.

None of that is your compliance. Cognism's compliance page states it processes and shares data under legitimate interest under Article 6.1(f) GDPR, which covers Cognism building and licensing the database. Your outbound campaign needs its own lawful basis, its own country-by-country electronic-marketing check, and its own transparency in the first message. Calling the opt-out endpoint is a suppression control, and a suppression control is not a lawful basis. The two obligations are set out in our GDPR compliance guide.

Where this fits in a stack

For a team that already owns Cognism seats and wants CRM records kept current, the Enrich endpoint plus a scheduled diff on redeemId is a small, robust build. For a team wanting to source new audiences programmatically, Search plus Redeem works, with the preview limit as the thing to instrument first.

For a team choosing an API on API merits alone, the comparison is worth making on documentation depth and on what is missing rather than on record counts. Apollo's API sits at a different point on that curve, and the wider field is covered in best data enrichment tools for SDR teams and best Cognism alternatives.

Worth saying plainly at the end: an enrichment API improves the inputs to an outbound motion and changes nothing about the motion itself. Clean, current, opted-in records still need an offer worth reading and sending infrastructure that reaches an inbox. If that second half is the actual gap, see how a campaign gets built end to end.

Pricing and features verified as of August 2026. Verify current terms with the vendor before relying on them.