### Cognism API Entitlements Source: https://developers.cognism.com/index Explains the concept of entitlements in the Cognism API, which define the available Contact and Account data based on API key setup. ```APIDOC Entitlements: Entitlements are a defined set of Contact and Account data that is available for you. They are set by Cognism Support Team. Entitlement definition affects Search, Preview and Result. Entitlements are related to the API Key. Cognism API cannot be used unless Entitlements are properly set up. Basic Info: No matter what entitlement you choose, basic info will always be present. This is minimum data defining Contact or Account entity. Entitlements are built on top of basic info. ``` -------------------------------- ### Compliance API: Get Opt-Out List Source: https://developers.cognism.com/index Retrieves a list of contacts who have opted out of communications. Supports pagination using `pageKey` and requires an Authorization header. ```APIDOC GET /api/search/contact/optOut?pageSize=100 AUTHORIZATION: Bearer Token Token: HEADERS: Authorization: Bearer PARAMS: pageSize: 100 pageKey: Include pageKey in the parameters to request next page. PageKey is used for pagination and is returned with every response Example Request: curl --location 'https://app.cognism.com/api/search/contact/optOut?pageSize=100' \ --header 'Authorization: Bearer ' Example Response: No response body No response headers ``` -------------------------------- ### Cognism API: Get Search Opt-Out by Id Source: https://developers.cognism.com/index Retrieves the opt-out status for a specific contact using their unique identifier. Requires Bearer token authorization. The endpoint returns no response body or headers upon successful execution. ```APIDOC Endpoint: GET /api/search/contact/optOut/id/{id} Description: Retrieves the opt-out status for a contact by their ID. Authorization: - Type: Bearer Token - Header: Authorization: Bearer Parameters: - Path Parameter: - id (string): The unique identifier of the contact. Example Request: curl --location 'https://app.cognism.com/api/search/contact/optOut/id/MzRkNjMzYjctNDFlYS0zYWM3LWEyODAtNDMxZDcxZmQ3N2ViO2IxMjBjOTdhLTlhNTItM2E3Zi1iNzNiLTg3MGUzYjQ0M2MxOTtlZmM2ZDk3NS04NTk5LTM4YWItOGNmZS1lMWM0MmFjMTZkYzY=' \ --header 'Authorization: Bearer ' Example Response: - Body: No response body. - Headers: No response headers. ``` -------------------------------- ### Company Financial and Operational Schema Source: https://developers.cognism.com/index Outlines fields for company revenue, website, founding year, and last confirmation date. ```APIDOC revenue: { type: long } linkedinUrl: { type: string } website: { type: string } founded: { type: integer } lastConfirmed: { type: long } naics: { type: string } ``` -------------------------------- ### My Entitlements Links Source: https://developers.cognism.com/index Provides links to check personal entitlement configurations for contacts and accounts. ```APIDOC MyEntitlementContact: https://developers.cognism.com/#0c23e257-7198-4fd1-83f7-46632d3120a3 MyEntitlementAccount: https://developers.cognism.com/#2dc967bf-c544-4896-889a-ff4583781450 ``` -------------------------------- ### Cognism API Authentication Source: https://developers.cognism.com/index Details on how to authenticate requests to the Cognism API using API keys. Supports both Authorization header and api_key query parameter. ```APIDOC Authentication: Cognism 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. Your API key should be kept private, and should never be displayed publicly. API keys have a time-to-live [TTL] of 6 months. You can authenticate HTTP requests in one of two ways: * Using header field "Authorization: Bearer {API KEY}" * Using query string "api_key={API KEY}" Keep 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. ``` -------------------------------- ### IPO Event Schema Source: https://developers.cognism.com/index Details the structure for IPO (Initial Public Offering) events, including stock exchange information and raised capital. ```APIDOC ipoEvent: type: array items: type: object properties: wentPublicOn: { type: long } stockExchangeSymbol: { type: string } stockSymbol: { type: string } openingValuationUsd: { type: long } moneyRaisedUsd: { type: long } investors: { type: array, items: { type: object, properties: { name: { type: string } } } } type: { type: string } ``` -------------------------------- ### Cognism API Structure and Endpoints Source: https://developers.cognism.com/index Describes the overall structure of the Cognism API, built using RESTful endpoints and standard HTTP verbs for accessing Contact and Account data. ```APIDOC API structure: API contains a set of HTTPS endpoints providing all necessary details to preview and redeem contacts of your choice. The API is built using RESTful endpoints and standard HTTP verbs. ``` -------------------------------- ### Cognism API Rate Limiting Source: https://developers.cognism.com/index Details on the rate limiting policies for the Cognism API. It specifies the maximum requests per minute and how previews are calculated based on available credits. ```APIDOC Rate Limiting: All 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**. Number of previews available - Number of credits available, multiplied by 10. ``` -------------------------------- ### Cognism API HTTP Headers and Response Codes Source: https://developers.cognism.com/index Information on using HTTP headers to monitor rate limit status for API requests. It specifically mentions the 'x-rate-total-limit' header. ```APIDOC HTTP Headers and Response Codes: Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized. ### **x-rate-total-limit** The rate limit ceiling for all endpoints for the 1 minute window. ``` -------------------------------- ### Cognism API Error Responses Source: https://developers.cognism.com/index Details common HTTP status codes and their corresponding error messages and troubleshooting steps for the Cognism API. Includes handling for rate limits, invalid requests, and authentication issues. ```APIDOC HTTP 429 “Too Many Requests” This 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: `{ "errors": [ { "code": 88, "message": "Rate limit exceeded" } ] }`. Error Code | Message | Troubleshooting ---|---|--- 400 | Requested page number must be within allowed values | Check page query parameter. Make sure it is a number and within allowed range 400 | Requested page size must be within allowed values | Check pageSize query parameter. Make sure it is a number and within allowed range 400 | Request body invalid JSON | Make sure request contains valid JSON 400 | Search request not supported by subscribed entitlement | Check your Entitlement definition for allowed search fields. Contact Cognism for Entitlement expansion 400 | Unrecognized fields in the request | Make sure all fields in the request are supported, check for typos 401 | Unauthorised | Make sure API KEY is valid and included in the request. Check [Authentication](https://developers.cognism.com/#authentication) for more details 402 | You've exceeded your credits limit. Please contact CSM | Not enough credits for the action 429 | Rate limit exceeded | Check [Rate limiting](https://developers.cognism.com/#rate-limiting) for more details. 500 | Internal server error | The server encountered an unexpected condition which prevented it from fulfilling the request. Please contact support if this continues. ``` -------------------------------- ### Company Technologies and Industry Schema Source: https://developers.cognism.com/index Defines the structure for listing company technologies and industries. ```APIDOC technologies: { type: array, items: { type: string } } industry: { type: array, items: { type: string } } ``` -------------------------------- ### User Profile and Job Event Data Structures Source: https://developers.cognism.com/index Defines the schema for user profile information, including contact details, company information, and job history. It also details the structure for job join events, capturing transitions between roles and companies. ```APIDOC UserEvent: type: object properties: jobJoinEvent: type: array items: type: object properties: date: type: string from: type: object properties: industry: type: string name: type: string sizeTo: type: integer sizeFrom: type: integer title: type: string to: type: object properties: industry: type: string name: type: string sizeTo: type: integer sizeFrom: type: integer title: type: string redeemId: type: string ``` -------------------------------- ### Predefined Account Entitlements Source: https://developers.cognism.com/index Lists the account fields and their availability in Standard and Advanced entitlement levels. 'Y' indicates the field is available. ```APIDOC Contact Fields | Standard | Advanced ---|--- id | Y | Y name | Y | Y domain | Y | Y industry | Y | Y description | Y | Y shortDescription | Y | Y founded | Y | Y website | Y | Y linkedinUrl | Y | Y revenue | Y | Y sic | Y | Y isic | Y | Y naics | Y | Y size | Y | Y headcount | Y | Y technology | Y | Y type | Y | Y officePhoneNumbers | | Y hqPhoneNumbers | | Y location | Y | Y hiringEvent | | Y fundingEvent | | Y acquisitonEvent | | Y ipoEvent | | Y ``` -------------------------------- ### Compliance API: Search Opt-Out by Email Source: https://developers.cognism.com/index Checks the opt-out status of a contact by their email address. Returns HTTP 200 if opted out, and 404 if not. Requires an Authorization header. ```APIDOC GET /api/search/contact/optOut/email/:email AUTHORIZATION: Bearer Token Token: HEADERS: Authorization: Bearer PATH VARIABLES: email: The email address of the contact to check. Example Request: curl --location 'https://app.cognism.com/api/search/contact/optOut/email/:email' \ --header 'Authorization: Bearer ' Example Response: No response body No response headers ``` -------------------------------- ### Acquisition Event Schema Source: https://developers.cognism.com/index Defines the structure for acquisition events, including acquirer, acquiree, and acquisition type. ```APIDOC acquisitionEvent: type: array items: type: object properties: acquiredOn: { type: string } acquisitionType: { type: string } acquirer: { type: string } acquiree: { type: string } type: { type: string } ``` -------------------------------- ### Company Profile Schema Source: https://developers.cognism.com/index Defines the structure for a company profile, including financial data, investors, and industry information. ```APIDOC CompanyProfile: properties: name: { type: string } series: { type: string } moneyRaisedUsd: { type: long } postMoneyValuationUsd: { type: long } investors: { type: array, description: "List of investor names", items: { type: string } } type: { type: string } ``` -------------------------------- ### Basic Account Info Schema Source: https://developers.cognism.com/index Defines the basic information schema for an Account entity in the Cognism API, including ID and name. ```json { "id": "String", "name": "String" } ``` -------------------------------- ### Cognism Contact Schema Source: https://developers.cognism.com/index Defines the structure for contact information, including direct phone numbers, education, and location details. ```APIDOC Contact: type: object properties: directPhoneNumbers: array items: object properties: number: string numberType: string label: string score: integer addressType: string ext: string dnc: object properties: status: boolean education: array items: object properties: start: string end: string school: string degree: string field: string description: string country: string region: string city: string state: string street: string zip: string positionStartDate: string seniority: string jobFunction: array items: string managementLevel: string lastConfirmed: long locationMoveEvent: array items: object properties: date: string from: object properties: country: string city: string state: string region: string to: object properties: country: string city: string state: string region: string jobLeaveEvent: array items: object properties: date: string from: object properties: country: string city: string state: string region: string ``` -------------------------------- ### Cognism API Rate Limiting Headers Source: https://developers.cognism.com/index Details the headers used for rate limiting in the Cognism API. These headers provide information about remaining requests, reset times, and limits for endpoints and the overall contract. ```APIDOC x-rate-total-limit-remaining: The number of requests left remaining for the 1 minute window. x-rate-limit-reset: Number of seconds before rate limits are reset. x-rate-limit-user: User name. x-rate-endpoint-limit: The rate limit ceiling for single endpoints for the 1 minute window. x-rate-endpoint-limit-remaining: The number of requests left remaining for single endpoints for the 1 minute window. x-rate-result-limit: Total number of preview profiles within API contract. Calculated as number of credits x 10. x-rate-result-limit-remaining: Total number of remaining requests within API contract. x-rate-result-limit-reset: Number of seconds before rate result limit is reset (until end of current contract). x-rate-result-limit: The 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. Redeem endpoint uses standard credits and does not decreases preview limit. ``` -------------------------------- ### Company Size Schema Source: https://developers.cognism.com/index Defines fields for company size range. ```APIDOC headcount: { type: integer } sizeTo: { type: integer } sizeFrom: { type: integer } ``` -------------------------------- ### Basic Contact Info Schema Source: https://developers.cognism.com/index Defines the basic information schema for a Contact entity in the Cognism API, including ID, name, and associated account details. ```json { "id": "String (UUID)", "fullName": "String", "firstName": "String", "lastName": "String", "jobTitle": "String", "account": { "id": "String", "name": "String" } } ``` -------------------------------- ### Company Location Schema Source: https://developers.cognism.com/index Specifies the structure for company location data, including address details. ```APIDOC location: type: array items: type: object properties: addressType: { type: string } country: { type: string } state: { type: string } city: { type: string } zip: { type: string } street: { type: string } ``` -------------------------------- ### Company Data Schema Source: https://developers.cognism.com/index Defines the schema for company data within the Cognism API. It includes fields for IPO events, acquisition events, headcount, location, technologies, industry, revenue, and more. ```APIDOC Company Data Schema: { "company": { "type": "object", "properties": { "ipoEvent": { "type": "array", "items": { "type": "object", "properties": { "wentPublicOn": {"type": "integer"}, "stockExchangeSymbol": {"type": "string"}, "stockSymbol": {"type": "string"}, "openingValuationUsd": {"type": "integer"}, "moneyRaisedUsd": {"type": "integer"}, "investors": { "type": "array", "items": { "type": "object", "properties": {"name": {"type": "string"}} } }, "type": {"type": "string"} } } }, "acquisitionEvent": { "type": "array", "items": { "type": "object", "properties": { "acquiredOn": {"type": "string"}, "acquisitionType": {"type": "string"}, "acquirer": {"type": "string"}, "acquiree": {"type": "string"}, "type": {"type": "string"} } } }, "headcount": {"type": "integer"}, "sizeTo": {"type": "integer"}, "sizeFrom": {"type": "integer"}, "location": { "type": "array", "items": [ { "type": "object", "properties": { "addressType": {"type": "string"}, "country": {"type": "string"}, "state": {"type": "string"}, "city": {"type": "string"}, "zip": {"type": "string"}, "street": {"type": "string"} } } ] }, "technologies": { "type": "array", "items": [{"type": "string"}] }, "type": {"type": "string"}, "domain": {"type": "string"}, "industry": { "type": "array", "items": [{"type": "string"}] }, "revenue": {"type": "long"}, "linkedinUrl": {"type": "string"}, "website": {"type": "string"}, "founded": {"type": "integer"}, "lastConfirmed": {"type": "long"}, "naics": { "type": "array", "items": [{"type": "string"}] }, "sic": { "type": "array", "items": [{"type": "string"}] }, "isic": { "type": "array", "items": [{"type": "string"}] }, "shortDescription": {"type": "string"}, "description": {"type": "string"} } } } ``` -------------------------------- ### Contact and Company Data Structure Source: https://developers.cognism.com/index Defines the schema for contact and company information, including personal details, employment history, skills, and contact methods. This structure is used to represent individual contacts and their associated company data. ```APIDOC ContactSchema: type: object properties: company: type: object properties: name: { type: string } website: { type: string } industry: { type: array, items: { type: string } } sic: { type: array, items: { type: string } } isic: { type: array, items: { type: string } } shortDescription: { type: string } description: { type: string } jobTitle: { type: string } lastName: { type: string } firstName: { type: string } fullName: { type: string } id: { type: string } privacyNotificationSent: { type: boolean } previousAccounts: { type: array items: { type: object properties: name: { type: string } location: { type: array items: { type: object properties: addressType: { type: string } country: { type: string } state: { type: string } city: { type: string } zip: { type: string } street: { type: string } } } title: { type: string } start: { type: string } end: { type: string } seniority: { type: string } jobFunction: { type: array, items: { type: string } } email: { type: object properties: address: { type: string } quality: { type: string } } managementLevel: { type: string } } } skills: { type: array, items: { type: string } } linkedinUrl: { type: string } email: { type: object properties: address: { type: string } quality: { type: string } sha256: { type: string } } mobilePhoneNumbers: { type: array items: { type: object properties: number: { type: string } numberType: { type: string } label: { type: string } score: { type: integer } addressType: { type: string } } ``` -------------------------------- ### Response Schema Note Source: https://developers.cognism.com/index A note regarding the response schema, indicating that the actual returned object depends on user entitlements. ```APIDOC Response schema: > Actual returned object will contain fields based on user Entitlements ``` -------------------------------- ### Predefined Contact Entitlements Source: https://developers.cognism.com/index Lists the contact fields and their availability in Standard and Advanced entitlement levels. 'Y' indicates the field is available. ```APIDOC Contact Fields | Standard | Advanced ---|--- id | Y | Y fullName | Y | Y firstName | Y | Y lastName | Y | Y jobTitle | Y | Y lastConfirmed | Y | Y managementLevel | Y | Y jobFunction | Y | Y seniority | Y | Y positionStartDate | Y | Y mobilePhoneNumbers | | Y directPhoneNumbers | | Y region | Y | Y country | Y | Y state | Y | Y city | Y | Y zip | Y | Y street | Y | Y education | Y | Y skills | Y | Y linkedinUrl | Y | Y email | Y | Y privacyNotificationSent | Y | Y locationMoveEvent | | Y jobJoinEvent | | Y jobLeaveEvent | | Y previousAccount | Y | Y account.id | Y | Y account.name | Y | Y account.domain | Y | Y account.industry | Y | Y account.description | Y | Y account.shortDescription | Y | Y account.founded | Y | Y account.website | Y | Y account.linkedinUrl | Y | Y account.revenue | Y | Y account.sic | Y | Y account.isic | Y | Y account.naics | Y | Y account.size | Y | Y account.headcount | Y | Y account.technology | Y | Y account.type | Y | Y account.officePhoneNumbers | | Y account.hqPhoneNumbers | | Y account.location | Y | Y account.hiringEvent | | Y account.fundingEvent | | Y account.acquisitonEvent | | Y account.ipoEvent | | Y ``` -------------------------------- ### Account Response Schema Source: https://developers.cognism.com/index This JSON schema defines the structure of the response object for a redeemed account. It includes the total number of results and an array of account objects, each containing details like name, ID, office and HQ phone numbers, hiring events, and funding events. ```json { "properties": { "totalResults": { "type": "integer" }, "results": { "type": "array", "items": [ { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "officePhoneNumbers": { "type": "array", "items": [ { "type": "object", "properties": { "number": { "type": "string" }, "numberType": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "addressType": { "type": "string" }, "ext": { "type": "string" }, "dnc": { "type": "object", "properties": { "status": { "type": "boolean" } } } } } ] }, "hqPhoneNumbers": { "type": "array", "items": [ { "type": "object", "properties": { "number": { "type": "string" }, "numberType": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "addressType": { "type": "string" }, "ext": { "type": "string" }, "dnc": { "type": "object", "properties": { "status": { "type": "boolean" } } } } } ] }, "hiringEvent": { "type": "array", "items": [ { "type": "object", "properties": { "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "jobTitle": { "type": "string" }, "department": { "type": "string" }, "jobType": { "type": "string" }, "internship": { "type": "boolean" }, "jobHours": { "type": "string" }, "workFromHome": { "type": "boolean" }, "employer": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string" }, "jobDate": { "type": "string" } } } ] }, "fundingEvent": { "type": "array", "items": { "type": "object", "properties": { "announcedOn": { "type": "long" }, "fundingType": { "type": "string" }, "series": { "type": "string" }, "moneyRaisedUsd": { "type": "long" }, "postMoneyValuationUsd": { "type": "long" }, "investors": { "type": "array", "description": "List of investor names", "items": { "type": "string" } }, "type": { "type": "string" } } } } } } ] } } } ``` -------------------------------- ### Redeemed Contact Response Object Source: https://developers.cognism.com/index This JSON object represents the complete structure of a redeemed contact response from the Cognism API. It includes total results and an array of contact results, each containing account details, office and HQ phone numbers, and information about hiring or funding events. ```json { "properties": { "totalResults": { "type": "integer" }, "results": { "type": "array", "items": [ { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "officePhoneNumbers": { "type": "array", "items": [ { "type": "object", "properties": { "number": { "type": "string" }, "numberType": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "addressType": { "type": "string" }, "ext": { "type": "string" }, "dnc": { "type": "object", "properties": { "status": { "type": "boolean" } } } } } ] }, "hqPhoneNumbers": { "type": "array", "items": [ { "type": "object", "properties": { "number": { "type": "string" }, "numberType": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "addressType": { "type": "string" }, "ext": { "type": "string" }, "dnc": { "type": "object", "properties": { "status": { "type": "boolean" } } } } } ] }, "hiringEvent": { "type": "array", "items": [ { "type": "object", "properties": { "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "jobTitle": { "type": "string" }, "department": { "type": "string" }, "jobType": { "type": "string" }, "internship": { "type": "boolean" }, "jobHours": { "type": "string" }, "workFromHome": { "type": "boolean" }, "employer": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string" }, "jobDate": { "type": "string" } } } ] }, "fundingEvent": { "type": "array", "items": { "type": "object", "properties": { "announcedOn": { "type": "long" }, "fundingType": { "type": "string" } } } } } } } } ] } } } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.