Learn how to use Cognism’s Enrich and Redeem APIs to find, preview, and access contact and company data. Understand match scores, credits, and API limits.
Use the Enrich API to find and preview matching contacts or companies in Cognism using the data points you provide. Use the Redeem API to retrieve the full record once you’ve confirmed the preview looks correct.
API results can differ from what you see in Prospector (web app). This can happen due to data refreshes, product updates, and differences in how matching is performed.
Prerequisites
Before you start, make sure:
- Your Cognism API access is set up.
- You have a valid API key.
- Your subscription includes the required Entitlements and (if applicable) credits.
Use the Enrich API
When you call the Enrich API, Cognism returns:
- A matchScore for the best match.
- A list of results.
- A preview of field availability using true/false flags (for example, hasEmail, hasMobilePhoneNumbers). These flags indicate whether Cognism has data for that field, based on your Entitlements.
Improve company match accuracy
- Use unique identifiers like website, domain, or linkedinUrl.
- Provide as many fields as possible.
Improve contact match accuracy
- Use unique identifiers like email or linkedinUrl.
- If you do not have a unique identifier, use a combination of firstName, lastName, and jobTitle with an account identifier like accountName or accountWebsite.
- Provide as many fields as possible.
Below is an example request to Enrich API:
curl --location --request POST'https://app.cognism.com/api/search/contact/enrich' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <My-Api-Key>' \
--data-raw '{
"email":"stjepan.buljat@cognism.com"
}'Below is an example response from the Enrich API:
{
"matchScore":42,
"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,
"hasJobJoinEvent":false,
"hasJobLeaveEvent":false,
"hasLocationMoveEvent":false,
"hasCountry":true,
"hasState":false,
"hasCity":true,
"hasZip":false,
"hasStreet":true,
"hasLinkedinUrl":true,
"hasYearOfBirth":true,
"hasCrunchbaseUrl":false,
"hasEducation":true,
"hasPreviousAccounts":true,
"hasSkills":true,
"hasLastConfirmed":true,
"redeemId":"MzRkNjMzYjctNDFlYS0zYWM3LWEyODAtNDMxZDcxZmQ3N2ViOzhkMDlhZGJhLTczMDYtMzhlMS1iODRiLWU4NmU2OWU3MGU3YjtlZmM2ZDk3NS04NTk5LTM4YWItOGNmZS1lMWM0MmFjMTZkYzY",
"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,
"hasIsic":false,
"hasNaics":true,
"hasSize":true,
"hasTechnologies":true,
"hasType":true,
"hasLocation":true,
"hasOfficePhoneNumbers":false,
"hasHqPhoneNumbers":true,
"hasHiringEvent":true
}
}
]
}Understand MatchScore
matchScore is based on how many data points were matched for the returned contact or company.
- The default minimum matchScore is 30.
- Cognism does not return data if the score is below 30.
- Scores below 27 are considered low quality.
- You can change the minimum score using minMatchScore in your request.
Access records using the Redeem API
Use the Redeem API after Enrich, once you’re happy with the preview.
- Copy the redeemId from the Enrich response.
- Send it in the Redeem API request.
- Cognism returns the full profile for that record, based on your Entitlements.
Redeem limits
- You can request 1 to 20 redeemIds per call.
- Limit: 1,000 records per minute.
Example Redeem 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"
]
}'Example Redeem response (full record)
(this is a small example of data that can be returned. For a more advanced example, check out our documentation here):
{
"total": 1,
"result": [
{
"id": "7351d07c-9118-403b-a7c1-d6510cc0c378",
"fullName": "Stjepan Buljat",
"firstName": "Stjepan",
"lastName": "Buljat",
"email": {
"address": "stjepan.buljat@cognism.com",
"quality": "HIGH_PLUS"
},
"linkedinURL": "https://www.linkedin.com/in/sbuljat",
"jobTitle": "CTO and Co-Founder",
"managementLevel": "Executive-Level",
"seniority": "Owner",
"jobFunctions": [
"TECHNOLOGY",
"OVERSIGHT"
],
"positionStartDate": "March 2016",
"skills": [
"UML",
"Inventory Management",
"JDBC",
"JBoss Application Server",
"VisualAge",
"pureQuery",
"Db4o",
"Framework Design",
"Smalltalk",
"Mac OS X",
"Glassfish",
"Tomcat",
"JSF",
"Web Development",
"Java",
"JMX",
"J2EE",
"JMS",
"Loss Prevention",
"Groovy",
"SQL",
"Blackberry",
"Git",
"Apache",
"Django",
"Scala",
"Servlets",
"Back-End Web Development",
"JPA",
"Amazon Web Services",
"PostgreSQL",
"WebSphere Application Server",
"DB2",
"Java Enterprise Edition",
"Visual Merchandising",
"MySQL",
"iPhone",
"spray-io",
"Swing",
"Front-end Development",
"EJB",
"Play! Framework",
"MQ",
"REST",
"Ant",
"WebSphere MQ",
"Akka",
"Message Queue",
"Jasper Reports",
"Websphere",
"Problem Solving",
"Cloud Computing",
"Eclipse",
"JUnit",
"Transaction Processing",
"Maven"
],
"yearOfBirth": 1978,
"country": "Croatia",
"city": "Zadar",
"education": [
{
"field": "Information Systems Engineering",
"school": "Imperial College London",
"start": "1997",
"degree": "MEng",
"end": "2001"
},
{
"field": "Computer Science",
"school": "FESB - Faculty of Electrical Engineering, Mechanical Engineering and Naval Architecture",
"start": "2004",
"degree": "Bachelor's degree",
"end": "2008"
},
{
"field": "Economics",
"school": "Faculty of Economics & Business - Business Management (MBA)",
"start": "2007",
"degree": "univ.spec.oec.",
"end": "2012"
},
{
"field": "Computer Systems Networking and Telecommunications",
"school": "Cisco Certified Network Associate program",
"start": "2005",
"end": "2005"
},
{
"field": "Project Management",
"school": "Certified ScrumMaster Training",
"start": "2013",
"degree": "Certified ScrumMaster",
"end": "2013"
},
{
"field": "Certificate in Quantitative Finance",
"school": "Certificate in Quantitative Finance (CQF)",
"start": "2007",
"degree": "Pass",
"end": "2008"
},
{
"field": "Computer Science",
"school": "FESB - Faculty of Electrical Engineering, Mechanical Engineering and Naval Architecture",
"start": "2008",
"degree": "Master's degree",
"end": "2010"
},
{
"field": "STA Diploma",
"school": "Society of Technical Analysts (STA)",
"start": "2009",
"degree": "Pass",
"end": "2009"
},
{
"field": "Computing",
"school": "Faculty of Electrical Engineering and Computing, Zagreb",
"start": "2000",
"degree": "Master of Science in Computing (mag.ing.comp)",
"end": "2005"
}
],
"mobilePhoneNumbers": [
{
"number": "+123456789",
"score": 65,
"dnc": false,
"label": "DIRECT_DIAL"
}
],
"account": {
"id": "efc6d975-8599-38ab-8cfe-e1c42ac16dc6",
"name": "Cognism",
"domain": "cognism.com",
"industries": [
"Computer Software"
],
"description": "Cognism is the smart all-in-one marketing and sales acceleration solution. We provide organizations a GDPR compliant way to prospect leads and enrich data. ",
"shortDescription": "Cognism is a B2B sales acceleration software company that provides a marketing and sales acceleration solution.",
"founded": 2015,
"website": "cognism.com",
"crunchbaseURL": "https://www.crunchbase.com/organization/cognism",
"linkedinURL": "https://www.linkedin.com/company/cognism/",
"revenue": 17000000,
"naics": [
"5182",
"51"
],
"sic": [
"737",
"73"
],
"sizeFrom": 201,
"sizeTo": 500,
"tech": [
"Replicated",
"Salesforce",
"Salesloft",
"Lifecycle",
"Docker",
"GDPR",
"Summit",
"Matplotlib",
"AccuRate",
"MongoDB",
"Cadence",
"Digital Marketing",
"Artificial Intelligence",
"Intercom",
"Java EE",
"Yield",
"Node",
"Retargeting",
"Github",
"Cognism",
"Boost",
"Ai",
"Onboard",
"LiNK",
"IBM",
"Sandbox",
"PostgreSQL",
"Office 365 Mail",
"Deep Learning",
"Websphere",
"Gensim",
"Achievers",
"Hubspot",
"Node.js"
],
"type": "Public Company",
"officePhoneNumbers": [
{
"number": "+16469719264",
"score": 20,
"dnc": false,
"label": "COMPANY_SWITCHBOARD"
}
],
"hqPhoneNumbers": [
{
"number": "+442038580822",
"score": 20,
"dnc": false,
"label": "COMPANY_SWITCHBOARD"
}
],
"locations": [
{
"type": "hq",
"country": "United Kingdom",
"state": "England",
"city": "London",
"street": "92 Albert Embankment"
},
{
"type": "office",
"country": "United States",
"state": "New York",
"city": "New York",
"zip": "10010",
"street": "43 W 23rd St, New York, NY 10010, USA"
}
],
"companyHiring": [
{
"employer": "Cognism",
"jobTitle": "Product-Led Growth Marketing Manager",
"department": "Marketing",
"jobDate": "2021-09-14",
"country": "United Kingdom",
"url": "https://independentjobs.independent.co.uk/job/27635997/product-led-growth-marketing-manager/",
"internship": false,
"workFromHome": false
}
]
},
"previousAccounts": [
{
"name": "ETNA d.o.o.",
"jobTitle": "Product Development Manager",
"role": "Manager",
"start": "September 2013",
"end": "March 2016",
"location": {
"country": "Croatia",
"city": "Zadar"
}
}
]
}
]
}How credits are charged and what data you can access
- You are charged credits when you call the Redeem API for contacts.
- 1 credit is charged per contact redeemed.
- You are not charged twice for redeeming the same contact. You can re-enrich the same contact again without an additional charge.
- You are not charged credits when redeeming companies.
- You are not charged for using the Search and Enrich APIs, but you must have credits in your package.
- The maximum number of API previews is based on your credits (credits × 10). For example, 100 credits = 1,000 previews.
Expected results
- Enrich returns a shortlist of matches with field availability flags and a matchScore.
- Redeem returns the full contact or company profile for the redeemIds you request, limited by your Entitlements.
Comments
Article is closed for comments.