Your enrichment API to boost your product and your marketing
Search companies, enrich a list of domains and find similar businesses.
API Documentation
The Companies API is built using the REST architecture. Our routes accept request bodies encoded in the form format and return responses encoded in the JSON format. You can jump from one feature to another with the navigation menu on your left. Examples with real responses are provided on the right side of the page.
Send us a message in the chatbox. A developer will reply to you as soon as possible to answer your questions.
We can help you integrate our API. Send us a message in the chatbox.
Authentication
The Companies API uses API token to authenticate requests. You can manage your API tokens in your settings or on the right side of this section.
There are two ways to authenticate your HTTP requests to the API:
By adding an "Authorization" header. The "Authorization" header is formatted as such: "Authorization: Basic MY-API-TOKEN" (replace "MY-API-TOKEN" with one of yours).
By sending the API token as a "GET" parameter. Like this "?token=MY-API-TOKEN" (mostly used to quickly test a endpoint).
Good to know
No API token found
Create an API token to start using our endpoints.
Errors & Rate-Limiting
The Companies API uses conventional HTTP response codes to indicate the success or failure of an API request. Generally, Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with our servers (these are rare).
Some 4xx errors that could be handled programmatically include an error code that briefly explains what went wrong.
Error object
For some errors that could be handled programmatically, a number indicating the error code reported.
403
A message providing more details about the error.
Missing API token
The type of error returned (see the list on your right).
apiConnectionError
Possible values
Webhooks
The Companies API uses webhooks to notify you about changes or when an operation ends. You can manage your webhooks on the right side of this section or in your settings.
Webhooks are helpful for receiving the results of our algorithms. For instance, when a new company you have requested has been scrapped.
No webhook found
Create a webhook to receive a notification for important events.
Companies
You will find all our features regarding our database of companies below.
Search companies with a specific condition or by name. Retrieve the profile of a particular business by providing its domain name or one of its social network URLs.
Do you also need to get similar companies or even the email patterns they use? We got you covered.
Search companies
Do you need to search companies located in a given country for a specific industry and that use a particular technology? Combine our conditions and create powerful search queries to identify them.
Query parameters
An array of conditions the companies must match.
Make sure this parameter is stringified and encoded.
A list of comma-separated domains to exclude from the results.
/companies?domainsToExclude=amazon.com,pearson.com
A list of comma-separated LinkedIn URLs to exclude from the results.
/companies?linkedinToExclude=https://www.linkedin.com/company/amazon,https://www.linkedin.com/company/pearson
The page to fetch (default to 1).
/companies?page=1
An additional search query applied to the company name or domain.
/companies?search=amazon
Define the fields to search.
/companies?searchFields[]=domain&searchFields[]=name
Possible values
Return a simplified version of the companies (no credits deducted but limitation are applied on the free plan). It is useful for previewing the data before fetching the full version. Default to false.
/companies?simplified=true
Possible values
The number of companies to be returned (between 1 and 100). Default to 10.
/companies?size=10
An array of multiple fields combined to sort the results.
…/companies?sortFields=%5B%7B%22key%22%3A%22meta.score%22%2C%22order%22%3A%22desc%22%7D%5D
Make sure this parameter is stringified and encoded.
The field to sort the results.
…/companies?sortKey=meta.score
Possible values
The order to sort the results.
…/companies?sortOrder=asc
Possible values
Response
The companies that match your conditions.
The metas information.
The conditions the companies must match.
Search companies by name
Retrieve a company profile by providing the company name. You can use this endpoint if you need more information about the company, but be careful. Two companies can have the same name—for example, Bolt. That's why this feature can return multiple companies.
Query parameters
The company name.
…/companies/by-name?name=microsoft
The page to fetch (default to 1).
/companies/by-name?page=1
The countries to filter the companies by. You can provide multiple countries separated by a comma. Default to all countries.
/companies/by-name?countries=us,fr,de
Possible values
If set to true, the company name must match the searched words. 'Bank of A' will not return Bank of America but 'Bank of' and 'Bank of America' will. Default to true.
/companies/by-name?exactWordsMatch=false
Comma-separated IDs of your lists containing companies to exclude from the results.
/companies/by-name?listsToExclude=3920,3925
Return a simplified version of the companies (no credits deducted but limitation are applied on the free plan). It is useful for previewing the data before fetching the full version. Default to false.
/companies/by-name?simplified=true
Possible values
The number of companies to be returned (between 1 and 25). Default to 1.
/companies/by-name?name=amazon&size=2
An array of multiple fields combined to sort the results.
…/companies/by-name?sortFields=%5B%7B%22key%22%3A%22meta.score%22%2C%22order%22%3A%22desc%22%7D%5D
Make sure this parameter is stringified and encoded.
The field to sort the results.
…/companies/by-name?sortKey=meta.score
Possible values
The order to sort the results.
…/companies/by-name?sortOrder=asc
Possible values
Response
The companies that match with the name.
The metas information.
Search companies using a prompt
Describe the companies you are looking for and our AI model will find them for you. You can adjust the similarity threshold to enhance the precision of your results.
Query parameters
The prompt our AI model will use to search for companies.
…/companies/by-prompt?prompt=universities in the united states
Comma-separated IDs of your lists containing companies to exclude from the results.
/companies/by-prompt?listsToExclude=3920,3925
The page to fetch (default to 1).
/companies/by-prompt?page=1
The similarity threshold to use for the search (between 0 and 1). Default to 0.75.
/companies/by-prompt?similarity=0.75
Whether to return a simplified version of the company profile. Default to false.
/companies/by-prompt?simplified=true
The number of companies to be returned (between 1 and 25). Default to 10.
/companies/by-prompt?size=10
An array of multiple fields combined to sort the results.
…/companies/by-prompt?sortFields=%5B%7B%22key%22%3A%22meta.score%22%2C%22order%22%3A%22desc%22%7D%5D
Make sure this parameter is stringified and encoded.
The field to sort the results.
…/companies/by-prompt?sortKey=meta.score
Possible values
The order to sort the results.
…/companies/by-prompt?sortOrder=asc
Possible values
Response
The list of companies matching your prompt.
The metas information.
Search for similar companies (competitors, your customers, etc.)
Send us one or more domains and we will return a list of similar companies.
Query parameters
A list of domains separated by commas.
…/companies/similar?domains[]=microsoft.com&domains[]=wix.com
The page to fetch (default to 1).
/companies/similar?domains[]=…&page=1
The number of similar companies to be returned (between 1 and 100). Default to 10.
/companies/similar?domains[]=…&size=50
An array of multiple fields combined to sort the results.
…/companies/similar?sortFields=%5B%7B%22key%22%3A%22meta.score%22%2C%22order%22%3A%22desc%22%7D%5D
Make sure this parameter is stringified and encoded.
The field to sort the results.
…/companies/similar?sortKey=meta.score
Possible values
The order to sort the results.
…/companies/similar?sortOrder=asc
Possible values
Response
The similar companies for your list of domains.
The metas information.
Enrich a company from a domain
Enrich a company by sending us its domain name. The domain name is a better identifier than the company name because it is unique and less prone to typos.
Query parameters
The company domain.
microsoft.com
Response
General information about the company.
Analytical data and website performance.
Information about the applications the company offers.
Company’s resources including digital assets.
Job openings and career opportunities at the company.
Standard industry classification codes for the company and other identification codes.
Details about related companies such as acquisitions and subsidiaries.
Contact information including emails and phones.
Content provided by the company like blogs, podcasts, and more.
Company descriptions and associated keywords converted to English with our AI.
Details regarding the company’s domain name.
Financial data and revenue information about the company.
Legal information and policies of the company.
Geographical locations and headquarters of the company.
Meta information about the company.
Details about the products offered by the company.
Additional information about the company we could not categorize.
Company’s social media links and metrics.
Technologies used by the company.
Enrich a company from an email
Enrich a company by sending us an email.
Query parameters
Whether to return a simplified version of the company payload.
/companies/[email protected]&simplified=true
Response
Enrich a company from a social network url (LinkedIn, Instagram, etc.)
Retrieve the profile of a company by sending us a social network URL (see the list below for the ones we accept).
Query parameters
The company's Dribbble URL.
/companies/by-social?dribbble=https://dribbble.com/microsoft
The company's Facebook URL.
/companies/by-social?facebook=https://www.facebook.com/microsoft
The company's GitHub URL.
/companies/by-social?github=https://github.com/microsoft
The company's Instagram URL.
/companies/by-social?instagram=https://www.instagram.com/microsoft
The company's LinkedIn URL. We handle both alpha urls (/company/microsoft) and numeric ids (/company/6585).
/companies/by-social?linkedin=https://www.linkedin.com/company/microsoft
The company's Pinterest URL.
/companies/by-social?pinterest=https://www.pinterest.com/microsoft
The company's Snapchat URL.
/companies/by-social?snapchat=https://www.snapchat.com/add/microsoft
The company's TikTok URL.
/companies/by-social?tiktok=https://www.tiktok.com/@microsoft
The company's Twitter URL.
/companies/by-social?twitter=https://twitter.com/microsoft
The company's Wellfound URL.
/companies/by-social?wellfound=https://wellfound.com/company/microsoft
The company's YouTube URL.
/companies/by-social?youtube=https://www.youtube.com/@microsoft
Response
General information about the company.
Analytical data and website performance.
Information about the applications the company offers.
Company’s resources including digital assets.
Job openings and career opportunities at the company.
Standard industry classification codes for the company and other identification codes.
Details about related companies such as acquisitions and subsidiaries.
Contact information including emails and phones.
Content provided by the company like blogs, podcasts, and more.
Company descriptions and associated keywords converted to English with our AI.
Details regarding the company’s domain name.
Financial data and revenue information about the company.
Legal information and policies of the company.
Geographical locations and headquarters of the company.
Meta information about the company.
Details about the products offered by the company.
Additional information about the company we could not categorize.
Company’s social media links and metrics.
Technologies used by the company.
Enrich a company with its email patterns
Send us a domain name and retrieve all the email patterns they use with the usage percentage.
Query parameters
The company domain.
…/companies/microsoft.com/email-patterns
Response
The email patterns used.
Count companies matching your query
Count the companies matching your conditions. Useful if you are building your own search engine for companies.
Query parameters
An array of conditions the companies must match.
Make sure this parameter is stringified and encoded.
An additional search query applied to the company name or domain.
/companies/count?search=amazon
Define the fields to search.
/companies/count?searchFields[]=domain&searchFields[]=name
Possible values
Response
The number of companies matching the conditions.
Actions
Below, you'll find a comprehensive overview of the actions you can perform with companies.
These actions are particularly powerful for automating processes within your product using our API.
They enable you to not only enrich companies that aren't yet in our database but also to perform more detailed enrichment on existing ones if needed (such as extracting products for an e-commerce website).
Request an action on one or more companies
This endpoint enables you to request an action for a single company, multiple companies, or an entire list of companies.
Body parameters
The domains that need to be processed.
["pearson.com","united.com"]
Indicates whether you are requesting a price estimate.
Possible values
The type of task to be performed.
Possible values
The ID of the list to be processed.
42
Response
The events that have been triggered by the request.
Indicates whether you are requesting a price estimate.
Fetch the events for your actions
This endpoint lets you retrieve your most recent action requests and events.
Query parameters
The page to fetch (default to 1).
1
The number of events to be returned (between 1 and 25). Default to 10.
10
The status of the events to retrieve.
Possible values
The type of the events to retrieve.
Possible values
Response
The list of events.
The metas information.
Industries
Search for specific industries and get information as the number of companies it contains.
Search industries
Search our industries database and get information such as the number of companies it contains. Results are sorted by "companies_count".
Query parameters
The page to fetch (default to 1).
/industries?page=1
An additional search query applied to the industry name.
/industries?search=saas
The number of industries to be returned (between 1 and 100). Default to 25.
/industries?size=10
Response
The industries that match your conditions.
The metas information.
Find similar industries
Discover similar industries with our API. Identify related sectors and expand your business opportunities.
Query parameters
The industries to compare with (max: 10).
/industries/similar?industries[]=saas&industries[]=fintech
The page to fetch (default to 1).
/industries/similar?page=1
The number of industries to be returned (between 1 and 100). Default to 25.
/industries/similar?size=10
Response
The industries that match your conditions.
The metas information.
Technologies
We currently track 368 technologies. If you need a technology that is not listed, feel free to chat with us as it usually takes us less than 48 hours to add it.
Search technologies
Browse the technologies that we identify and get information such as the number of companies using it.
Query parameters
The page to fetch (default to 1).
/technologies?page=1
An additional search query applied to the technology name.
/technologies?search=shopify
The number of technology to be returned (between 1 and 100). Default to 25.
/technologies?size=10
Response
The technologies we identify that match your conditions.
The metas information.
Locations
The following endpoints let you search all our locations: cities, counties, states, countries, and continents.
Search cities
Search our cities to filter companies in a specific location.
Query parameters
The page to fetch (default to 1).
An additional search query applied to the city name.
The number of cities to be returned (between 1 and 20). Default to 10.
Response
The cities that match your conditions.
The metas information.
Search counties
Search our counties to filter companies in a specific location.
Query parameters
The page to fetch (default to 1).
An additional search query applied to the county name.
The number of counties to be returned (between 1 and 20). Default to 10.
Response
The counties that match your conditions.
The metas information.
Search states
Search our states to filter companies in a specific location.
Query parameters
The page to fetch (default to 1).
An additional search query applied to the state name.
The number of states to be returned (between 1 and 20). Default to 10.
Response
The states that match your conditions.
The metas information.
Search countries
Search our countries to filter companies in a specific location.
Query parameters
The page to fetch (default to 1).
An additional search query applied to the country name.
The number of countries to be returned (between 1 and 20). Default to 10.
Response
The countries that match your conditions.
The metas information.
Search continents
Search our continents to filter companies in a specific location.
Query parameters
The page to fetch (default to 1).
An additional search query applied to the continent name.
The number of continents to be returned (between 1 and 20). Default to 10.
Response
The continents that match your conditions.
The metas information.
Job Titles
You will find all our features regarding our database of job titles below. Search or enrich job titles with the departments and the seniority levels. You can use these features to provide more context to your customers inside your CRM or to target employees with other providers.
Enrich a job title from its name
Send us a job title (e.g., chief marketing officer) and retrieve additional information like the departments and the seniority levels. We support the following languages: English, French, and Spanish.
Query parameters
The job title's name.
/job-titles/enrich?name=chief%20executive%20officer
Response
The job title's department.
marketing
Possible values
The job title's secondary department.
content marketing
Possible values
The job title's english name.
The job title's spanish name.
The job title's french name.
The job title's seniority level.
Possible values
Lists
Companies can be saved in your lists. The following endpoints let you retrieve your lists and deal with the companies that belong to them.
Fetch your lists
This endpoint allows you to retrieve the lists that belong to your team.
Query parameters
The page to fetch (default: 1).
/lists?page=1
The number of lists to be returned (between 1 and 100). Default to 10.
/lists?size=10
Response
The lists that belong to your team.
The metas information.
Create a list of companies
This endpoint allows you to create a list of companies.
Body parameters
If the list is dynamic. When set to true, the list will be updated automatically when new companies are added to the database.
Possible values
The name of the list.
The type of list to create.
Possible values
Response
The analytics of the list.
When the list was created.
2022-02-22T07:23:52.000+00:00
If the list is dynamic or static.
true
The id of the list.
3838
If the list has been imported.
true
The integrations associated with the list.
The name of the list
French NodeJS Companies
The process active status of the list (for internal use).
true
The process initialized flag (for internal use).
true
When the list is being processed.
2022-02-22T07:23:52.000+00:00
The query used to generate the list.
Fetch companies in your list
This endpoint allows you to fetch companies in your lists.
Query parameters
The page to fetch (default to 1).
/lists/:listId/companies?page=1
The number of companies to be returned (between 1 and 100). Default to 10.
/lists/:listId/companies?size=10
An array of multiple fields combined to sort the results.
…/lists/:listId/companies?sortFields=%5B%7B%22key%22%3A%22meta.score%22%2C%22order%22%3A%22desc%22%7D%5D
Make sure this parameter is stringified and encoded.
The field to sort the results.
…/lists/:listId/companies?sortKey=meta.score
Possible values
The order to sort the results.
…/lists/:listId/companies?sortOrder=asc
Possible values
Response
The companies that belong to your list.
The metas information.
Manage your team
These endpoints allow you to manage and retrieve detailed information about the team associated with your API token.
Fetch your team
This endpoint allows you to retrieve the team associated with your API token.
Response
The team's country.
us
The team's creation date.
2020-06-29 08:21:01
The team's credits.
500000
If the team is subscribed to a paid plan.
true
The team's id.
1
The team's name.
Jay Gatsby Enterprises
The team's website url.
https://www.jaygatsbyenterprises.com