We have released the Search API which should be migrated to immediately. This guide explains the major differences between the Public API (soon to be discontinued) and the new Search API, and should help you with the migration process.
Major Changes
The way to query and get results has changed, some of the main details are explained in Sections 1 to 6.
Search API has been introduced. Details can be found here -->Search API, including the three renamed fields:
Public API | Search API |
|---|---|
|
|
|
|
|
|
The Response Schema has changed, new version can be found here -->https://developers.cognism.com/#response-schema.
API flow has changed; in short it’s search/enrich then redeem.
New endpoints (details following).
Endpoints
There is no direct mapping of endpoints from the Public API to the Search API. The following sections explain the differences with some examples for comparison.
Public API
https://api.cognism.com/api/prospector/people/search
https://api.cognism.com/api/prospector/company/search
https://api.cognism.com/api/prospector/people/match
https://api.cognism.com/api/prospector/company/{id}
https://api.cognism.com/api/prospector/people/{id}
Search API
https://app.cognism.com/api/search/contact/search https://app.cognism.com/api/search/contact/redeem https://app.cognism.com/api/search/account/search https://app.cognism.com/api/search/account/redeem https://app.cognism.com/api/search/contact/enrich https://app.cognism.com/api/search/account/enrich
Public API (to be discontinued soon)
1. Search people dataset
https://api.cognism.com/api/prospector/people/search
The Public API examples show the request and response code details depending whether the "show_contact_data" was set to true or false.
If "show_contact_data": true is requested, the response shows all data, and the customer IS charged for this result.
If "show_contact_data": false is requested, the response shows all data obfuscated, and the customer is NOT charged for this result.
2. Search companies dataset
https://api.cognism.com/api/prospector/company/search
The response shows all company data, and the customer is NOT charged for this result.
Public API Examples
Examples are of Search people dataset using the old Public API, as detailed in Section 1 above.
Request ("show_contact_data": true)
{
"firstName": "Stjepan",
"lastName": "Buljat",
"jobTitles": [
"CTO"
],
"options": {
"show_contact_data": true
}
}
Response ("show_contact_data": true)
{
"total": 1,
"results": [
{
"name": "Stjepan Buljat",
"first": "Stjepan",
"last": "Buljat",
"id": "34d633b7-41ea-3ac7-a280-431d71fd77eb",
"emails": [
{
"score": 91,
"sha256": "8196f25443a02b758c7fbd4b5c0ce86c71eadda92f49709eb5e2e3515d586929",
"src": {
"at": 1672830270675,
"name": "cognism"
},
"verified": true,
"handle": "stjepan.buljat@cognism.com",
"status": "VALID",
"quality": "HIGH_PLUS"
}
],
"phone_numbers": [
{
"number": "+38598521575",
"score": 99,
"src": {
"at": 1668530137203,
"name": "cognism"
},
"dnc": true,
"number_type": "MOBILE",
"label": "DIRECT_DIAL"
}
],
.
.
.
.
.
.
.
.
.
.
.
.
.
.
"com": [
{
"locations": [
{
"country": "United Kingdom",
"city": "London",
"src": {
"at": 1656661425937,
"name": "cognism"
},
"street": "92 Albert Embankment",
"phones": [],
"state": "London",
"type": "hq"
}
],
"aliases": [
"cognism"
],
"desc": "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. ",
"name": "Cognism"
.
.
.
.
.
.
.
.
.
]
}
]
}
Request ("show_contact_data": false)
{
"firstName": "Stjepan",
"lastName": "Buljat",
"jobTitles": [
"CTO"
],
"options": {
"show_contact_data": false
}
}
Response ("show_contact_data": false)
{
"total": 1,
"results": [
{
"name": "Stjepan Buljat",
"first": "Stjepan",
"last": "Buljat",
"id": "34d633b7-41ea-3ac7-a280-431d71fd77eb",
"emails": [
{
"score": 91,
"src": {
"at": 1672830270675,
"name": "cognism"
},
"verified": true,
"handle": "s*****@cognism.com",
"status": "VALID",
"quality": "HIGH_PLUS"
}
],
"phone_numbers": [
{
"number": "+385******",
"score": 99,
"src": {
"at": 1668530137203,
"name": "cognism"
},
"dnc": true,
"number_type": "MOBILE",
"label": "DIRECT_DIAL"
}
],
.
.
.
.
.
.
.
.
.
.
.
.
.
.
"com": [
{
"locations": [
{
"country": "United Kingdom",
"city": "London",
"src": {
"at": 1656661425937,
"name": "cognism"
},
"street": "92 Albert Embankment",
"phones": [],
"state": "London",
"type": "hq"
}
],
"aliases": [
"cognism"
],
"desc": "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. ",
"name": "Cognism"
.
.
.
.
.
.
.
.
.
]
}
]
}
Search API (new)
3. Search contact dataset
https://app.cognism.com/api/search/contact/search
The Search API examples show the request and response code details.
The initial section of the response shows the search criteria. All other fields show true or false depending if there is any data corresponding for that field.
redeemId details are also displayed, and are used to display all data which was flagged with true (details in Section 4).
The customer is NOT charged for this result.
4. Redeem contact dataset
https://app.cognism.com/api/search/contact/redeem
The response shows all data which was flagged with true in the previous search (Section 3).
The customer IS charged for this result.
5. Search and Redeem account dataset
https://app.cognism.com/api/search/account/search
https://app.cognism.com/api/search/account/redeem
Similar process to Contact Search and Redeem, as explained in Sections 3 and 4.
Workflow for getting data is two step process. First step is using Search or Enrich endpoint. This step will return data presence flags.
Second step, depending of response from Search/Enrich, is Redeem endpoint where full data is obtained.
The customer is NOT charged for either the Search or Redeem results *
*Charging for redeeming account data may change in the future
6. Enrich and Redeem contact dataset
https://app.cognism.com/api/search/contact/enrich
https://app.cognism.com/api/search/contact/redeem
Enrich your data, followed by Redeem to display the results. In future you can use the same redeemId to update this result.
Workflow for getting data is two step process. First step is using Search or Enrich endpoint. This step will NOT use credits and will return data presence flags.
Second step, depending on response from Search/Enrich, is Redeem endpoint where full data is obtained and credit IS charged.
Result shows fields with true or false. If you have data in the field it shows true, but if not the field shows false.
redeemId details are also displayed, and are used to display all data which was flagged with true (details in Section 4).
The customer IS charged only when calling Redeem endpoint and retrieving data result.
Search API Example
Search Request
{
"firstName": "Stjepan",
"lastName": "Buljat",
"jobTitles": [
"CTO"
],
"excludeJobTitles": [
"CEO"
],
"regions": [
"EMEA"
],
"mobilePhoneNumbers": {
"highPlus": true
},
"emailQuality": {
"highPlus": true
},
"account": {
"names": [
"Cognism"
],
"officePhoneNumbers": {
"medium": true
}
}
}
Search Response
{
"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": "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,
"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
}
}
]
}
Redeem Endpoint Request
{
"redeemIds": [
"MzRkNjMzYjctNDFlYS0zYWM3LWEyODAtNDMxZDcxZmQ3N2ViOzhkMDlhZGJhLTczMDYtMzhlMS1iODRiLWU4NmU2OWU3MGU3YjtlZmM2ZDk3NS04NTk5LTM4YWItOGNmZS1lMWM0MmFjMTZkYzY"
]
}
Redeem Endpoint Response
{
"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"
}
}
]
}
]
}
Comments
Please sign in to leave a comment.