Profiles

Find one person by name and current company

Changed on Oct 20, 2026

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.

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)

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

first_namestring

last_namestring

full_namestring

Instead of first_name and last_name.

companystring required

Current employer name or company URL.

confirmboolean

Deprecated. Accepted and ignored. An authorized match runs without it.

confirm_tokenstring

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

Example request

{
  "first_name": "Ada",
  "last_name": "Peeters",
  "company": "Acme"
}

Response

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

Example response

{
  "object": "person_match",
  "outcome": "exact",
  "match": {
    "profile_id": "lead_8f2a1c_1",
    "full_name": "Ada Peeters",
    "location": "London, England, United Kingdom",
    "alternate_id": null,
    "photo": null,
    "profile_url": "https://profiles.example.com/ada-peeters",
    "current_positions": [
      {
        "title": "Backend Engineer",
        "company_name": "Acme Robotics",
        "company_id": null,
        "company_url": "https://companies.example.com/acme-robotics",
        "current": true,
        "description": "Builds the fleet API in Go.",
        "started_on": {
          "year": 2021,
          "month": 3,
          "text": "2021-03"
        },
        "tenure_at_position": {
          "numYears": 5,
          "numMonths": 7
        },
        "tenure_at_company": {
          "numYears": 6
        }
      }
    ],
    "identity_key": "ada peeters|acme robotics",
    "already_seen": 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

Operation history