Search and Access Records Using the Cognism API

This guide explains how to use the Search API to find records and the Redeem API to access full profile data. By understanding how previews, credits, and limits work, you can efficiently integrate Cognism data into your workflows.

Prerequisites

• You have API access enabled for your account 
• You have a valid API key 
• Your account includes available credits 

How the Cognism API works

The Search API lets you:

• Search for Contacts and Accounts using filters 
• Preview records that match your search criteria 

The Redeem API lets you:

• Access full profile data for selected records 

Search results depend on your Entitlement.

API results may differ slightly from the Cognism platform due to data updates or entitlement rules.

Search using the Search API

Use the Search API to find Contacts or Accounts based on specific filters.

What the Search API returns

When you call the Search API:

• Cognism returns a preview of matching records 
• Each field is returned as true or false, indicating data availability 
• Results are limited by your Entitlement 

Search requests do not consume credits.

Preview usage counts towards your preview limit.

Preview limits

Your preview limit is calculated as:

Number of credits × preview multiplier

• The default multiplier is 10 

Example: 
15,000 credits allow up to 150,000 previews.

Each request reduces your preview limit based on the number of records returned:

• Search requests typically reduce it by 20 (default index size) 
• Enrich requests reduce it by 1 per profile 

Search API limits

• Request 20 to 100 records per call 
• Maximum of 1,000 records per minute

Below is an example request for the Search API:

curl --location --request POST'https://app.cognism.com/api/search/contact/search?lastReturnedKey=&indexSize=20' \
--header 'Authorization: Bearer <My-Api-Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName":"Stjepan",
    "lastName":"Buljat",
    "jobTitles":[
        "CTO"
     ],
    "excludeJobTitles":[
        "CEO"
     ],
    "regions":[
        "EMEA"
     ],
    "mobilePhoneNumbers":{
        "highPlus":true
     },
    "emailQuality":{
        "highPlus":true
     },
    "account":{
        "names":[
            "Cognism"
        ],
        "officePhoneNumbers":{
            "medium":true
        }
      }
}'

Below is an example response for the Search API:

{
   "lastReturnedKey":"190898491634000_~9d674a67-a4b2-3ddc-9c7e-e96a64ef0228",
   "totalResults":1,
   "results":[
     {
       "id":"7351d07c-9118-403b-a7c1-d6510cc0c378",
       "fullName":"Stjepan Buljat",
       "firstName":"Stjepan",
       "lastName":"Buljat",
       "jobTitle":"CTO",
       "hasManagementLevel":true,
       "hasSeniority":true,
       "hasJobFunction":true,
       "hasPositionStartDate":true,
       "hasEmail":true,
       "hasMobilePhoneNumbers":false,
       "hasDirectPhoneNumbers":false,
       "hasOfficePhoneNumbers":false,
       "hasHqPhoneNumbers":true,
       "hasJobJoinEvent":false,
       "hasJobLeaveEvent":false,
       "hasLocationMoveEvent":false,
       "hasCountry":true,
       "hasState":false,
       "hasCity":true,
       "hasZip":false,
       "hasStreet":true,
       "hasLinkedinUrl":true,
       "hasYearOfBirth":true,
       "hasCrunchbaseUrl":false,
       "hasEducation":true,
       "hasPreviousAccount":true,
       "hasSkills":true,
       "hasLastConfirmed":true,
       "redeemId":"MzRkNjMzYjctNDFlYS0zYWM3LWEyODAtNDMxZDcx
                   ZmQ3N2ViOzhkMDlhZGJhLTczMDYtMzhlMS1iODRi
                   LWU4NmU2OWU3MGU3YjtlZmM2ZDk3NS04NTk5LTM4
                   YWItOGNmZS1lMWM0MmFjMTZkYzY",
       "account":{
         "id":"efc6d975-8599-38ab-8cfe-e1c42ac16dc6",
         "name":"Cognism",
         "hasDomain":true,
         "hasIndustries":true,
         "hasDescription":true,
         "hasShortDescription":true,
         "hasFounded":true,
         "hasWebsite":true,
         "hasCrunchbaseURL":true,
         "hasLinkedinURL":true,
         "hasRevenue":true,
         "hasSic":true,
         "hasIisc":false,
         "hasNaics":true,
         "hasSize":false,
         "hasTechnologies":true,
         "hasType":true,
         "hasCountry":true,
         "hasState":true,
         "hasCity":true,
         "hasZip":true,
         "hasStreet":true,
         "hasOfficePhoneNumbers":false,
         "hasHqPhoneNumbers":true,
         "hasHiringEvent":true
        }
      }
   ]
}

Access full records using the Redeem API

After receiving a Search API response, use the Redeem API to access full profile data.

Redeem a record

1. Go to the Search API response 
2. Identify the redeemId field 
3. Use the redeemId in a Redeem API request 

The Redeem API returns all fields included in your Entitlement.

Redeem API limits

• Request 1 to 20 redeem IDs per call 
• Maximum of 1,000 records per minute 

Example Redeem API Request

curl --location --request POST'https://app.cognism.com/api/search/contact/redeem' \
--header 'Authorization: Bearer <My-Api-Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "redeemIds":[
        "MzRkNjMzYjctNDFlYS0zYWM3LWEyODAtNDMxZDcxZmQ3N2ViOzhkMDlhZGJhLTczMDYtMzhlMS1iODRiLWU4NmU2OWU3MGU3YjtlZmM2ZDk3NS04NTk5LTM4YWItOGNmZS1lMWM0MmFjMTZkYzY"
    ]
}'

How credits are charged

Credits are charged based on how you use the API and your account configuration.

Credit model

The API supports two credit models:

• Companion credits (standard credits) 
• Bulk credits 

Which model applies depends on your account setup.

If Companion credit consumption is enabled, the API uses Companion credits. Otherwise, it uses Bulk credits.

When credits are consumed

Credits are only consumed when using the Redeem API.

• One credit is charged per contact 
• Redeeming companies does not consume credits 
• Search and Enrich APIs do not consume credits 

Redeeming the same record

You are not charged again for redeeming the same contact.

A credit is only consumed again if the contact’s:

• Job title changes 
• Company changes 

This behaviour matches the Cognism platform.

Preview limits and credits

Preview limits still apply and are based on your available credits.

Credits × 10 = preview limit (default multiplier)

API and platform consistency

Credit consumption works the same way in the API and the Cognism platform.

Expected results

After completing these steps, you can:

• Preview Contacts and Accounts using filters 
• Control when credits are spent by redeeming records 
• Access full profile data based on your Entitlement