LeadHaste

Cognism API Guide: Test Enrichment Before CRM Writeback

Sofia Urrego
Sofia Urrego·Nov 21, 2026·10 min read

Summarize with AI

The Cognism API separates prospect Search from record Enrich and profile Redeem before the eventual CRM write. Keep those jobs separate in your integration. A preview does not contain the complete entitled profile, a Match Score is not a probability of accuracy, and a successful Redeem response does not prove that your CRM accepted the record.

Separate Search, Enrich, Redeem, and CRM writeback

Cognism's API overview describes Search and Enrich as distinct from Redeem. Search filters Cognism data for contacts or companies. Enrich starts with identifiers for a person or company you already hold. Both return preview data plus a Match Score and Redeem ID. Redeem accepts that ID and returns the complete profile allowed by your entitlements.

A custom integration must separately write an accepted result to the CRM. Cognism returns data to the caller, while your application chooses the destination object, maps fields, checks duplicates, assigns an owner, and handles a rejected write.

No enrichment result should write straight into production CRM fields. Put a staging record between Cognism and the CRM. That record gives the team one place to decide whether a match is good enough and whether a field may change. It also controls whether the contact should enter an outbound workflow.

StageInputEvidence to retainStop condition
SearchApproved prospect filtersQuery, preview, Match Score, Cognism ID, Redeem IDCandidate fails account, role, source, or suppression rules
EnrichKnown person or company identifiersSubmitted identifiers, preview, Match Score, Redeem IDMatch is absent, ambiguous, or stale
RedeemApproved Redeem IDComplete entitled response, credit movement, status, response bodyCredit state or returned identity cannot be reconciled
CRM writeAccepted staged fieldsDestination ID, prior values, final values, owner, write resultDuplicate, protected-field overwrite, denied write, or missing requirement

Prove access and entitlements before testing data

Confirm procurement and permissions before testing data. Cognism's API requirements and entitlements guide says the organisation needs API access enabled, available credits, configured entitlements, and permission to generate tokens. Buying access to the web application does not establish that the API or every desired field is available.

Entitlements govern which fields can be searched or returned. The Developer Portal says they affect Search and Preview. They also affect Result and are related to the API key. If an expected field is missing from a successful response, check entitlements before classifying the record as a failed match.

List every field the integration expects, then compare that list with an authenticated response from the buyer's account. Include contact fields, account fields, phone types, and any compliance-related fields the workflow depends on. Keep the response and the entitlement confirmation with the release evidence.

Authenticate with a dedicated token

Cognism's authentication guide requires a token on every request. The Developer Portal documents both a Bearer token in the Authorization header and an api_key query parameter, but recommends the header because it offers better security. Use the header. Credentials placed in URLs can leak through logs, browser history, monitoring tools, and support captures.

The token generation guide shows creation and expiration dates and allows tokens to be copied or deleted. The Developer Portal states that keys have a six-month time to live. Use a dedicated integration token, record its owner and expiry, and alert well before rotation.

Test a valid token and a missing token. Also test an expired token and a deleted token. Cognism documents 401 Unauthorized for missing or invalid credentials. Rotation is complete only when the new token works and the retired token fails.

Preview allowance and redemption credits are different meters

The Search guide and Enrich guide say previews do not consume contact redemption credits. A new contact Redeem does. Company redemptions and repeat redemptions of an already redeemed contact do not consume additional contact credits under the published help guidance.

Cognism's rate-limit documentation defines a separate preview-result allowance calculated as allocated credits multiplied by ten. Returned profiles from Search and Enrich reduce that allowance, and Redeem also counts toward it while using standard contact credits where applicable.

Record these response headers for every fixture request:

  • x-rate-total-limit and x-rate-total-limit-remaining;
  • x-rate-limit-reset;
  • endpoint limit and remaining headers;
  • x-rate-result-limit and x-rate-result-limit-remaining;
  • the result-limit reset header.

Measure the starting and ending values rather than predicting cost from request count. One request can return several preview profiles, and the commercial terms attached to the account may differ from the public examples.

Redeem accepts between one and 20 Redeem IDs per request in the current Redeem guide. Keep the first test to one approved contact. A larger batch makes it harder to isolate credit movement or a mismatched identity. It can also obscure a partial downstream failure.

Review the evidence behind each Match Score

Cognism's matching explanation describes the Match Score as an aggregate score. The Enrich matching documentation lists a default minMatchScore of 30 and says no data is returned when no profile reaches the configured threshold.

Unique identifiers such as an email address, LinkedIn URL, company website, or domain can strengthen a match. Names and titles add supporting signals, as do company details. Cognism does not publish the exact formula or the contribution of each field to an individual result, so do not turn a score into a percentage probability.

Preserve the submitted identifiers beside the score and preview. Test one expected match, one person with a stale title, one ambiguous identity, and one deliberate no-match. Then compare the redeemed record with the source fixture. The Developer Portal warns that API and Prospector results can differ because data updates and system changes do not always land at the same time.

Make CRM field rules explicit

Cognism's native CRM connectors have their own mapping and matching behavior. The public API does not inherit those rules. For a custom integration, define create versus update, duplicate matching, required fields, permissions, and error recovery in your own application.

The connector documentation can inform the design, but it does not establish custom API behavior. Cognism documents Apply if blank and Overwrite mapping choices for its Salesforce connector. It also warns about duplicate companies in HubSpot when HubSpot and Cognism create companies from different domain values.

Start with fill-only updates in the CRM sandbox. Let an accepted value populate a blank approved field, but hold changes to seller-corrected identity, account ownership, lifecycle or opportunity stage, and suppression. Choose one system to own company creation. Otherwise, two legitimate domain values can produce two company records and split the account history.

For every proposed write, retain the Cognism ID, Redeem ID, source CRM ID, destination object, and owner. Also retain the prior value, proposed value, mapping rule, timestamp, and final destination ID. Read the CRM record again after the write and verify the expected fields. A queue acknowledgement records only that the job was accepted.

Handle failures without blind Redeem retries

Cognism's troubleshooting guide and error reference document these public failure states:

  • 400 for malformed input, invalid pagination, unsupported fields, or a search outside subscribed entitlements;
  • 401 for a missing or invalid key;
  • 402 when the credit limit is exceeded;
  • 429 when an endpoint or overall rate limit is exceeded;
  • 500 for an internal server error.

The Developer Portal publishes a maximum of 1,000 requests per minute. Cognism help pages also discuss records-per-minute throughput. Requests and records are different units, so read the total and endpoint headers on each response, including the remaining values, and confirm the account's contracted limits.

Cognism recommends retry logic for rate limits, but its public material does not document idempotency keys or safe replay semantics. It also does not document a formal backoff schedule for credit-bearing Redeem calls. Put an ambiguous Redeem into a reconciliation queue. Check the returned record state and both allowance meters before deciding whether to repeat it.

Store the endpoint, request fingerprint, timestamp, status code, complete response body, relevant rate headers, and credit evidence. That is also the information Cognism asks customers to provide when escalating a failed API request to Support.

Run a controlled Cognism API release test

Use company-controlled or expressly consented fixture records, a dedicated token, a staging table, and a CRM sandbox. Disconnect any automation that could enroll a fixture into production outreach.

  1. Record the API access terms, token owner and expiry, enabled entitlements, starting contact credits, preview allowance, and rate headers.
  2. Send one valid authenticated request, then test missing, expired, and deleted credentials. Require the expected 401 behavior.
  3. Run a narrow Search and preserve the filters, preview, Match Score, Cognism ID, Redeem ID, returned profile count, and preview-allowance change.
  4. Enrich an expected match, stale-title record, ambiguous identity, and deliberate no-match. Compare the submitted identifiers, scores, previews, and selected results.
  5. Redeem one approved net-new contact. Read the complete entitled profile and reconcile both contact-credit and preview-allowance movement. Redeem the same contact again, then redeem one company. Verify the published credit behavior against the account rather than assuming it.
  6. Stage one accepted record without touching the CRM. Apply required-field, source, suppression, territory, owner, duplicate, freshness, fill-only, and protected-field rules.
  7. Create or update the fixture in the CRM sandbox. Test a duplicate, missing required field, denied write, apply-if-blank field, and blocked overwrite. Read every result back by destination ID.
  8. Exercise 400, 401, 402, a controlled 429, and a transient 500 path. Confirm that no paid Redeem retries blindly and every ambiguous request reaches reconciliation.
  9. Reverse the CRM changes, remove supported test data, delete the test token, and export the request, response, credit, field-change, and destination-ID evidence.

Hold release for any unexplained credit movement, preview mismatch, identity ambiguity, duplicate, suppression bypass, protected-field overwrite, missing destination ID, or Redeem result that cannot be reconciled safely.

LeadHaste can connect prospect research, enrichment, suppression, CRM ownership, and campaign execution in infrastructure your team controls. See our managed outbound services and outbound resources to define the acceptance fixture before production data moves.

Book your free ICP review →

Frequently Asked Questions

A modern outbound stack includes: data enrichment (Apollo, Clay, ZoomInfo), email infrastructure (Google Workspace, custom domains), sending tools (Smartlead, Instantly), warm-up services (Warmbox), LinkedIn automation (Expandi, Dripify), CRM integration (HubSpot, Salesforce), and analytics platforms. Most agencies use 15–30 tools orchestrated together.

Building your own stack costs $3K–5K/month in software alone, plus a dedicated person to manage it. With a managed service, you get all the tooling plus the expertise to orchestrate it, often at lower total cost. The key question: can you afford to spend 6–8 weeks setting up instead of generating pipeline?

There's no single 'best' tool. It depends on your volume, budget, and integration needs. Smartlead and Instantly are popular for high-volume sending. Apollo doubles as a data and sequencing platform. The real advantage comes from how tools are orchestrated together, not from any single tool choice.

Look for three things: (1) Do you own the infrastructure they build? (2) Are the engagement terms clear, including what happens after the initial build-and-learn period? (3) Can you see transparent metrics and real case studies with specific numbers? LeadHaste starts with a three-month engagement, then moves month-to-month. Avoid vague reporting and providers that own your domains.

Data enrichment is the process of taking basic company or contact data and adding layers of detail: job titles, direct emails, phone numbers, technographics, intent signals, company size, funding stage, and more. Enrichment tools like Apollo, Clay, and ZoomInfo pull from multiple data sources to build a complete prospect profile before outreach begins.

CognismAPIdata enrichmentCRM integration
Sofia Urrego

Sofia Urrego

Account Success, LeadHaste

Looks after LeadHaste accounts end to end, from targeting and copy through to the conversations that come back, so each client keeps improving month over month.

Newsletter

The weekly for people who buy outbound.

Five things that changed in outbound this week, why they matter, and what to do about each. Read by founders, sales leaders and growth leads at B2B companies.

Read past issues →

Ready to build outbound that compounds?

We'll build the entire system for your business, and the infrastructure it runs on stays yours.

Book my free review →