Beam background
API Documentation

Supercharge your product or your sales machine with our enrichment API for companies and employees

Companies
Employees
Industries
Job titles
Locations
Lists

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.

Need help?

Send us a message in the chatbox. A developer will reply to you as soon as possible to answer your questions.

Not a developer?

We can help you integrate our API. Send us a message in the chatbox.

Base URL
https://api.thecompaniesapi.com

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).

Your API tokens
To help you test all our endpoints in a click, your API token is included in all the endpoints below when you copy them.
Your API tokens
Create API token
magic
You don't have any api tokens yet
Create an api token to start using the api.

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

error. code string
For some errors that could be handled programmatically, a number indicating the error code reported. 403
error. message string
A message providing more details about the error. Missing api token
error. type enum
The type of error returned (see the list on your right). apiConnectionError
Possible values apiConnectionError apiError authenticationError invalidRequestError noCreditsRemaining rateLimitError
HTTP status code summary
200 - OK The request was successful.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API token provided.
402 - Request Failed The parameters were valid, but the request failed.
403 - Forbidden The API token doesn't have permission to perform the request.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on our end. These rare errors should be reported, but we catch them with Sentry and fix them as soon as they occur.
HTTP errors types summary
apiConnectionError Failure to connect to The Companies API.
apiError API errors cover any other type of problem (e.g., a temporary problem with The Companies API's servers) and are extremely uncommon.
authenticationError Failure to properly authenticate yourself in the request.
invalidRequestError Invalid request errors arise when your request has invalid parameters.
noCreditsRemaining You have no remaining credits to make this request.
rateLimitError Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

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 or when we have found a new employee for one of your dynamic lists.

Your Webhooks
Create a new webhook
magic
You don't have any webhook yet
Create a webhook to receive a notification for the events you would like to track.

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.

Available endpoints
GET https://api.thecompaniesapi.com/v1/companies
GET https://api.thecompaniesapi.com/v1/companies/by-name
GET https://api.thecompaniesapi.com/v1/companies/by-social
GET https://api.thecompaniesapi.com/v1/companies/similar
GET https://api.thecompaniesapi.com/v1/companies/:domain
GET https://api.thecompaniesapi.com/v1/companies/:domain/email-patterns

Search companies by name
1 credit

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

name Required
The company name. …/companies/by-name?name=amazon
countries Optional
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 ad ae af ag ai al am ao aq ar as at au aw ax az ba bb bd be Show more
exactWordsMatch Optional
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
size Optional
The number of companies to be returned (between 1 and 25). Default to 1. …/companies/by-name?name=amazon&size=2

Response

companies array
The companies that match with the name.
Show attributes
meta array
The metas information.
Show attributes
endpoint
GET https://api.thecompaniesapi.com/v1/companies/by-name
Response
Loading response...

Enrich a company from a domain
1 credit

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

domain Required
The company domain. …/companies/gucci.com

Response

company. alexaRank number
The company's Alexa rank. 8
company. analyzedAt string
The last time the company has been analyzed. 2021-12-22T15:49:15.000Z
company. businessType string
The company's business type. public-company
Possible values educational-institution government-agency nonprofit partnership privately-held public-company self-employed sole-proprietorship
company. city object
The company's city.
Show attributes
company. codeNaics string
The company's NAICS code. 518210
company. codeSic string
The company's SIC code. 5961
company. companiesAcquisitions array
The acquired companies.
Show attributes
company. companiesSubsidiaries array
The subsidiary companies.
Show attributes
company. companiesSimilar array
The similar companies.
Show attributes
company. companyParent object
The parent company.
Show attributes
company. continent object
The company's continent.
Show attributes
company. country object
The company's country.
Show attributes
company. county object
The company's county.
Show attributes
company. description string
The company's description. Amazon.com, Inc. is an American multinational technology company based in Seattle, Washington, which focuses on…
company. descriptionShort string
The company's short description in one line. Amazon.com, Inc. is an American multinational technology company based in Seattle.
company. domain string
The company's domain. amazon.com
company. domainAlts string
The company's alternative domains (redirection).
company. domainName string
The company's domain name. amazon
company. domainTld string
The company's top level domain. com
company. emailPatterns array
The company's email patterns for employees.
Show attributes
company. id number
The company id. 5130216
company. industries array
The company's industries. Internet, Fashion, Marketing…
company. industryMain string
The company's main industry (usually from LinkedIn). Internet
company. logo string
The company's logo url. https://poweredwith.nyc3.cdn.digitaloceanspaces.com/images/domains/amazon.com.jpg
company. monthlyVisitors enum
The company's total monthly visitors. over-1b
Possible values under-10k 10k-50k 50k-100k 100k-500k 500k-1m 1m-10m 10m-50m 50m-100m 100m-500m 500m-1b over-1b
company. name string
The company's name. Amazon
company. phoneNumber string
The company's phone number. 00 1 206-922-0880
company. revenue enum
The company's revenue. over-1b
Possible values under-1m 1m-10m 10m-50m 50m-100m 100m-200m 200m-1b over-1b
company. socialNetworks object
The company's social networks.
Show attributes
company. state object
The company's state.
Show attributes
company. stockExchange string
The company's stock exchange. NYSE
company. stockSymbol string
The company's stock symbol. AMZN
company. technologies array
The technologies used by the company.
company. technologyCategories array
The technologies' categories used by the company.
company. totalEmployees enum
The company's total number of employees. over-10k
Possible values 1-10 10-50 50-200 200-500 500-1k 1k-5k 5k-10k over-10k
company. totalEmployeesExact number
The company's exact number of employees. 3930
company. yearFounded number
The company's year of foundation. 1994
endpoint
GET https://api.thecompaniesapi.com/v1/companies/gucci.com
Response
Loading response...

Find similar companies
0.25 credit

Send us one or more domains and we will return a list of similar companies.

Query

domains Required
A list of domains separated by commas. …/companies/similar?domains[]=gucci.com&domains[]=wix.com
page Optional
The page to fetch (default to 1). …/companies/similar?domains[]=…&page=1
size Optional
The number of similar companies to be returned (between 1 and 100). Default to 10. …/companies/similar?domains[]=…&size=50

Response

companies array
The similar companies for your list of domains.
Show attributes
meta array
The metas information.
Show attributes
endpoint
GET https://api.thecompaniesapi.com/v1/companies/similar?domains[]=gucci.com&page=1&size=10
Response
Loading response...

Find email patterns for a domain
1 credit

Send us a domain name and retrieve all the email patterns they use with the usage percentage.

Query

domain Required
The company domain. …/companies/gucci.com/email-patterns

Response

patterns array
The email patterns used.
Show attributes
endpoint
GET https://api.thecompaniesapi.com/v1/companies/gucci.com/email-patterns
Response
Loading response...

Employees

We design algorithms to identify employees in real-time or enrich them when you need their email address or profile information. You will find all our features below.

Available endpoints
GET https://api.thecompaniesapi.com/v1/employees
GET https://api.thecompaniesapi.com/v1/employees/emails/discover
GET https://api.thecompaniesapi.com/v1/employees/emails/enrich

Identify employees in real-time
10 credits

Search for employees with certain job titles inside a company. The company domain name is required, but job titles aren't. You can also use conditions the employees must match for more complicated queries (see query parameter).

You can also send the id of one of your lists to save the employees. If you don't have any list, you can create one with our endpoint to create a list.

Query

countries Optional
The country codes (comma-separated) to search for. If not defined, we will search for all countries. …/employees?countries=us,fr,de
Only countries with more than one million inhabitants are available.
Possible values ae af al am ao ar at au az ba bd be bf bg bh bi bj bo br bw Show more
domain Required
The company domain to search for employees (can also be a URL as we will extract the domain). …/employees?domain=gucci.com
findEmails Optional
If set to true, we will try to find the business email of the employees. This will make the response time slower. …/employees?findEmails=true
We advise people to avoid using this parameter as it can make the response time very slow. Instead, use our endpoint to discover emails when you receive the employees (free of charge).
Possible values true false
hideCompany Optional
If set to true, we will not attach the company information to the employees. This will make the response lighter. (default: false) …/employees?hideCompany=true
Possible values true false
jobTitles Optional
The job titles (comma-separated) to search for. If not defined, we will search for all job titles. …/employees?jobTitles=ceo,cto,software%20developer
listId Optional
The id of the list to save the employees to. …/employees?listId=102
page Optional
The page to fetch (default: 1). …/employees?page=1
You must request the first page before fetching the next ones. As employees are found in real-time, we cannot know how many pages there are.
query Optional
A more complex list of conditions the employees must match (if you want something more precise than the jobTitles and countries parameters).
Make sure this parameter is stringified and encoded (i.e. encodeURIComponent).
job titles
=
Browse
Add a new condition
GET https://api.thecompaniesapi.com/v1/employees?query=%5B%7B%22attribute%22%3A%22jobTitles%22%2C%22operator%22%3A%22or%22%2C%22sign%22%3A%22equals%22%2C%22values%22%3A%5B%22marketing%22%5D%7D%5D&domain=gucci.com
size Optional
The number of employees to be returned (default to 100, max is 100). …/employees?size=10

Response

countries array
The country codes (comma-separated) to search for. If not defined, we will search for all countries.
employees array
The employees that match your conditions.
Show attributes
list object
The list the employees were saved to.
Show attributes
meta array
The metas information.
Show attributes
jobTitles array
The job titles (comma-separated) to search for. If not defined, we will search for all job titles.
query array
A more complex list of conditions the employees must match (if you want something more precise than the jobTitles and countries parameters).
Show attributes
endpoint
GET https://api.thecompaniesapi.com/v1/employees
Response
Loading response...

Discover an employee's email
5 credits

Use our algorithms to find and verify an employee's email address. Send us the employee's first name, last name, middle name, and/or employee id, and we will do the rest.

Query

domain Optional
The company's domain …/emails/discover?domain=gucci.com
employeeId Optional
The employee's id …/emails/discover?employeId=123
Credits are not deducted with this parameter.
firstName Optional
The employee's first name …/emails/discover?firstName=Jay
fullName Optional
The employee's full name …/emails/discover?fullName=Jay%20Gatsby
warningForFullName
lastName Optional
The employee's last name …/emails/discover?lastName=Gatsby
middleName Optional
The employee's middle name …/emails/discover?middle=James

Response

email string
The email discovered. [email protected]
emailDisposable boolean
Whether the email is disposable or not. false
emailDomain string
The domain of the email. gucci.com
emailFree boolean
Whether the email is free or not. false
emailPattern string
The pattern of the email. [F].[L]
emailStatus string
The status of the email. valid
Possible values catch-all error guessed identified verified verified-already
emailUsername string
The username of the email. jay.gatsby
endpoint
GET https://api.thecompaniesapi.com/v1/employees/emails/discover
Response
Loading response...

Enrich an employee from his email
1 credit

Send us a professional email, and we will enrich it with the company profile as well as data points about the employee (see list below).

Query

email Required
The email to enrich. …/employees/emails/[email protected]

Response

company object
The company profile for the email.
Show attributes
email string
The email to enrich. [email protected]
emailDisposable boolean
Whether the email is disposable or not. false
emailFree boolean
Whether the email is free or not. false
endpoint
GET https://api.thecompaniesapi.com/v1/employees/emails/enrich
Response
Loading response...

Industries

Search for specific industries and get information as the number of companies it contains.

Available endpoints
GET https://api.thecompaniesapi.com/v1/industries

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 find specific employees with our algorithms.

Available endpoints
GET https://api.thecompaniesapi.com/v1/job-titles/enrich

Enrich a job title from its name
Free

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

name Required
The job title's name. …/job-titles/enrich?name=chief%20marketing%20officer

Response

jobTitle. department string
The job title's department. marketing
Possible values customer service design education engineering finance health human resources legal marketing media operations public relations real estate sales trades
jobTitle. departmentSecondary string
The job title's secondary department. content marketing
Possible values accounting accounts brand marketing broadcasting business development compensation content marketing customer success data dental devops doctor editorial education administration electrical employee development events fitness graphic design information technology Show more
jobTitle. name string
The job title's english name.
jobTitle. nameEs string
The job title's spanish name.
jobTitle. nameFr string
The job title's french name.
jobTitle. seniorityLevel string
The job title's seniority level.
Possible values owner partner cxo vp director manager senior entry training unpaid
endpoint
GET https://api.thecompaniesapi.com/v1/job-titles/enrich
Response
Loading response...

Locations

The following endpoints let you search all our locations: cities, counties, states, countries, and continents.

Available endpoints
GET https://api.thecompaniesapi.com/v1/locations/cities
GET https://api.thecompaniesapi.com/v1/locations/counties
GET https://api.thecompaniesapi.com/v1/locations/states
GET https://api.thecompaniesapi.com/v1/locations/countries
GET https://api.thecompaniesapi.com/v1/locations/continents

Search cities
Free

Search our cities to filter companies or target employees in a specific location.

Query

page Optional
The page to fetch (default to 1). …/locations/cities?page=1
search Optional
An additionnal search query applied to the city name. …/locations/cities?search=new%20york
size Optional
The number of cities to be returned (between 1 and 20). Default to 10. …/locations/cities?size=20

Response

cities array
The cities that match your conditions.
Show attributes
meta array
The metas information.
Show attributes
endpoint
GET https://api.thecompaniesapi.com/v1/locations/cities
Response
Loading response...

Search counties
Free

Search our counties to filter companies or target employees in a specific location.

Query

page Optional
The page to fetch (default to 1). …/locations/counties?page=1
search Optional
An additionnal search query applied to the county name. …/locations/counties?search=newport
size Optional
The number of counties to be returned (between 1 and 20). Default to 10. …/locations/counties?size=20

Response

counties array
The counties that match your conditions.
Show attributes
meta array
The metas information.
Show attributes
endpoint
GET https://api.thecompaniesapi.com/v1/locations/counties
Response
Loading response...

Search states
Free

Search our states to filter companies or target employees in a specific location.

Query

page Optional
The page to fetch (default to 1). …/locations/states?page=1
search Optional
An additionnal search query applied to the state name. …/locations/states?search=new%20york
size Optional
The number of states to be returned (between 1 and 20). Default to 10. …/locations/states?size=20

Response

states array
The states that match your conditions.
Show attributes
meta array
The metas information.
Show attributes
endpoint
GET https://api.thecompaniesapi.com/v1/locations/states
Response
Loading response...

Search countries