Companies

Resolve company names to company URLs

Changed on Oct 20, 2026

Use the URLs in current_companies or past_companies filters. A cache hit, a company on the built-in list, and a lookup with no result are free. A company found live costs 1 credit, unless the profile source marks that lookup free.

Scope: sourcing:spend.

post/v1/companies:resolve

Request

Base URL: https://api.recruitmcp.com
URL: https://api.recruitmcp.com/v1/companies:resolve
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://recruitmcp.com/oauth/authorize, token URL https://recruitmcp.com/oauth/token, scopes: sourcing:spend)

Query parameters

dry_runboolean

Optional. true returns a free preview, labelled dry_run, and changes nothing. The same flag in the JSON body is honored. A dry run never charges. Omit it to run the call.

Headers

Idempotency-Keystring

Required unless dry_run=true. At most 128 characters. The same key and body replays the first response for 24 hours and does not charge again. A different body is 409 idempotency_key_reused. A second call waits for the first and replays it. 409 idempotency_in_progress means the first call was still running when the wait ended.

RecruitMCP-Version'2026-10-13'

API version. Defaults to the version the key was created with. Supported: 2026-10-13.

RecruitMCP-Customerstring

Act inside this customer (cus_…). Ignored for keys bound to a customer, which always act inside theirs.

Request body

namesstring[] required

Company names or company URLs. Up to 50.

countrystring

Country that disambiguates common names.

confirmboolean

Deprecated. Accepted and ignored. The call runs when the key is authorized.

confirm_tokenstring

From approval_required. Required only when the estimate is above the key threshold.

Response

Live response is a CompanyList. With ?dry_run=true, a Preview; nothing is charged or sent.

Example response

{
  "object": "list",
  "data": [
    {
      "query_name": "Paperkiln",
      "company_name": "Paperkiln",
      "company_id": "51207",
      "company_url": "https://companies.example.com/paperkiln",
      "universal_name": "paperkiln",
      "industry": "Computer Software",
      "employee_count": 400,
      "website": "https://example.com",
      "not_found": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Changes

Oct 20, 2026ad27b35513a6 Revision changes
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status

Operation history