Beam background
Company & Employee Enrichment API

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.

julien

Of course, if you need help with anything or want to see additional features, feel free to reach us in the chatbox. We are usually quick to implement them.

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

nada

Your API tokens carry many privileges, so keep them secure! Please do not share them in publicly accessible areas such as GitHub, client-side code, etc. Those authentication keys are permanent (they never expire). You can consider them safe for long-term purposes.

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

or

By sending the API token as a "GET" parameter. Like this "?token=MY-API-TOKEN" (mostly used to quickly test a endpoint).

power

Please note that you can only use HTTPS to access the API. HTTP is not supported.

To help you test all our endpoints in a click, your API token is included in all the endpoints below when you copy them.
Create a new 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.

anthony

We consider the credit system a rate-limit system by design. Some free API features such as the job titles, industries, and others have a rate limit security. Contact us with your use case if you plan to use them in a high volume.

Error object

error. codestring
For some errors that could be handled programmatically, a number indicating the error code reported.
403
error. messagestring
A message providing more details about the error.
Missing api token
error. typeenum
The type of error returned (see the list on your right).
apiConnectionError
Possible values
apiConnectionError
apiError
authenticationError
invalidRequestError
noCreditsRemaining
rateLimitError
200 - OKThe request was successful.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API token provided.
402 - Request FailedThe parameters were valid, but the request failed.
403 - ForbiddenThe API token doesn't have permission to perform the request.
404 - Not FoundThe requested resource doesn't exist.
409 - ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server ErrorsSomething 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.
apiConnectionErrorFailure to connect to The Companies API.
apiErrorAPI errors cover any other type of problem (e.g., a temporary problem with The Companies API's servers) and are extremely uncommon.
authenticationErrorFailure to properly authenticate yourself in the request.
invalidRequestErrorInvalid request errors arise when your request has invalid parameters.
noCreditsRemainingYou have no remaining credits to make this request.
rateLimitErrorToo 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.

julien

We are always looking for new ways to use webhooks. If you have any suggestion, please let us know.

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.

power

An important concept to keep in mind is that we represent a company by its domain name (e.g., gucci.com). This is what we use as a unique key. That means that when we discover a new domain name, we consider it a new company.

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.

julien

If you have a company's domain name, it's better to use it. We use it as a unique key in our database. See our endpoint below.

Query parameters

namerequired
The company name.
…/companies/by-name?name=amazon
countriesoptional
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
& 230 others
exactWordsMatchoptional
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
sizeoptional
The number of companies to be returned (between 1 and 25). Default to 1.
…/companies/by-name?name=amazon&size=2
sortFieldoptional
The field to sort the results. Default to score.
…/companies/by-name?sortField=revenue
Possible values
monthlyVisitors
revenue
score
totalEmployees
yearFounded
sortOrderoptional
The order to sort the results. Default to desc.
…/companies/by-name?sortOrder=asc
Possible values
asc
desc

Response

companiesarray
The companies that match with the name.
metaobject
The metas information.
GET
https://api.thecompaniesapi.com/v1/companies/by-name
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.

power

We return more than 50 data points including the industries, the revenue, the technologies… If you need something we do not have yet, please let us know.

Query parameters

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

Response

company. alexaRanknumber
The company's Alexa rank.
8
company. businessTypestring
The company's business type.
public-company
Possible values
educational-institution
government-agency
nonprofit
partnership
privately-held
public-company
self-employed
sole-proprietorship
company. cityobject
The company's city.
company. codeNaicsstring
The company's NAICS code.
518210
company. codeSicstring
The company's SIC code.
5961
company. companiesAcquisitionsarray
The acquired companies.
company. companiesSubsidiariesarray
The subsidiary companies.
company. companiesSimilararray
The similar companies.
company. companyParentobject
The parent company.
company. continentobject
The company's continent.
company. countryobject
The company's country.
company. countyobject
The company's county.
company. descriptionstring
The company's description.
Amazon.com, Inc. is an American multinational technology company based in Seattle, Washington, which focuses on…
company. descriptionShortstring
The company's short description in one line.
Amazon.com, Inc. is an American multinational technology company based in Seattle.
company. domainstring
The company's domain.
amazon.com
company. domainAltsstring
The company's alternative domains (redirection).
company. domainNamestring
The company's domain name.
amazon
company. domainTldstring
The company's top level domain.
com
company. emailPatternsarray
The company's email patterns for employees.
company. idnumber
The company id.
5130216
company. industriesarray
The company's industries.
Internet, Fashion, Marketing…
company. industryMainstring
The company's main industry (usually from LinkedIn).
Internet
company. logostring
The company's logo url.
https://thecompaniesapi.s3.fr-par.scw.cloud/images/domains/amazon.com.jpg
company. monthlyVisitorsenum
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. namestring
The company's name.
Amazon
company. phoneNumberstring
The company's phone number.
00 1 206-922-0880
company. revenueenum
The company's revenue.
over-1b
Possible values
under-1m
1m-10m
10m-50m
50m-100m
100m-200m
200m-1b
over-1b
company. socialNetworksobject
The company's social networks.
company. stateobject
The company's state.
company. stockExchangestring
The company's stock exchange.
NYSE
company. stockSymbolstring
The company's stock symbol.
AMZN
company. technologiesarray
The technologies used by the company.
company. technologyCategoriesarray
The technologies' categories used by the company.
company. totalEmployeesenum
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. totalEmployeesExactnumber
The company's exact number of employees.
3930
company. yearFoundednumber
The company's year of foundation.
1994
GET
https://api.thecompaniesapi.com/v1/companies/gucci.com
Loading response...

Count companies matching your query
Free

Count the companies matching your conditions. Useful if you are building your own search engine for companies.

queryrequired
The conditions the companies must match.
Make sure this parameter is stringified and encoded.
Industries
=
retail
Browse
Add a new condition
GET
https://api.thecompaniesapi.com/v1/companies/count?query=%5B%7B%22attribute%22%3A%22industries%22%2C%22operator%22%3A%22or%22%2C%22sign%22%3A%22equals%22%2C%22values%22%3A%5B%22retail%22%5D%7D%5D
searchoptional
An additionnal search query applied to the company name or domain.
…/companies?search=amazon
searchFieldsoptional
Define the fields to search.
…/companies?searchFields[]=domain&searchFields[]=name
Possible values
domain
name

Response

countnumber
The number of companies matching the conditions.
GET
https://api.thecompaniesapi.com/v1/companies/count
Loading response...

Find similar companies
0.25 Credit

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

julien

This API feature is one of the most powerful. You can use it to find similar companies to your own, or to find companies that are similar to your customers. You can also use it to find companies that are similar to your competitors. The possibilities are endless.

Query parameters

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

Response

companiesarray
The similar companies for your list of domains.
metaobject
The metas information.
GET
https://api.thecompaniesapi.com/v1/companies/similar?domains[]=gucci.com&page=1&size=10
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.

power

We use this feature internally to prioritize the patterns when we want to guess and verify a business email address with external APIs. You can use this endpoint to decrease your API calls to tools like MailboxLayer or Debounce (and therefore your costs).

Query parameters

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

Response

patternsarray
The email patterns used.
GET
https://api.thecompaniesapi.com/v1/companies/gucci.com/email-patterns
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.

nada

If you need additional endpoints, feel free to contact us. We are usually fast to implement them.

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.

julien

You may wonder why our technology searches employees in real-time. From our experience (we were one of them), most services that rely on a database of employees take the risk of having outdated information. People leave from one job to another, get promoted, etc. This issue will never be one with us. The only downside is that it can take a few seconds to get the results.

Query parameters

countriesoptional
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
& 140 others
domainrequired
The company domain to search for employees (can also be a URL as we will extract the domain).
…/employees?domain=gucci.com
findEmailsoptional
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
false
true
hideCompanyoptional
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
false
true
jobTitlesoptional
The job titles (comma-separated) to search for. If not defined, we will search for all job titles.
…/employees?jobTitles=ceo,cto,software%20developer
listIdoptional
The id of the list to save the employees to.
…/employees?listId=102
pageoptional
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.
queryoptional
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.
Job titles
=
marketing
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
sizeoptional
The number of employees to be returned (default to 100, max is 100).
…/employees?size=10

Response

countriesarray
The country codes (comma-separated) to search for. If not defined, we will search for all countries.
employeesarray
The employees that match your conditions.
listobject
The list the employees were saved to.
metaobject
The metas information.
jobTitlesarray
The job titles (comma-separated) to search for. If not defined, we will search for all job titles.
queryarray
A more complex list of conditions the employees must match (if you want something more precise than the jobTitles and countries parameters).
GET
https://api.thecompaniesapi.com/v1/employees
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.

power

We don't deduct credits when you provide the employee's id or when we can't figure out the email address.

Query parameters

domainoptional
The company's domain
…/emails/discover?domain=gucci.com
employeeIdoptional
The employee's id
…/emails/discover?employeId=123
Credits are not deducted with this parameter.
firstNameoptional
The employee's first name
…/emails/discover?firstName=Jay
fullNameoptional
The employee's full name
…/emails/discover?fullName=Jay%20Gatsby
lastNameoptional
The employee's last name
…/emails/discover?lastName=Gatsby
middleNameoptional
The employee's middle name
…/emails/discover?middle=James

Response

emailstring
The discovered email.
emailDisposableboolean
Whether the email is disposable or not.
false
emailDomainstring
The email's domain.
gucci.com
emailFreeboolean
Whether the email is free or not.
false
emailPatternstring
The email's pattern.
[F].[L]
emailStatusstring
The email's status.
valid
Possible values
catch-all
error
guessed
identified
verified
verified-already
emailUsernamestring
The email's username.
jay.gatsby
GET
https://api.thecompaniesapi.com/v1/employees/emails/discover
{email : "[email protected]" ,emailDisposable :false,emailDomain : "gucci.com" ,emailFree :false,emailPattern : "[F].[L]" ,emailStatus : "verified" ,emailUsername : "jay.gatsby" ,}

Enrich an employee from his/her 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).

julien

If you need a specific data point, please ask us for it.

Query parameters

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

Response

companyobject
The company profile for the email.
emailstring
The email sent to enrich.
emailDisposableboolean
Whether the email is disposable or not.
false
emailFreeboolean
Whether the email is free or not.
false
GET
https://api.thecompaniesapi.com/v1/employees/emails/enrich
Loading response...

Industries

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

anthony

We currently have over 3 million industries in our database. We can send you a file with our 100,000 most popular industries if you want to use it in your application.

GET
https://api.thecompaniesapi.com/v1/industries
GET
https://api.thecompaniesapi.com/v1/industries/similar

Find similar industries
Free

Discover similar industries with our API. Identify related sectors and expand your business opportunities.

Query parameters

industriesrequired
The industries to compare with (max: 10).
…/industries/similar?industries[]=saas&industries[]=fintech
pageoptional
The page to fetch (default to 1).
…/industries/similar?page=1
sizeoptional
The number of industries to be returned (between 1 and 100). Default to 25.
…/industries/similar?size=10

Response

industriesarray
The industries that match your conditions.
metaobject
The metas information.
GET
https://api.thecompaniesapi.com/v1/industries/similar?industries[]=saas&size=10
Loading response...

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.

power

If you need additional features, feel free to reach us in the chatbox. We are usually fast to implement them.

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.

nada

Our database includes more than 165,000 job titles categorized in 70 departments and 10 seniority levels.

query

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

Response

jobTitle. departmentstring
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. departmentSecondarystring
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
& 35 others
jobTitle. namestring
The job title's english name.
jobTitle. nameEsstring
The job title's spanish name.
jobTitle. nameFrstring
The job title's french name.
jobTitle. seniorityLevelstring
The job title's seniority level.
Possible values
owner
partner
cxo
vp
director
manager
senior
entry
training
unpaid
GET
https://api.thecompaniesapi.com/v1/job-titles/enrich
Loading response...

Locations

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

julien

ou can use them to filter our companies or target employees in a specific location.

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 parameters

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

Response

citiesarray
The cities that match your conditions.
metaobject
The metas information.
GET
https://api.thecompaniesapi.com/v1/locations/cities
Loading response...

Search counties
Free

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

Query parameters

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

Response

countiesarray
The counties that match your conditions.
metaobject
The metas information.
GET
https://api.thecompaniesapi.com/v1/locations/counties
Loading response...

Search states
Free

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

Query parameters

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

Response

statesarray
The states that match your conditions.
metaobject
The metas information.
GET
https://api.thecompaniesapi.com/v1/locations/states
<