Companies API

Discover companies and manage which companies Recuity tracks for your workspace.

Endpoint	Purpose
GET /api/v1/companies	Search companies
POST /api/v1/companies	Add a new company to your workspace
POST /api/v1/companies/{company_id}/tracking	Start tracking a company's jobs
DELETE /api/v1/companies/{company_id}/tracking	Stop tracking a company's jobs

Search companies

GET/api/v1/companies

Search and retrieve companies, including details, social links, and tracking status. Results can include companies your workspace added as well as companies from the shared public directory. Use ownership and tracking_status to narrow the scope.

https://recuity.ai/api/v1/companies

Provide exactly one of q, similar_to_company_id or domain. An invalid request returns 400 Bad Request.

Query parameters

Parameter	Type	Required	Description
q	String	One of	Company search query
similar_to_company_id	String	One of	Return companies similar to this ID (a 24-character hex ID)
domain	String	One of	Find a company by its website domain (e.g. `monvia.com`), up to 50 characters
location	String	No	Filter by location, up to 50 characters
company_type	String	No	`Startup`, `SME`, `Enterprise`, `Government`, `Education`, `NonProfit`
ownership	String	No	`TenantOwned` (your companies), `Public` (shared directory)
tracking_status	String	No	`Tracked`, `NotTracked`
has_hiring_signal	Boolean	No	`true` returns only companies whose home page links to a careers or vacancies page, `false` only those without such a link. Omit for no filter
page	Number	No	Page number, default 1

Example request

curl -X GET \
  "https://recuity.ai/api/v1/companies?q=tech&company_type=Startup" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://recuity.ai/api/v1/companies",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "q": "tech",
        "company_type": "Startup"
    }
)
data = response.json()

Example response

200 OK

{
  "companies": [
    {
      "id": "692987bcd5644d953f62cc87",
      "name": "TechCorp Solutions",
      "current_url": "https://techcorp-solutions.com",
      "location": "London, GB",
      "company_type": "Startup",
      "company_size": "201-500 employees",
      "founded_year": 2014,
      "is_tracked": true,
      "is_owned_by_tenant": false
    }
  ],
  "total_results": 20,
  "current_page": 1,
  "has_more": true,
  "page_size": 20
}

Response object

Field	Type	Description
companies	Array	Array of company objects
total_results	Number	Number of companies on this page (not a total across pages; use `has_more` to page on)
current_page	Number	Current page number
has_more	Boolean	Whether more pages are available
page_size	Number	Number of results per page

Company object fields

Field	Type	Description
id	String	Unique company identifier
name	String	Company name
summary	String	Company summary
current_url	String	Company website URL
location	String	Primary company location
headquarter	String	Headquarter location
other_locations	Array	Other company locations
company_type	String	`Startup`, `SME`, `Enterprise`, `Government`, `Education`, `NonProfit`
company_size	String	Company size range (e.g. `201-500 employees`)
founded_year	Number	Year the company was founded
industry_sectors	Array	Industry sectors
potential_job_titles	Array	Potential job titles at this company
linkedin_url	String	LinkedIn profile URL (nullable)
twitter_url	String	Twitter profile URL (nullable)
facebook_url	String	Facebook page URL (nullable)
instagram_url	String	Instagram profile URL (nullable)
youtube_url	String	YouTube channel URL (nullable)
company_logo	String	Company logo image URL (nullable)
primary_website_language	String	Primary language of the company website (nullable)
is_tracked	Boolean	Whether the company is being tracked
is_owned_by_tenant	Boolean	Whether the company was added by your workspace
has_hiring_signal	Boolean	Whether the company's home page links to a careers or vacancies page. An indication the company may be hiring, not a list of open roles

Add a company

POST/api/v1/companies

Add a new private company to your workspace by providing its website URL. Set track_jobs to start tracking in the same call. Returns 400 Bad Request if the request is invalid or your plan's limit on added companies is reached.

https://recuity.ai/api/v1/companies

Request body

Field	Type	Required	Description
url	String	Yes	Company website: a domain (e.g. `company.com`) or an `https://` URL. `http://` URLs are rejected
primary_location	String	No	Primary location (e.g. `London, GB`), up to 50 characters
company_type	String	No	`Startup`, `SME`, `Enterprise`, `Government`, `Education`, `NonProfit`
track_jobs	Boolean	No	Set `true` to start tracking immediately after adding

Example request

curl -X POST \
  "https://recuity.ai/api/v1/companies" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example-company.com",
  "primary_location": "London, GB",
  "company_type": "Startup",
  "track_jobs": true
}'

import requests

response = requests.post(
    "https://recuity.ai/api/v1/companies",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example-company.com",
        "primary_location": "London, GB",
        "company_type": "Startup",
        "track_jobs": True
    }
)
data = response.json()

Example response

200 OK

{
  "success": true,
  "message": "Company created successfully",
  "company_id": "692987bcd5644d953f62cc87"
}

Response fields

Field	Type	Description
success	Boolean	Whether the company was added successfully
message	String	Status message
company_id	String	Unique identifier for the newly added company

Start tracking a company's jobs

POST/api/v1/companies/{company_id}/tracking

Begin crawling and indexing jobs from this company's careers page into your workspace. Returns 404 Not Found if the company does not exist or your workspace cannot track it, and 400 Bad Request if your plan's tracking limit is reached.

https://recuity.ai/api/v1/companies/{company_id}/tracking

Path parameters

Parameter	Type	Required	Description
company_id	String	Yes	Unique company identifier from the company search response

Example request

curl -X POST \
  "https://recuity.ai/api/v1/companies/692987bcd5644d953f62cc87/tracking" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

company_id = "692987bcd5644d953f62cc87"
response = requests.post(
    "https://recuity.ai/api/v1/companies/" + company_id + "/tracking",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
data = response.json()

Example response

200 OK

{
  "success": true,
  "message": "Company tracked successfully"
}

Response fields

Field	Type	Description
success	Boolean	Whether tracking was started successfully
message	String	Status message

Stop tracking a company's jobs

DELETE/api/v1/companies/{company_id}/tracking

Stop crawling this company's careers page. Existing job data is removed from your workspace. While a crawl of the company is in progress this returns 400 Bad Request with the number of minutes to wait.

https://recuity.ai/api/v1/companies/{company_id}/tracking

Path parameters

Parameter	Type	Required	Description
company_id	String	Yes	Unique company identifier

Example request

curl -X DELETE \
  "https://recuity.ai/api/v1/companies/692987bcd5644d953f62cc87/tracking" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

company_id = "692987bcd5644d953f62cc87"
response = requests.delete(
    "https://recuity.ai/api/v1/companies/" + company_id + "/tracking",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
data = response.json()

Example response

200 OK

{
  "success": true,
  "message": "Company untracked successfully"
}

Response fields

Field	Type	Description
success	Boolean	Whether tracking was stopped successfully
message	String	Status message

We value your privacy

Cookie settings

Companies API

Search companies

Query parameters

Example request

Example response

Response object

Company object fields

Add a company

Request body

Example request

Example response

Response fields

Start tracking a company's jobs

Path parameters

Example request

Example response

Response fields

Stop tracking a company's jobs

Path parameters

Example request

Example response

Response fields