The Cognism API is used to search, preview and enrich Contacts and Accounts. Cognism database provides extensive B2B contacts and sales intelligence data.
\nNOTE: API responses may differ from the results retrieved via Prospector search (Web Application). We strive to ensure that the API is updated regularly to align as closely as possible with Prospector search results. However, discrepancies can occur due to various factors, including data updates and system enhancements. We appreciate your understanding and are committed to improving the accuracy and reliability of our API services.
\nThe new Cognism API reduces complexity when searching, and it simplifies data structure. Also, response time is greatly improved.
\nNOTE: Pagination of results is possible from first to last result, but you cannot hop between pages.
\nBenefits include:
\nBetter accuracy on technology and event searches
\nAbility to create more complex queries
\nThe new Cognism API also removes the limitation of 10,000 displayed results, making it now unlimited.
\nVisibility for all open positions for each contact - with different emails and company phones.
\nAbility to configure the response fields in line with the entitlements.
\nCredit burn remain as was, currently only on contacts, but not on account. This might change in the future.
\nCognism uses API keys to allow access to the APIs. The API Key is assigned to you by Cognism and it is used to authenticate and authorize each request.
\nYour API key should be kept private, and should never be displayed publicly.
\nAPI keys have a time-to-live [TTL] of 6 months.
\nYou can manually generate additional keys or remove existing ones using one of our tools:
\nCognism Prospector, or
\nCognism Refresh.
\nYou can authenticate HTTP requests in one of two ways:
\nUsing header field \"Authorization: Bearer {API KEY}\"
\nUsing query string \"api_key={API KEY}\"
\nKeep in mind that we recommend the use of the HTTP header field rather than the api_key query parameter as it provides an added level of security. The documentation uses HTTP header field in all examples.
\nAPI contains a set of HTTPS endpoints providing all necessary details to preview and redeem contacts of your choice.
\nThe API is built using RESTful endpoints and standard HTTP verbs.
\nEntitlements are a defined set of Contact and Account data that is available for you. They are set by Cognism Support Team.
\nEntitlement definition affects Search, Preview and Result. Entitlements are related to the API Key.
\nCognism API cannot be used unless Entitlements are properly set up.
\nNo matter what entitlement you choose, basic info will always be present. This is minimum data defining Contact or Account entity.
\nEntitlements are built on top of basic info.
\nBasic info for Contact entity
\n{\n \"id\": \"String (UUID)\",\n \"fullName\": \"String\",\n \"firstName\": \"String\",\n \"lastName\": \"String\",\n \"jobTitle\": \"String\",\n \"account\": \n {\n \"id\": \"String\",\n \"name\": \"String\"\n }\n}\n\nBasic info for Account entity
\n{\n \"id\": \"String\",\n \"name\": \"String\"\n}\n\nUse Predefined Contact Entitlements table to check full set of Contact supported fields. Entitlement affects Contact search and response data.
\nUse Predefined Account Entitlements table to check full set of Account supported fields. Entitlement affects Contact search and response data.
\nTo check how your entitlements are defined use MyEntitlementContact and MyEntitlementAccount.
\n\n\nActual returned object will contain fields based on user Entitlements
\n
Redeemed contact response complete object
\n{\n \"properties\": {\n \"totalResults\": {\n \"type\": \"integer\"\n },\n \"results\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"account\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"officePhoneNumbers\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"string\"\n },\n \"numberType\": {\n \"type\": \"string\"\n },\n \"label\": {\n \"type\": \"string\"\n },\n \"score\": {\n \"type\": \"integer\"\n },\n \"addressType\": {\n \"type\": \"string\"\n },\n \"ext\": {\n \"type\": \"string\"\n },\n \"dnc\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"boolean\"\n }\n }\n }\n }\n }\n ]\n },\n \"hqPhoneNumbers\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"string\"\n },\n \"numberType\": {\n \"type\": \"string\"\n },\n \"label\": {\n \"type\": \"string\"\n },\n \"score\": {\n \"type\": \"integer\"\n },\n \"addressType\": {\n \"type\": \"string\"\n },\n \"ext\": {\n \"type\": \"string\"\n },\n \"dnc\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"boolean\"\n }\n }\n }\n }\n }\n ]\n },\n \"hiringEvent\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"country\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"jobTitle\": {\n \"type\": \"string\"\n },\n \"department\": {\n \"type\": \"string\"\n },\n \"jobType\": {\n \"type\": \"string\"\n },\n \"internship\": {\n \"type\": \"boolean\"\n },\n \"jobHours\": {\n \"type\": \"string\"\n },\n \"workFromHome\": {\n \"type\": \"boolean\"\n },\n \"employer\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\"\n },\n \"jobDate\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n },\n \"fundingEvent\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"announcedOn\": {\n \"type\": \"long\"\n },\n \"fundingType\": {\n \"type\": \"string\"\n },\n \"series\": {\n \"type\": \"string\"\n },\n \"moneyRaisedUsd\": {\n \"type\": \"long\"\n },\n \"postMoneyValuationUsd\": {\n \"type\": \"long\"\n },\n \"investors\": {\n \"type\": \"array\",\n \"description\": \"List of investor names\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"type\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"ipoEvent\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"wentPublicOn\": {\n \"type\": \"long\"\n },\n \"stockExchangeSymbol\": {\n \"type\": \"string\"\n },\n \"stockSymbol\": {\n \"type\": \"string\"\n },\n \"openingValuationUsd\": {\n \"type\": \"long\"\n },\n \"moneyRaisedUsd\": {\n \"type\": \"long\"\n },\n \"investors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"type\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"acquisitionEvent\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"acquiredOn\": {\n \"type\": \"string\"\n },\n \"acquisitionType\": {\n \"type\": \"string\"\n },\n \"acquirer\": {\n \"type\": \"string\"\n },\n \"acquiree\": {\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"headcount\": {\n \"type\": \"integer\"\n },\n \"sizeTo\": {\n \"type\": \"integer\"\n },\n \"sizeFrom\": {\n \"type\": \"integer\"\n },\n \"location\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"addressType\": {\n \"type\": \"string\"\n },\n \"country\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"zip\": {\n \"type\": \"string\"\n },\n \"street\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n },\n \"technologies\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"type\": {\n \"type\": \"string\"\n },\n \"domain\": {\n \"type\": \"string\"\n },\n \"industry\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"revenue\": {\n \"type\": \"long\"\n },\n \"linkedinUrl\": {\n \"type\": \"string\"\n },\n \"website\": {\n \"type\": \"string\"\n },\n \"founded\": {\n \"type\": \"integer\"\n },\n \"lastConfirmed\": {\n \"type\": \"long\"\n },\n \"naics\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"sic\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"isic\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"shortDescription\": {\n \"type\": \"string\"\n },\n \"description\": {\n \"type\": \"string\"\n }\n }\n },\n \"jobTitle\": {\n \"type\": \"string\"\n },\n \"lastName\": {\n \"type\": \"string\"\n },\n \"firstName\": {\n \"type\": \"string\"\n },\n \"fullName\": {\n \"type\": \"string\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"privacyNotificationSent\": {\n \"type\": \"boolean\"\n },\n \"previousAccounts\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"location\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"addressType\": {\n \"type\": \"string\"\n },\n \"country\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"zip\": {\n \"type\": \"string\"\n },\n \"street\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n },\n \"title\": {\n \"type\": \"string\"\n },\n \"start\": {\n \"type\": \"string\"\n },\n \"end\": {\n \"type\": \"string\"\n },\n \"seniority\": {\n \"type\": \"string\"\n },\n \"jobFunction\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"email\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\"\n },\n \"quality\": {\n \"type\": \"string\"\n }\n }\n },\n \"managementLevel\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n },\n \"skills\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"linkedinUrl\": {\n \"type\": \"string\"\n },\n \"email\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\"\n },\n \"quality\": {\n \"type\": \"string\"\n },\n \"sha256\": {\n \"type\": \"string\"\n }\n }\n },\n \"mobilePhoneNumbers\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"string\"\n },\n \"numberType\": {\n \"type\": \"string\"\n },\n \"label\": {\n \"type\": \"string\"\n },\n \"score\": {\n \"type\": \"integer\"\n },\n \"addressType\": {\n \"type\": \"string\"\n },\n \"ext\": {\n \"type\": \"string\"\n },\n \"dnc\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"boolean\"\n }\n }\n }\n }\n }\n ]\n },\n \"directPhoneNumbers\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"string\"\n },\n \"numberType\": {\n \"type\": \"string\"\n },\n \"label\": {\n \"type\": \"string\"\n },\n \"score\": {\n \"type\": \"integer\"\n },\n \"addressType\": {\n \"type\": \"string\"\n },\n \"ext\": {\n \"type\": \"string\"\n },\n \"dnc\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"boolean\"\n }\n }\n }\n }\n }\n ]\n },\n \"education\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"start\": {\n \"type\": \"string\"\n },\n \"end\": {\n \"type\": \"string\"\n },\n \"school\": {\n \"type\": \"string\"\n },\n \"degree\": {\n \"type\": \"string\"\n },\n \"field\": {\n \"type\": \"string\"\n },\n \"description\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n },\n \"country\": {\n \"type\": \"string\"\n },\n \"region\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"street\": {\n \"type\": \"string\"\n },\n \"zip\": {\n \"type\": \"string\"\n },\n \"positionStartDate\": {\n \"type\": \"string\"\n },\n \"seniority\": {\n \"type\": \"string\"\n },\n \"jobFunction\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"managementLevel\": {\n \"type\": \"string\"\n },\n \"lastConfirmed\": {\n \"type\": \"long\"\n },\n \"locationMoveEvent\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"date\": {\n \"type\": \"string\"\n },\n \"from\": {\n \"type\": \"object\",\n \"properties\": {\n \"country\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"region\": {\n \"type\": \"string\"\n }\n }\n },\n \"to\": {\n \"type\": \"object\",\n \"properties\": {\n \"country\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"region\": {\n \"type\": \"string\"\n }\n }\n }\n }\n }\n ]\n },\n \"jobLeaveEvent\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"date\": {\n \"type\": \"string\"\n },\n \"from\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"sizeTo\": {\n \"type\": \"integer\"\n },\n \"sizeFrom\": {\n \"type\": \"integer\"\n },\n \"title\": {\n \"type\": \"string\"\n }\n }\n },\n \"to\": {\n \"type\": \"object\",\n \"properties\": {\n \"industry\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"sizeTo\": {\n \"type\": \"integer\"\n },\n \"sizeFrom\": {\n \"type\": \"integer\"\n },\n \"title\": {\n \"type\": \"string\"\n }\n }\n }\n }\n }\n ]\n },\n \"jobJoinEvent\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"date\": {\n \"type\": \"string\"\n },\n \"from\": {\n \"type\": \"object\",\n \"properties\": {\n \"industry\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"sizeTo\": {\n \"type\": \"integer\"\n },\n \"sizeFrom\": {\n \"type\": \"integer\"\n },\n \"title\": {\n \"type\": \"string\"\n }\n }\n },\n \"to\": {\n \"type\": \"object\",\n \"properties\": {\n \"industry\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"sizeTo\": {\n \"type\": \"integer\"\n },\n \"sizeFrom\": {\n \"type\": \"integer\"\n },\n \"title\": {\n \"type\": \"string\"\n }\n }\n }\n }\n }\n ]\n },\n \"redeemId\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n }\n }\n}\n\nRedeemed account response complete object
\n{\n \"properties\": {\n \"totalResults\": {\n \"type\": \"integer\"\n },\n \"results\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"officePhoneNumbers\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"string\"\n },\n \"numberType\": {\n \"type\": \"string\"\n },\n \"label\": {\n \"type\": \"string\"\n },\n \"score\": {\n \"type\": \"integer\"\n },\n \"addressType\": {\n \"type\": \"string\"\n },\n \"ext\": {\n \"type\": \"string\"\n },\n \"dnc\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"boolean\"\n }\n }\n }\n }\n }\n ]\n },\n \"hqPhoneNumbers\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"string\"\n },\n \"numberType\": {\n \"type\": \"string\"\n },\n \"label\": {\n \"type\": \"string\"\n },\n \"score\": {\n \"type\": \"integer\"\n },\n \"addressType\": {\n \"type\": \"string\"\n },\n \"ext\": {\n \"type\": \"string\"\n },\n \"dnc\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"boolean\"\n }\n }\n }\n }\n }\n ]\n },\n \"hiringEvent\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"country\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"jobTitle\": {\n \"type\": \"string\"\n },\n \"department\": {\n \"type\": \"string\"\n },\n \"jobType\": {\n \"type\": \"string\"\n },\n \"internship\": {\n \"type\": \"boolean\"\n },\n \"jobHours\": {\n \"type\": \"string\"\n },\n \"workFromHome\": {\n \"type\": \"boolean\"\n },\n \"employer\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\"\n },\n \"jobDate\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n },\n \"fundingEvent\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"announcedOn\": {\n \"type\": \"long\"\n },\n \"fundingType\": {\n \"type\": \"string\"\n },\n \"series\": {\n \"type\": \"string\"\n },\n \"moneyRaisedUsd\": {\n \"type\": \"long\"\n },\n \"postMoneyValuationUsd\": {\n \"type\": \"long\"\n },\n \"investors\": {\n \"type\": \"array\",\n \"description\": \"List of investor names\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"type\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"ipoEvent\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"wentPublicOn\": {\n \"type\": \"integer\"\n },\n \"stockExchangeSymbol\": {\n \"type\": \"string\"\n },\n \"stockSymbol\": {\n \"type\": \"string\"\n },\n \"openingValuationUsd\": {\n \"type\": \"integer\"\n },\n \"moneyRaisedUsd\": {\n \"type\": \"integer\"\n },\n \"investors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"type\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"acquisitionEvent\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"acquiredOn\": {\n \"type\": \"string\"\n },\n \"acquisitionType\": {\n \"type\": \"string\"\n },\n \"acquirer\": {\n \"type\": \"string\"\n },\n \"acquiree\": {\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"headcount\": {\n \"type\": \"integer\"\n },\n \"sizeTo\": {\n \"type\": \"integer\"\n },\n \"sizeFrom\": {\n \"type\": \"integer\"\n },\n \"location\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"addressType\": {\n \"type\": \"string\"\n },\n \"country\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"type\": \"string\"\n },\n \"city\": {\n \"type\": \"string\"\n },\n \"zip\": {\n \"type\": \"string\"\n },\n \"street\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n },\n \"technologies\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"type\": {\n \"type\": \"string\"\n },\n \"domain\": {\n \"type\": \"string\"\n },\n \"industry\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"revenue\": {\n \"type\": \"long\"\n },\n \"linkedinUrl\": {\n \"type\": \"string\"\n },\n \"website\": {\n \"type\": \"string\"\n },\n \"founded\": {\n \"type\": \"integer\"\n },\n \"lastConfirmed\": {\n \"type\": \"long\"\n },\n \"naics\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"sic\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"isic\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"string\"\n }\n ]\n },\n \"shortDescription\": {\n \"type\": \"string\"\n },\n \"description\": {\n \"type\": \"string\"\n }\n }\n }\n ]\n }\n }\n}\n\nAll API requests are subject to rate limits that exist independently of your API key's monthly usage allowance. The maximum rate limit is 1,000 requests per minute.
\nNumber of previews available - Number of credits available, multiplied by 10.
\nUse the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.
\nThe rate limit ceiling for all endpoints for the 1 minute window.
\nThe number of requests left remaining for the 1 minute window.
\nNumber of seconds before rate limits are reset.
\nUser name.
\nThe rate limit ceiling for single endpoints for the 1 minute window.
\nThe number of requests left remaining for single endpoints for the 1 minute window.
\nTotal number of preview profiles within API contract. Calculated as number of credits x 10.
\nTotal number of remaining requests within API contract.
\nNumber of seconds before rate result limit is reset (until end of current contract).
\nThe limit on preview profiles (contact or account). Limit is calculated as number of allocated credits x 10, e.g. 1 000 000 credits = 10 000 000 preview limit. Preview limit is decreased by the number of returned preview profiles on Search and Enrich endpoints. Usually single Search request decreases the preview limit by 20 (default index size) and Enrich by 1.
\nRedeem endpoint uses standard credits and does not decreases preview limit.
\nThis response code is returned when an application exceeds the rate limit for a given API endpoint, and the following error is returned in the response body:
\n{ \"errors\": [ { \"code\": 88, \"message\": \"Rate limit exceeded\" } ] }.
Each input parameter contributes to an overall match score, which represents the confidence level of a match.
\nConstant fields such as firstName, lastName, and email have consistent scoring weight.
\nDynamic fields such as jobTitle or accountName are weighted based on specificity and uniqueness:
\n“Software Engineer” adds fewer points than “Senior Machine Learning Engineer” because it is more general.
\n\n\nIf no profile meets your minMatchScore threshold, the API returns no data.
\n
Every enrichment result is scored. The default minMatchScore is 30, which provides a balanced level between accuracy and match rate.
\nYou can adjust this value depending on your use case:
\n\n\nIt is not recommended to use minMatchScore above 45. Increase in accuracy is almost non existent above this threshold.
\n
{\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"jobTitle\": \"Senior Product Designer\",\n \"accountWebsite\": \"test.com\",\n \"minMatchScore\": 45\n}\n\nBehavior:
Tight score threshold (minMatchScore ≥ 45).
Returns a result only if contact data strongly matches all criteria, it will possibly miss on good match in case of data change.
Best for precise identity resolution and when input data is high quality
{\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"jobTitle\": \"Software Engineer\",\n \"accountName\": \"Acme Corp\",\n \"minMatchScore\": 28\n}\n\nBehavior:
Looser threshold (minMatchScore ≥ 28).
May return one of several potential contacts having same firstName and lastName with full or partial match on accountName or jobTitle. Suitable for wide data discovery or when inputs are uncertain.
{\n \"email\": \"john.doe@test.com\"\n}\n\nBehavior:
Direct identifier match.
Typically scores between 40–49.
Not the best use case for Enrich endpoint
\n\nIt is also recommended to use Search endpoint for cases like this. There is no benefit of scoring mechanism when input is single field, it will come down to match or no match
\n
With an unexpected response, usually, one of the below HTTP codes will be returned. Check the table for help with error messages and troubleshooting steps.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Authentication","slug":"authentication"},{"content":"API structure","slug":"api-structure"},{"content":"Entitlements","slug":"entitlements"},{"content":"Response schema","slug":"response-schema"},{"content":"Rate Limiting","slug":"rate-limiting"},{"content":"Matching strategies for Enrich endpoint","slug":"matching-strategies-for-enrich-endpoint"},{"content":"Error response messages","slug":"error-response-messages"}],"owner":"14862827","collectionId":"58d2e00d-2fc0-4594-89e3-3c6d43bf293d","publishedId":"UVJhBu4C","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"282850","highlight":"4e3cbb"},"publishDate":"2023-10-25T12:27:07.000Z"},"item":[{"name":"Search API","item":[{"name":"Search Contacts","id":"6c453b29-38c4-4037-8c09-7ba084bb3b7f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Search Contacts and see preview data.
\n\n\n","urlObject":{"path":["api","search","contact","search"],"host":["https://app.cognism.com"],"query":[{"description":{"content":"Dot denotes field is one level deep. Field name on the right side of the dot is child object of the object on the left side of the dot
\n
Number of results in one result set. Default 20. Max 100.
\n","type":"text/plain"},"key":"indexSize","value":"25"},{"description":{"content":"Last returned key used to fetch next set of results. If empty, first set of results is returned
\n","type":"text/plain"},"key":"lastReturnedKey","value":""}],"variable":[]}},"response":[{"id":"efb074d2-3866-4077-83f1-5b4fa7d627cf","name":"Search Contacts Advanced Entitlement","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"BearerSearch Accounts and see preview data.
\n\n\n","urlObject":{"path":["api","search","account","search"],"host":["https://app.cognism.com"],"query":[{"description":{"content":"Dot denotes field is one level deep. Field name on the right side of the dot is child object of the object on the left side of the dot
\n
Number of results in one result set. Default 20. Max 100.
\n","type":"text/plain"},"key":"indexSize","value":"100"},{"key":"lastReturnedKey","value":""}],"variable":[]}},"response":[{"id":"8795b8a9-0f4a-452a-8fdc-2fccdb92d5db","name":"Search Account Advanced Entitlement","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"BearerUse this API to search Cognism Contacts and Accounts dataset by different parameters. The search and response models are dependant on defined Entitlement.
\nSearch results contain records that match all input search criteria.
\nCheck Utility API for search filter values.
\n\n\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"a172740b-b7e6-44e4-a3e7-f303fbca6165","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"2dc2ab69-724c-4570-9145-2f00927407ca","type":"text/javascript","exec":[""]}}],"_postman_id":"45a5a5b0-04d6-4935-8ef1-9e566f4da764"},{"name":"Redeem API","item":[{"name":"Redeem Contacts by IDs","id":"cd09a2d5-0abb-4fbe-9114-a53bf2f903ec","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Each Array field can have up to 1000 search terms in a single request.
\n
Redeem Contacts by request IDs. Use \"redeemId\" field from Search and Enrich API response.
\n\n\nCheck response object schema under Response schema / Contact
\n
The redeemId is a unique identifier for a contact in a specific job title at a specific account. It differs from a “normal” contact ID (id) in that it encodes not just the person, but also their current job title and company.
redeemId changesredeemId changes whenever any of the components change:
If the same person (same id) moves to a different job title, the redeemId will be different.
If the same person moves to a different account/company, redeemId changes.
If nothing changes (same person, same job title, same company), the redeemId remains the same.
redeemIdIf you try to redeem (or use) a redeemId that has since become outdated (because the contact’s job title or company changed), our API will fallback to the updated redeemId.
In that case, you will still be able to get the contact, and we will provide the new/current redeemId in the response alongside the contact’s data.
This allows us to uniquely and stably (within a job-title/account context) identify a contact.
\nProvides flexibility: if someone moves jobs or companies, clients using previous redeemIds won’t break; they will get redirected to the current redeemId.
\nOptional parameter. Merge phones and locations. Boolean value, default false.
\n","type":"text/plain"},"key":"mergePhonesAndLocations","value":""}],"variable":[]}},"response":[{"id":"9f96d3fe-e765-4659-8d1c-7b482392b292","name":"Redeem Contact Advanced Entitlement","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"BearerRedeem Accounts by request IDs. Use \"id\" field from Search and Enrich API response.
\n\n\n","urlObject":{"path":["api","search","account","redeem"],"host":["https://app.cognism.com"],"query":[{"description":{"content":"Check response object schema under Response schema / Account
\n
Optional parameter. Merge phones and locations. Boolean value, default false.
\n","type":"text/plain"},"key":"mergePhonesAndLocations","value":""}],"variable":[]}},"response":[{"id":"9385e042-a0bd-4e85-9a37-62388d59620b","name":"Redeem Advanced Entitlement","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"BearerRedeem Contacts or Accounts by providing IDs. Response includes data as per subscribed Entitlement.
Provide one or up to 20 IDs inside list of redeemIDs.
\n\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"6377b9d9-3566-4729-899f-b3491ade4bbe","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"07668ad1-9bb7-4fb4-b99b-d4b0f15ae548","type":"text/javascript","exec":[""]}}],"_postman_id":"92839ed2-f9ce-4ba7-a03b-c7451ea4420f"},{"name":"Enrich API","item":[{"name":"Enrich Contact","event":[{"listen":"test","script":{"id":"f5dcdcf7-6711-4aa5-b58e-94f9e6323663","exec":["var idsToDelete = ['98135',\r"," '98128',\r"," '98125',\r"," '98123',\r"," '98119',\r"," '77343',\r"," '79419',\r"," '164323',\r"," '100397',\r"," '99268',\r"," '92947',\r"," '122137',\r"," '216840',\r"," '200275',\r"," '197281',\r"," '196960',\r"," '163639',\r"," '163625',\r"," '99981'];\r","\r","// Function to delete an ID\r","function deleteID(id) {\r"," return new Promise((resolve, reject) => {\r"," pm.sendRequest({\r"," url: 'https://app.cognism.com/api/prospector/campaigns/' + id,\r"," method: 'DELETE',\r"," header: {\r"," 'Content-Type': 'application/json',\r"," 'X-Session-Token': \"\"\r"," }\r"," }, (err, res) => {\r"," if (err) {\r"," reject(err);\r"," } else {\r"," resolve(res);\r"," }\r"," });\r"," });\r","}\r","\r","// Loop through each ID and call deleteID function\r","async function deleteIDs() {\r"," for (let id of idsToDelete) {\r"," try {\r"," let response = await deleteID(id);\r"," console.log(\"Deleted ID:\", id);\r"," console.log(\"Response:\", response);\r"," } catch (error) {\r"," console.error(\"Error deleting ID:\", id, error);\r"," }\r"," }\r","}\r","\r","// Call the function to start deleting IDs\r","deleteIDs();"],"type":"text/javascript","packages":{}}}],"id":"157c4853-80fc-4f50-a538-8d92bda2cc57","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Usual workflow is using Search API and finding IDs of your interest before redeeming
\n
Enrich your contacts by providing input parameters. Response info depends on your Entitlement.
In order to match contact accurately, use one of search criteria
* Unique identifiers such as email/sha256 or linkedinUrl.
* Combine firstName, lastName and jobTitle with accountName or with account unique identifiers accountWebsite
* Provide as many input parameters as you can and we will return back best possible match
Default minMatchScore is 30 and data will not be returned if profile is scored less. In general, everything scored <27 indicates low quality match. However, minMatchScore can be defined as search parameter.
\n\n\nphoneNumber enrichment searches all types of phone numbers
\n
Approximate score based on matched parameters (🟢Match 🟡Partial match 🔴No match)
\nAnchor Fields allow you to specify input fields that must match. By default, firstName and lastName are Anchor Fields for Contact enrich. If any of Anchor Fields do not match, other parameters matching is irrelevant and no data is returned.
\n\n\nAnchor Fields do not affect score
\n
In the example below, no data is returned since accountName did not match. If accountName was not defined inside anchorFields, expected matchScore would be as per table above (30-50).
\n{\n \"firstName\": \"Stjepan\",🟢\n \"lastName\": \"Buljat\",🟢\n \"jobTitle\": \"CTO and Co-Founder\",🟢\n \"accountName\": \"Kaspr\",🔴\n \"anchorFields\": [\n \"accountName\"\n ]\n}\n\nEnrich your accounts by providing input parameters. Response info depends on your Entitlement.
In order to match account accurately, use one of search criteria
Default minMatchScore is 40 and data will not be returned if profile is scored less. In general, everything scored <35 indicates low quality match. However, minMatchScore can be defined as search parameter.
\nApproximate score based on matched parameters (🟢Match 🟡Partial match 🔴No match)
\nAccount Enrich supports Anchor Fields, same rules apply as on Contact Enrich.
\n","urlObject":{"path":["api","search","account","enrich"],"host":["https://app.cognism.com"],"query":[],"variable":[]}},"response":[{"id":"4326fe20-a145-46fc-9e9f-9112608bc4e6","name":"Enrich Account by website Advanced Entitlement","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"BearerUse Enrich API to enrich and update you data. Enrich supports finding single best match according to provided parameters.
\n\n\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"e9b68f1b-8c8f-4a52-9dc4-78b3303ca9cd","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"1165bdd3-9533-4f87-9035-c093535c2a06","type":"text/javascript","exec":[""]}}],"_postman_id":"2a33be06-e764-4ce9-9093-4be52d2c8e70"},{"name":"Entitlement API","item":[{"name":"Get Contact Entitlement Details","id":"0c23e257-7198-4fd1-83f7-46632d3120a3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"MatchScore value depends on how well and how many input parameters have matched returned contact/account profile.
\n
Get details of subscribed Contact Entitlement
\n","urlObject":{"path":["api","search","entitlement","contactEntitlementSubscription"],"host":["https://app.cognism.com"],"query":[],"variable":[]}},"response":[{"id":"8fe85ed3-731e-4b0f-8978-ea0638b161d3","name":"Contact Advanced Entitlement","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"BearerGet details of subscribed Account Entitlement
\n","urlObject":{"path":["api","search","entitlement","accountEntitlementSubscription"],"host":["https://app.cognism.com"],"query":[],"variable":[]}},"response":[{"id":"6ded61a4-c3c0-40e5-8d68-c9213ae6775e","name":"Account Advanced Entitlement","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"BearerList supported technologies. Use optional search parameter to retreive list of matching technologies
\n","urlObject":{"path":["api","search","filter","technologiesSearch"],"host":["https://app.cognism.com"],"query":[{"description":{"content":"Name of the last fetched technology
\n","type":"text/plain"},"key":"lastReturnedKey","value":""},{"description":{"content":"Search filter. Leave it empty if you want to fetch all technologies
\n","type":"text/plain"},"key":"search","value":""},{"description":{"content":"Index Size. Default size is 20. Maximum size is 10 000
\n","type":"text/plain"},"key":"indexSize","value":"20"}],"variable":[]}},"response":[],"_postman_id":"95532229-02b1-479e-9ad9-547a1d84fd5e"},{"name":"Management Levels","id":"6a348ac4-907d-4159-acae-35fcaa91a9ab","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Include pageKey in the parameters to request next page.
\nPageKey is used for pagination and is returned with every response
\n","urlObject":{"path":["api","search","contact","optOut"],"host":["https://app.cognism.com"],"query":[{"key":"pageSize","value":"100"},{"disabled":true,"key":"pageKey","value":null}],"variable":[]}},"response":[],"_postman_id":"be459a87-3a33-478a-89e1-54be764a4e7b"},{"name":"Search Opt-Out by Email","id":"f66bb3cf-aa90-4a97-bce8-27f7fdfd25f2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Compliance API exposes three endpoints for checking contact Opt-out status.
\nOpt-Out List returns all contacts that have Opt-out.
\nSearch Opt-out by Email and by Id endpoints can be called with the contact's Email or Cognism Id.
\nHTTP status code 200 indicates Contact has chose to Opt-out.
\nHTTP status code 404 indicates Contact has not chose to Opt-out
\n","_postman_id":"5f2f007c-bbe1-4fe8-b788-bb4b4e144fe1"}],"event":[{"listen":"prerequest","script":{"id":"aec2741d-79e8-448e-a852-f21731eacd2a","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"2b65eb9e-647c-482d-9905-51217cd05349","type":"text/javascript","exec":[""]}}]}