---
title: "Find one person by name and current company"
method: POST
path: "/v1/people:match"
tags: ["Profiles"]
---

# Find one person by name and current company

`POST /v1/people:match`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/people:match`
- 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`)

Looks up one person by name and current company. Charged one lead credit only when exactly one person matches (outcome exact), and only the first time that person is returned. Ambiguous and no-match outcomes are free.

Scope: `sourcing:spend`.

## Query parameters

- `dry_run` boolean

## Headers

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

## Request body

- PeopleMatchRequest
  - `first_name` string
  - `last_name` string
  - `full_name` string: Instead of first_name and last_name.
  - `company` string, required: Current employer name or company URL.
  - `confirm` boolean: Deprecated. Accepted and ignored. An authorized match runs without it.
  - `confirm_token` string: From approval_required. Required only when the estimate is above the key threshold.

## Response `200`

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

- union
  - PeopleMatch
    - `object` 'person_match'
    - `outcome` 'exact' | 'ambiguous' | 'none', required
    - `match` PersonStub, required
      - `profile_id` string, required: Search id for this person, an opaque string. GET /v1/people/{profile_id} also accepts the alternate id.
      - `alternate_id` string, nullable: The other profile id for the same person. Null until the person has been enriched and both ids are known.
      - `full_name` string, nullable
      - `location` string, nullable
      - `profile_url` string, nullable
      - `photo` string, nullable: Profile photo on this API, /v1/media/{token}. The token expires after 7 days; a later response signs a new one. Null when there is no photo.
      - `current_positions` object[]
        - `title` string, nullable
        - `company_name` string, nullable
        - `company_id` string, nullable
        - `company_url` string, nullable
        - `current` boolean
        - `description` string, nullable: The role description as written on the profile.
        - `started_on` object, nullable: Start of this role, for example { year: 2020, month: 1, text: "2020-01" }. Keys can be missing.
          - `year` integer
          - `month` integer
          - `text` string
        - `tenure_at_position` object, nullable: Time in this role, for example { numYears: 2, numMonths: 7 }. A key whose value is 0 is left out, so { numYears: 4 } means 4 years and 0 months. Null when neither is known.
          - `numYears` integer
          - `numMonths` integer
        - `tenure_at_company` object, nullable: Time at this company, same shape as tenure_at_position: a key whose value is 0 is left out.
          - `numYears` integer
          - `numMonths` integer
      - `identity_key` string, nullable
      - `already_seen` boolean: True when the person is in your seen register.
    - `cost` Cost, required
      - `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. `free_tier_limit` (do not retry): This workspace has used its free upstream allowance. `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.

## Changes

- **2026-10-20** `ad27b35513a6`: 8 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`
  - …4 more

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/people:match/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)