Using Enrich and Redeem APIs

Use Enrich API to update your existing database. The Enrich API finds the best match based on the provided data points. The API needs to be set up before it can be used.

Enrich results will return a preview of all records that match the criteria entered and the Redeem API can be used to get all the data. The API needs to be setup before it can be used.

Learn more about setting up the Cognism API and about Entitlements

Jump to a section

Using Enrich API

  • When calling our Enrich API, Cognism will respond with a preview of the data as per the subscriber Entitlement.
  • Each field will be returned with either a true or false value, letting you know if Cognism has data for the Contact/Company.

For better Account match accuracy:

  • Use unique identifier fields such as website, domain or linkedinUrl
  • Provide as many fields as you can to ensure a greater match.

For better Contact match accuracy:

  • Use unique identifier fields such as email or linkedinUrl.
  • A combination of firstName, lastName and jobTitle with accountName or another account unique identifier such as accountWebsite.
  • Provide as many fields as you can to ensure a greater match.

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
}
}
]
}

MatchScore explained

A MatchScore is generated and is based on the number datapoints that were matched and returned for a contact or account profile.

  • The default minimum MatchScore is 30 
  • Data will not be returned if the score is less than 30.
  • Any score below 27 is regarded as a low-quality match. 
  • You can change the minimum MatchScore (minMatchScore) if needed.

Access records using Redeem API

After you have received a response from the Enrich API, and are happy with the previewed data, you will want access to the full profile. This is when you would call on the Redeem API.

In the Enrich response, you will see a field called “redeemid”. This will be used as the call and the Redeem API response will be the full profile of the record you have requested.

Info

1 to 20 IDs can be requested at a time with a limit of 1000 records per minute for Redeem API.

Below is an example call where you would use the redeemid returned from the search response for Redeem API:

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"
]
}'

Note

When calling our Redeem APIs, Cognism will return all data for the fields included within your subscribed Entitlement.

Below is an example response from the Redeem API with all the available requested and according to your Entitlements (this is 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 are credits charged and what data can I access?

  • If you do not already have credits within your Cognism package, these must be purchased for an additional cost. 
  • Credits will be charged when you ping our Redeem APIs. 
  • One credit is charged per contact.
  • You will not be charged twice for the same redeem API, meaning you can continuously enrich the same contact for no extra cost.
  • We do not charge credits when redeeming companies.
  • You will not be charged for using our Search and Enrich APIs; however, you must have credits within your package. 
  • We limit how many API calls you can make (credits x 10). Example: 100 credits = 1000 previews.
Was this article helpful?
0 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.