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.

Need help?

Message us in the chatbox. A developer will reply under 1 hour to see how we can solve your issue.

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.

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

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

error. code string
For some errors that could be handled programmatically, a short string indicating the error code reported. 403
error. message string
A human-readable message providing more details about the error. For card errors, these messages can be shown to your users. Missing api token
error. param string
If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field. The Company domain is not a string
error. type enum
The type of error returned. apiConnectionError
Possible values apiConnectionError apiError authenticationError invalidRequestError noCreditsRemaining rateLimitError
HTTP status code summary
200 - OK 500, 502, 503, 504 - Server Errors
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 permissions 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 The Companies API's end. (These are rare.)
HTTP status code 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.

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.

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

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

Available Endpoints
GET https://api.thecompaniesapi.com/v1/companies
GET https://api.thecompaniesapi.com/v1/companies/by-name/:name
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 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

name required
The company name. …/companies/by-name/amazon
size optional
The number of companies to be returned (between 1 and 25). Default to 1. …/companies/by-name/amazon?size=2

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.

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

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

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

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.

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 code NAICS. 518210
company. codeSic string
The company's code SIC. 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. county object
The company's county.
Show attributes
company. country object
The company's country.
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 company's technologies.
company. technologyCategories array
The company's categories of technologies.
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...

Enrich a company with a social url (LinkedIn, Instagram, etc.)
1 credit

Retrieve the company profile information by providing a social url we support (see the list below). At least one social network must be provided. We will return more than 50 data points including the industries, the revenue, the technologies…

Multiple social urls can be provided (i.e. both LinkedIn and YouTube) and we will check them in the order they are provided until we find a company that matches it.

Query parameters

angellist optional
The company's AngelList URL. …/companies/by-social?angellist=https://angel.co/company/gucci
crunchbase optional
The company's Crunchbase URL. …/companies/by-social?crunchbase=https://www.crunchbase.com/organization/gucci
dribbble optional
The company's Dribbble URL. …/companies/by-social?dribbble=https://dribbble.com/gucci
facebook optional
The company's Facebook URL. …/companies/by-social?facebook=https://www.facebook.com/gucci
github optional
The company's GitHub URL. …/companies/by-social?github=https://github.com/gucci
instagram optional
The company's Instagram URL. …/companies/by-social?instagram=https://www.instagram.com/gucci
linkedin optional
The company's LinkedIn URL. We handle both alpha urls (/company/gucci) and numeric ids (/company/6585). …/companies/by-social?linkedin=https://www.linkedin.com/company/gucci
pinterest optional
The company's Pinterest URL. …/companies/by-social?pinterest=https://www.pinterest.com/gucci
snapchat optional
The company's Snapchat URL. …/companies/by-social?snapchat=https://www.snapchat.com/add/gucci
tiktok optional
The company's TikTok URL. …/companies/by-social?tiktok=https://www.tiktok.com/@gucci
twitter optional
The company's Twitter URL. …/companies/by-social?twitter=https://twitter.com/gucci
youtube optional
The company's YouTube URL. …/companies/by-social?youtube=https://www.youtube.com/@gucci

Response

Returns a company with all the information for the provided social url. When no company matches, an empty object will be returned. Make sure to handle this case in your code.

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 code NAICS. 518210
company. codeSic string
The company's code SIC. 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. county object
The company's county.
Show attributes
company. country object
The company's country.
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 company's technologies.
company. technologyCategories array
The company's categories of technologies.
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/by-social?linkedin=https://www.linkedin.com/company/gucci
Response
Loading response...

Find similar companies
5 credits

Find similar companies for a list of domains.

Query parameters

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

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.

companies array
The similar companies for your list of domains.
Show attributes
metas 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

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

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

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.

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

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.

Available Endpoints
GET https://api.thecompaniesapi.com/v1/employees/

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.

Available Endpoints
GET https://api.thecompaniesapi.com/v1/emails

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

email required
The business email. …/emails/[email protected]

Response

Returns an object that contains the company profile (when available) as well as other information about the specified business email.

company object
The company profile for the business email.
Show attributes
email string
The business email sent. [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/emails/:email
Response
Loading response...

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.

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

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.

Available Endpoints
GET https://api.thecompaniesapi.com/v1/job-titles/:name

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

name required
The job title's name. …/job-titles/chief%20executive%20officer

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.

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 investment journalism judicial lawyer logistics mechanical media relations network nursing office management paralegal pipeline product product design product marketing professor project engineering project management property management quality assurance realtor recruiting researcher security software support systems tax teacher therapy video web web design wellness writing
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/:name
Response
Loading response...

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.

Available Endpoints
GET https://api.thecompaniesapi.com/v1/lists
GET https://api.thecompaniesapi.com/v1/lists/:listId/companies
GET https://api.thecompaniesapi.com/v1/lists/:listId/employees

Fetch lists
Free

This endpoint lets you retrieve all the lists that belong to your team.

Query parameters

page optional
The page to fetch (default to 1). …/lists?page=1
size optional
The number of lists to be returned (between 1 and 100). Default to 10. …/lists?size=50
type optional
The type of lists you want to retrieve. …/lists?type=companies
Possible values companies employees

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.

lists array
The lists that belong to your team.
Show attributes
metas array
The metas information.
Show attributes
Endpoint
GET https://api.thecompaniesapi.com/v1/lists
Response
Copy
{ data : [ { analytics : { }, companyList : null , createdAt : "2022-04-01T13:07:14.000+00:00" , dynamic : false , id : 4246 , imported : false , integrations : [ ], invisible : false , name : "French NodeJS Companies" , processActive : false , processInitialized : true , processingAt : "2022-04-01T13:07:15.000+00:00" , query : [ ], type : "companies" , } , { analytics : { }, companyList : { }, createdAt : "2022-02-22T07:23:53.000+00:00" , dynamic : false , id : 3838 , imported : false , integrations : [ ], invisible : false , name : "Edtech Ceos & Founders" , processActive : false , processInitialized : true , processingAt : "2022-02-22T07:23:53.000+00:00" , query : [ ], type : "employees" , } , { analytics : { }, companyList : null , createdAt : "2022-02-22T07:23:52.000+00:00" , dynamic : false , id : 3837 , imported : false , integrations : [ ] , invisible : false , name : "Edtech Companies" , processActive : false , processInitialized : true , processingAt : "2022-02-22T07:23:53.000+00:00" , query : [ ], type : "companies" , } , ] , meta : { total : 4 , perPage : 10 , currentPage : 1 , lastPage : 1 , firstPage : 1 , firstPageUrl : "/?page=1" , lastPageUrl : "/?page=1" , nextPageUrl : null , previousPageUrl : null , } , }

Fetch companies from a list
Free

This endpoint allows you to retrieve the companies you have added to a list.

Query parameters

page optional
The page to fetch (default to 1). …/lists/:listId/domains?page=1
size optional
The number of companies to be returned (between 1 and 100). Default to 10. …/lists/:listId/domains?size=50

Response

Returns a paginated response of the companies you have added to the list.

companies array
The companies that belongs to your list.
Show attributes
metas array
The metas information.
Show attributes
Endpoint
GET https://api.thecompaniesapi.com/v1/lists/1234/domains
Response
Copy
{ data : [ { alexaRank : 55726 , analyzedAt : "2020-09-24T08:40:05.000Z" , businessType : null , city : { }, codeNaics : "334" , codeSic : "737" , country : { }, description : "Blade was created in 2015 to design and develop a new type of Cloud computers, with a simple vision: Computer power should be mutualized. \\Tablets, smartphones and other connected devices have redefined our relationship to computing. Yet we struggle to move our contents and applications seamlessly across our devices. Cloud computing has fostered major evolutions in the way we use technology. Yet our PCs remain idle on our desks most of the time. \\This is poised to change. \\In the future, computer power will be allocated smartly. Our computers will be in the cloud. And we will be able to access them from any device. \\We want to be at the forefront of this revolution. \\Blade employs a team of passionate, highly skilled developers, as well as experts in business, law, marketing and distribution, and gaming. If you would like to know more about our company, please feel free to call us, or even stop by our office. We will be delighted to offer you coffee, and tell you more about our business." , domain : "shadow.tech" , domainAlts : [ ] , domainName : "shadow" , domainTld : "tech" , emailPatterns : [ ], id : 20035 , industries : [ ], industryMain : "software" , logo : "https://poweredwith.nyc3.cdn.digitaloceanspaces.com/images/domains/shadow.tech.jpg" , monthlyVisitors : "1m-10m" , name : "Blade - Shadow" , phoneNumber : "(888) 890-6714" , revenue : "1m-10m" , socialNetworks : { }, technologies : [ ], technologyCategories : [ ], totalEmployees : "50-200" , yearFounded : 2015 , } , { alexaRank : 602519 , analyzedAt : "2020-10-26T02:32:34.000Z" , businessType : null , city : { }, codeNaics : "54199" , codeSic : "7299" , country : { }, description : "Cocolis.fr favorise les pratiques économes, écologiques et sociales en mettant en relation les particuliers qui ont besoin d'envoyer un objet et ceux qui ont de la place dans leur coffre ou dans leur valise. Les uns payent leur envoi jusqu'à 80% moins cher et les autres remboursent une partie de leurs frais de transport, tout en rendant service." , domain : "cocolis.fr" , domainAlts : [ ] , </