Supercharge your product or your sales machine by taking advantage of our API
API Reference
The Companies API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
You can view code examples in the area to the right, and you can switch the programming language of the examples with the tabs in the top right. We provide examples in Curl, Ruby, PHP, Java - and for Events, JavaScript.
Authentication
The Companies API uses API token to authenticate requests. You can manage your API tokens in your settings.
Your API tokens carry many privileges , so be sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. Those authentication keys are permanent (they never expire). You can consider them safe for long-term purposes.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
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:
?token=MY-API-TOKEN (mostly used for quick testing).
Errors & Rate-Limiting
The Companies API uses conventional HTTP response codes to indicate the success or failure
of an API request. In general: 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, a charge failed, etc.). Codes in the
5xx range indicate an error with The Companies API's servers (these are rare).
Some 4xx errors that could be handled programmatically (e.g., a parameter is
missing) include an error code that briefly explains the error reported.
Also, we consider the credit system to be a rate-limit system by design. Some free API endpoints like job titles, industries, and others we might provide in the future have a rate limit security. Contact us with your use case if you plan to use them in a high volume.
Webhooks
The Companies API uses webhooks to notify you about changes. You can manage your webhooks in your settings.
Webhooks are helpful for receiving the results of our algorithms when they processed your requests for employees. They can also be used to get a notification when a new company or employee is added or removed from your lists.
We are always looking for new ways to use webhooks. If you have an idea, please let us know.
Companies
If you need additional endpoints, feel free to reach us in the chatbox. We are usually fast to implement them.
Search companies
0.25 credit
Per result
Search companies in specific industries, using a particular technology, based in a given location… Combine our conditions and create powerful search queries.
To help you create your conditions, we have designed the generator below. Another way would be to check what the URL parameters looks like in the company directory .
Query parameters
Response
Returns a paginated response including the companies that match with your search. When no
results can be found, the data property will be empty.
Search companies by name
1 credit
Retrieve the company profile information by providing its name. We will return more than 50 data points including the industries, the revenue, the technologies…
Query parameters
Response
Returns an array containing the companies that match with the name. When no companies match, an empty array will be returned. Make sure to handle this case in your code. Also, use something like encodeURI() to encode the name property properly.
Enrich a company with a domain
1 credit
Retrieve the company profile information by providing a domain name. We will return more than 50 data points including the industries, the revenue, the technologies…
Query parameters
Response
Returns a company with all the information for the provided domain name. When no company matches, an empty object will be returned. Make sure to handle this case in your code.
Find similar companies
5 credits
Find similar companies for a list of domains.
Query parameters
Response
Returns a paginated response including the similar companies for your list of domains. When
no results can be found, the data property will be empty.
Find email patterns for a domain
1 credit
Retrieve all email patterns used by a given company. We use this endpoint internally to prioritize the patterns when we want to find a business email address.
Query parameters
Response
Returns an array including all the email patterns and their usage percentage for the provided domain name. When no company matches, an empty array will be returned. Make sure to handle this case in your code.
Employees
Our algorithms can search for the employees of any company from their job title, location, or seniority level.
If you need additional endpoints, feel free to reach us in the chatbox. We are usually fast to implement them.
Search employees
10 credits
A database of employees can be outdated very quickly. This is why we do not have any. Instead, we use machine learning to analyze public sources and ensure each employee is still working inside the company. From our experience, it is the most reliable way to proceed.
Once formatted, the results are sent back to you with their business email and saved to one of your lists if specified.
Query parameters
Response
Returns all the employees we could identify to match your search. When no results can be
found, the data property will be empty.
Emails
Our algorithms can enrich your business emails with the company profile.
If you need additional endpoints, feel free to reach us in the chatbox. We are usually fast to implement them.
Enrich a business email
1 credit
Send us a business email (e.g. [email protected]) and retrieve the full profile of the company.
Query parameters
Response
Returns an object that contains the company profile (when available) as well as other information about the specified business email.
Industries
Search specific industries with our search engine and get information for each one such as the number of companies it contains.
We currently have more than 3 million industries in our database.
Search industries Free
Search our industries database with our search engine and get information for each one such
as the number of companies it contains. Results are sorted by
domains_count.
Query parameters
Response
Returns a paginated response including the industries that match with your search. When no
results can be found, the data property will be empty.
Job Titles
Search or enrich job titles with the departments and the seniority levels. It can be used to provide more context to your customers inside your CRM or to find specific employees with our algorithms.
If you need additional endpoints or data points, feel free to reach us in the chatbox. We are usually fast to implement them.
Enrich a job title with a name
1 credit
Send us a job title (e.g. chief executive officer) and retrieve additionnal information like the departments and the seniority levels. The name can be in any language we support: English, French or Spanish.
Our database includes more than 165,000 job titles categorized in 70 departments and 10 seniority levels.
Query parameters
Response
Returns a job title with all the information like departments and the seniority levels. When no job title matches, a 404 response will be returned. Make sure to handle this case in your code.
Lists
Your lists are the main way to manage your companies and employees. The API lets you retrieve the lists you have created as well as the companies and the employees you have added to them.
Fetch lists Free
This endpoint lets you retrieve all the lists that belong to your team.
Query parameters
Response
Returns a paginated response including the cities that match with your search. When no results can be found, the data property will be empty.
Fetch companies from a list Free
This endpoint allows you to retrieve the companies you have added to a list.
Query parameters
Response
Returns a paginated response of the companies you have added to the list.