jobdata

Companies API Endpoint Documentation

Accessing detailed company profiles.

Docs Company data
Table of contents

Introduction

The Companies endpoint is a powerful feature within the jobdata API that offers comprehensive information about companies that are currently hiring. This endpoint serves as a directory to explore and retrieve detailed company profiles, including their name, logo, website, social media links, description, headquarters location, size, founding year, specialties, industry, and type. It is designed to help job search platforms, HR software, market researchers, and business analysts obtain valuable insights into companies across various industries.

Endpoint Overview

Endpoint (list): /api/companies/

Endpoint (single element): /api/companies/{id}/

Method: GET for listing companies and GET with company ID for retrieving a specific company's details.

Authorization Required: Yes (access pro subscription)

Description: The Companies endpoint allows users to fetch a list of companies with optional filtering parameters to narrow down the search based on specific criteria, such as industry, company size, and location. Additionally, it provides a detailed view of a single company's profile by specifying the company ID.

Request

Making requests to the Companies endpoint requires an authorization header with your API key. Below are examples of how to make requests using both curl and Python for listing companies and retrieving details of a specific company.

Listing Companies Using curl

curl -X GET "https://jobdataapi.com/api/companies/?industry_id=1&min_size=11&max_size=200" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Listing Companies Using Python

import requests

url = "https://jobdataapi.com/api/companies/"
params = {
    "industry_id": 79,
    "min_size": 11,
    "max_size": 200
}
headers = {"Authorization": "Api-Key YOUR_API_KEY"}
response = requests.get(url, headers=headers, params=params)
print(response.json())

Retrieving a Specific Company's Details Using curl

curl -X GET "https://jobdataapi.com/api/companies/123/" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Retrieving a Specific Company's Details Using Python

import requests

url = "https://jobdataapi.com/api/companies/123/"
headers = {"Authorization": "Api-Key YOUR_API_KEY"}
response = requests.get(url, headers=headers)
print(response.json())

Parameters

For listing companies, the endpoint supports several query parameters to filter the results:

  • is_agency: Filter for recruiting/staffing agencies via is_agency=true or all other companies (direct hiring) with false. By default all companies are shown in the results.
  • description: Filter companies by a search term in their description - requires a valid access pro API key.
  • founded_after: Filter companies founded after a specific year (YYYY).
  • founded_before: Filter companies founded before a specific year (YYYY).
  • founded_in: Filter companies founded in a specific year.
  • hq: Filter companies by the location of their headquarters.
  • industry_id: Filter companies by industry ID to match companies in specific industries (see Industries endpoint for more info).
  • max_size: Filter companies with a maximum number of employees (see size range values below).
  • min_size: Filter companies with a minimum number of employees (see size range values below).
  • name: Filter companies by their name or parts of it - requires a valid access pro API key.
  • specialty: Filter companies by a specific specialty or focus area.
  • type_id: Filter companies by their type ID, such as public, private, or non-profit (see Company Types endpoint for more info).
  • website: Filter companies by their website URL or domain name - requires a valid access pro API key.
  • min_jobs_open: Filter companies by minimum number of open positions.
  • min_jobs_total: Filter companies by minimum number of total positions (including closed/expired).
  • page: Specifies the page number in the paginated result set - requires a valid access pro API key.
  • page_size: Determines the number of results per page (1 - 5000, default: 200) - requires a valid access pro API key.

Note that as a access pro subscriber many of the above query parameters are also available for the /api/jobs/ endpoint and can be used for advanced job post filtering - see Jobs endpoint for more info on this feature.

Example Request with Parameters

cURL

curl -X GET "https://jobdataapi.com/api/companies/?name=OpenAI&min_size=11&max_size=500&page=1&page_size=250" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Python

import requests

url = "https://jobdataapi.com/api/companies/"
params = {
    "name": "OpenAI",
    "min_size": 11,
    "max_size": 500,
    "page": 1,
    "page_size": 250
}
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Company Size Filtering

When utilizing the max_size and min_size parameters to filter companies by their size, it's essential to use specific predefined values. These values correspond to different ranges of employee counts, allowing for precise segmentation of companies based on their size. The valid values and their associated employee count ranges are as follows:

  • 0 for companies with 0-1 employees
  • 2 for companies with 2-10 employees
  • 11 for companies with 11-50 employees
  • 51 for companies with 51-200 employees
  • 201 for companies with 201-500 employees
  • 501 for companies with 501-1,000 employees
  • 1001 for companies with 1,001-5,000 employees
  • 5001 for companies with 5,001-10,000 employees
  • 10001 for companies with more than 10,000 employees

To apply these filters, select the appropriate value that matches the size range you're interested in. For instance, to filter for companies that have between 51 to 200 employees, you would specify min_size=51 and max_size=200 in your query parameters.

Response

The response is a JSON object containing a list of companies that match the query parameters. Each company in the list includes details such as the company's name, logo, website URL, description, headquarters location, size, founding year, and more.

Response Data Structure

The companies_list operation returns a JSON object containing the following main attributes:

  • count: The total number of companies matching the query.
  • next: A URL to the next page of results (pagination).
  • previous: A URL to the previous page of results (pagination).
  • results: An array of company objects, each containing detailed information about a company.

Each object in the results array includes:

  • id: A unique integer identifier for the company.
  • name: The name of the company.
  • logo: A URL to the company's logo image.
  • website_url: The company's official website URL.
  • linkedin_url: The company's LinkedIn page URL.
  • twitter_handle: The company's Twitter handle.
  • github_url: The company's GitHub page URL.
  • is_agency: A boolean flag that determines if the company is a recruiting/staffing firm or not.
  • info_description: A brief description of the company.
  • info_hq: The location of the company's headquarters.
  • info_size: The size of the company in terms of number of employees.
  • info_founded: The year the company was founded.
  • info_specialties: Specialties or areas of focus for the company.
  • info_industry: An object representing the industry the company operates in, including an id and name.
  • info_type: An object representing the type of company, including an id and name.
  • num_jobs_open: The number of open/live jobs (updated every 2h).
  • num_jobs_total: The number of overall/total jobs (updated every 2h).

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 123,
      "name": "OpenAI",
      "logo": "https://example.com/logo.png",
      "website_url": "https://openai.com",
      "linkedin_url": "https://linkedin.com/company/openai",
      "twitter_handle": "openai",
      "github_url": "https://github.com/openai",
      "info_description": "OpenAI is an AI research and deployment company dedicated to ensuring that general-purpose artificial intelligence benefits all of humanity...",
      "info_hq": "San Francisco, CA",
      "info_size": 201,
      "info_founded": 2015,
      "info_specialties": "artificial intelligence and machine learning",
      "info_industry": {
        "id": 79,
        "name": "Research Services"
      },
      "info_type": {
        "id": 5,
        "name": "Partnership"
      },
      "num_jobs_open":135,
      "num_jobs_total":326
    }
  ]
}

Use Cases

  • Job Search Platforms: Enhance job listings by providing detailed company profiles alongside job ads.
  • HR Software: Offer in-depth insights into companies for users researching potential employers.
  • Market Researchers: Analyze company data across industries, sizes, and locations for market analysis.
  • Business Analysts: Obtain a comprehensive overview of companies for competitive analysis and business strategy planning.

Notes

  • Replace YOUR_API_KEY with your actual jobdata API key in the header.
  • The addition of enhanced company information may be delayed by a few weeks after a company first appears in the database. So it is advised to check and update locally stored company info regularly, e.g. on a monthly basis.
  • This endpoint is available to access pro subscribers only.
  • The detailed information provided by this endpoint can greatly enhance the value of job listings and company research tools.

This section offers a complete guide on how to interact with the Companies endpoint, ensuring that developers and businesses can effectively utilize this information to enhance their applications and services.

Related Docs

Industries API Endpoint Documentation
View documentation
CSV File Downloads Documentation
View documentation
Company Types API Endpoint Documentation
View documentation