---
title: "Resolve company names to company URLs"
method: POST
path: "/v1/companies:resolve"
tags: ["Companies"]
---

# Resolve company names to company URLs

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

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

## Query parameters

- `dry_run` boolean

## Headers

- `Idempotency-Key` string
- `RecruitMCP-Version` '2026-10-13'
- `RecruitMCP-Customer` string

## Request body

- CompanyResolveRequest
  - `names` string[], required: Company names or company URLs. Up to 50.
  - `country` string: Country that disambiguates common names.
  - `confirm` boolean: Deprecated. Accepted and ignored. The call runs when the key is authorized.
  - `confirm_token` string: From approval_required. Required only when the estimate is above the key threshold.

## Response `200`

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

- union
  - CompanyList
    - `object` 'list', required
    - `data` Company[], required
      - `query_name` string, required
      - `company_name` string, nullable
      - `company_id` string, nullable
      - `company_url` string, nullable
      - `universal_name` string, nullable
      - `industry` string, nullable
      - `employee_count` integer, nullable
      - `website` string, nullable
      - `not_found` boolean
    - `next_cursor` string, nullable, required: Pass as cursor for the next page. Null on the last page.
    - `has_more` boolean, required
    - `cost` Cost
      - `credits` integer, required: Credits charged by this call. Whole credits. 0 on an idempotent replay, where the body also has replayed: true and the header Idempotent-Replayed: true.
      - `cached_items` integer: Items read from cache. On a replay, the value of the first response.
      - `live_items` integer: Items fetched live by this call. 0 on a replay.
      - `upstream_calls` integer: Index calls made by this call. 0 on a replay.
  - Preview: Returned when dry_run=true. Nothing was spent or changed. Search, profile, company, and contact previews set dry_run true and requires_confirm false.
    - `dry_run` true, required: True on this preview. Nothing was charged and nothing was changed.
    - `estimate` Estimate, required
      - `credits_min` integer, required: Lowest expected spend. Whole credits.
      - `credits_max` integer, required: Ceiling. Spend never passes it. Whole credits.
      - `expected_pages` integer
      - `expected_profile_fetches` integer
      - `skipped_pages_from_checkpoints` integer: Pages already paid for in an earlier search. Not charged again.
      - `cached_items` integer: Items served from cache, free.
      - `balance_credits` integer, nullable: Account balance. A customer-bound key gets that customer's remaining daily cap, or null when the customer has no cap.
      - `sufficient` boolean: True when the visible balance covers credits_max, or when that balance is hidden. False when a live call can return 402 insufficient_credits.
      - `warning` string, nullable: Null when sufficient is true. Otherwise the live call can return 402 insufficient_credits.
      - `requires_confirm` boolean, required: False on a search, profile, company, or contact preview. True when the call still needs an explicit confirm.
    - `cost` Cost
      - `credits` integer, required: Credits charged by this call. Whole credits. 0 on an idempotent replay, where the body also has replayed: true and the header Idempotent-Replayed: true.
      - `cached_items` integer: Items read from cache. On a replay, the value of the first response.
      - `live_items` integer: Items fetched live by this call. 0 on a replay.
      - `upstream_calls` integer: Index calls made by this call. 0 on a replay.

## Other responses

- `400`: `idempotency_key_required` (do not retry): This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview. `invalid_request` (do not retry): A field is missing or has a value this endpoint does not accept. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `402`: `daily_credit_cap_reached` (do not retry): This key's daily credit cap is reached. `insufficient_credits` (do not retry): Not enough credits for this operation.
- `403`: `forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `409`: `approval_required` (do not retry): This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it. `confirm_token_used` (do not retry): This confirm_token was already used. Ask for a new preview to get another. `idempotency_in_progress` (retry): A request with this Idempotency-Key is still running. Retry after it finishes. `idempotency_key_reused` (do not retry): Idempotency-Key was already used with a different request.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded. `upstream_busy` (retry): The profile source is busy. Retry after the delay.
- `502`: `upstream_busy` (retry): The profile source is busy. Retry shortly. `upstream_error` (retry): The profile source returned a response that could not be used. Retry later.
- `503`: `upstream_busy` (retry): The profile source is paused.
- `504`: `gateway_timeout` (retry): The call did not finish in time. Nothing was charged. Retry the same request.

## Changes

- **2026-10-20** `ad27b35513a6`: 9 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `402`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - …5 more

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/companies:resolve/post.md)

---

[API](https://skmtc.dev/recruitmcp/apis/recruitmcp-api.md) · [All operations](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/revisions/ad27b35513a6?raw)