Companies
Two endpoints serve companies. /companies finds companies by name and returns who they are, for free. /company-profiles returns each company's profile, read from its own website, and counts toward your monthly allowance: one for each company returned, the same as a job.
List Companies
GET /v1/public/companies
Returns a paginated list of companies: id, name and website. Free, and available after your allowance is spent.
curl -H "X-API-Key: $JOBVEN_API_KEY" \
"https://api.jobven.com/v1/public/companies?search=acme&limit=20"
const response = await fetch(
'https://api.jobven.com/v1/public/companies?search=acme&limit=20',
{ headers: { 'X-API-Key': process.env.JOBVEN_API_KEY } }
);
const { data: companies } = await response.json();
import requests
import os
response = requests.get(
'https://api.jobven.com/v1/public/companies',
headers={'X-API-Key': os.environ['JOBVEN_API_KEY']},
params={'search': 'acme', 'limit': 20}
)
companies = response.json()['data']
Query Parameters
| Parameter | Type | Description |
|---|---|---|
search | string | Company name or website contains this text, up to 200 characters |
isVerified | boolean | Filter by verification status |
status | enum | active, inactive |
sortBy | enum | name, foundedYear, totalJobsPosted, activeJobsCount, createdAt. Ties are broken by id |
sortOrder | enum | ASC, DESC, in any case |
page | number | Page number, from 1 to 100,000 |
limit | number | Results per page |
Response
{
"data": [
{ "id": 1042, "name": "TechCorp Inc.", "website": "https://techcorp.com" }
],
"meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
GET /v1/public/companies/{id} returns one company in the same shape, or 404.
List Company Profiles
GET /v1/public/company-profiles
Returns a paginated list of companies with their profiles. Each company returned counts one toward your monthly allowance.
# Software companies with 200 to 1,000 employees
curl -H "X-API-Key: $JOBVEN_API_KEY" \
"https://api.jobven.com/v1/public/company-profiles?industry=technology_software&minEmployees=200&maxEmployees=1000"
Query Parameters
Every parameter of List Companies, with search matching the name, the website or the description, plus:
| Parameter | Type | Description |
|---|---|---|
industry | string | Companies in any of these industries, up to 10. Same keys as a job's industry (see Industries) |
size | enum | Exactly this employee band: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+ |
minEmployees | number | Companies whose band reaches at least this many employees. minEmployees=100 matches 51-200 and up |
maxEmployees | number | Companies whose band starts at or below this many employees. maxEmployees=500 matches 201-500 and below |
includeUnknownSize | boolean | With minEmployees or maxEmployees, also return companies whose size is not known |
sortBy=foundedYear puts companies with no known year last in either order. An unknown industry, size or sortOrder value returns 400.
Response
{
"data": [
{
"id": 1042,
"name": "TechCorp Inc.",
"website": "https://techcorp.com",
"description": "TechCorp makes payroll and scheduling software for restaurants.",
"industry": "technology_software",
"size": "201-500",
"sizeMin": 201,
"sizeMax": 500,
"sizeSource": "stated",
"foundedYear": 2014,
"headquarters": { "city": "Toronto", "state": "Ontario", "country": "CA" },
"linkedinUrl": "https://www.linkedin.com/company/techcorp",
"twitterUrl": null,
"githubUrl": "https://github.com/techcorp",
"profileUpdatedAt": 1792000000
}
],
"meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | number | Company ID. A job's companies[].id is the same ID |
name | string | Company name |
website | string | Company website URL |
description | string | null | What the company does, in one or two plain sentences |
industry | string | null | One of the industry keys |
size | string | null | Employee band, e.g. 51-200 |
sizeMin | number | null | Lower bound of the band |
sizeMax | number | null | Upper bound of the band; null for 10001+ |
sizeSource | string | null | stated: the company's site gives its head count. estimated: estimated from the site |
foundedYear | number | null | Year founded, when the company's site states it |
headquarters | object | null | { city, state, country }, when the company's site states it. country is an ISO 3166-1 alpha-2 code |
linkedinUrl | string | null | The company's LinkedIn page |
twitterUrl | string | null | The company's X account |
githubUrl | string | null | The company's GitHub organization |
profileUpdatedAt | number | null | When the profile was last read from the company's site (Unix seconds) |
Profiles are read from each company's own website and refreshed every 90 days. A field the site does not establish is null, and a company not yet profiled has null in every profile field.
foundedYear, headquarters and the social links come from the company's site as written. description is written by a model from the site, and industry and an estimated size are classified by a model. An estimated size is published only at high confidence; check sizeSource before treating a band as exact.Industries
technology_software, healthcare_medical, finance_banking, education, retail_ecommerce, manufacturing, consulting_professional, marketing_advertising, government_public, energy_utilities, transportation_logistics, real_estate_construction, hospitality_food, media_entertainment, nonprofit_ngo, other
Get a Company Profile
GET /v1/public/company-profiles/{id}
Returns one company with the fields above, or 404 when no company has that ID. Counts one toward your monthly allowance. Use it to look up the company behind a job: each entry in a job's companies carries the company's id.
curl -H "X-API-Key: $JOBVEN_API_KEY" \
"https://api.jobven.com/v1/public/company-profiles/1042"
Pagination
Both lists use offset-based pagination with page and limit parameters.
const page = 1;
const limit = 50;
const response = await fetch(
`https://api.jobven.com/v1/public/companies?page=${page}&limit=${limit}`,
{ headers: { 'X-API-Key': process.env.JOBVEN_API_KEY } }
);
const { data: companies, meta } = await response.json();
// Fetch the next page while page < meta.totalPages
const nextPage = page + 1;