Profiles

Enrich profiles

Changed on

Full public professional profiles for up to 100 profile ids or profile URLs. This does not return email or phone; a contact lookup does that. The body is the full profile, including education. MCP enrich_profiles defaults view to full and returns that same profile; compact is opt-in. Credits stay the profile price either way. profile_id is the search id or a public profile URL. alternate_id is the other profile id for the same person when both are known. Either id reads the same cached profile. Cached copies younger than max_age_days are free. A live enrich usually queues a job: the response is 202 with job_id, poll_url (/v1/jobs/{job_id}), and status queued, plus a Location header, and X-Credits-Charged is 0. Poll GET /v1/jobs/{job_id} every few seconds until status is completed, or wait for job.completed. The call that queued the job is charged when it completes; the completed job has result.data and credits_charged, read from the ledger and equal to result.cost.credits, and the ledger row carries this call's request_id and the job_id. When everything is already stored the profiles come back at once (200). A suppressed person is omitted and never charged.

Polling example:

KEY="<your API key>"
curl -s -X POST https://api.recruitmcp.com/v1/people:enrich \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"ids":["lead_8f2a1c_1"]}'
# 202: {"job_id":"job_01J0JOB0EXAMPLE","poll_url":"/v1/jobs/job_01J0JOB0EXAMPLE","status":"queued",...}
until curl -s https://api.recruitmcp.com/v1/jobs/job_01J0JOB0EXAMPLE \
  -H "Authorization: Bearer $KEY" | grep -q '"status":"\(completed\|failed\)"'; do sleep 3; done
curl -s https://api.recruitmcp.com/v1/jobs/job_01J0JOB0EXAMPLE -H "Authorization: Bearer $KEY"
# result.data holds the profiles; credits_charged equals result.cost.credits

Scope: sourcing:spend.

post/v1/people:enrich

Request

  • Base URL: https://api.recruitmcp.com
  • URL: https://api.recruitmcp.com/v1/people:enrich
  • 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

idsstring[]

Profile ids or public profile URLs. Up to 100.

profile_idsstring[]

Alias of ids, the same name POST /v1/people/contacts:fetch uses. Merged with ids.

profile_urlsstring[]

Public profile URLs. Up to 100 together with ids.

max_age_daysinteger

Cached copies younger than this are free. Default 30.

enrich_companiesboolean

Add industry and size to each experience entry.

confirmboolean

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

confirm_tokenstring

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

Example request

{
  "ids": [
    "lead_8f2a1c_1",
    "lead_3c71e0_2"
  ],
  "max_age_days": 30
}

Response

200 when everything is already stored: a ProfileList at once. With ?dry_run=true, a Preview; nothing is charged or sent.

OR

Example response

{
  "object": "list",
  "data": [
    {
      "profile_id": "lead_8f2a1c_1",
      "full_name": "Ada Peeters",
      "headline": "Backend Engineer at Acme Robotics",
      "profile_url": "https://profiles.example.com/ada-peeters",
      "experience": [
        {
          "position": "Backend Engineer",
          "company": "Acme Robotics",
          "started": "2021-03",
          "current": true,
          "company_url": "https://companies.example.com/acme-robotics"
        }
      ],
      "skills": [
        "Go",
        "Kubernetes"
      ],
      "source": "profile_index",
      "fetched_at": "2026-10-13T09:00:00Z"
    },
    {
      "profile_id": "lead_3c71e0_2",
      "full_name": "Jonas Vermeulen",
      "headline": "Platform Engineer at Paperkiln",
      "profile_url": "https://profiles.example.com/jonas-vermeulen",
      "experience": [
        {
          "position": "Backend Engineer",
          "company": "Acme Robotics",
          "started": "2021-03",
          "current": true,
          "company_url": "https://companies.example.com/acme-robotics"
        }
      ],
      "skills": [
        "Go",
        "Kubernetes"
      ],
      "source": "profile_index",
      "fetched_at": "2026-10-13T09:00:00Z"
    }
  ],
  "not_found": [],
  "omitted": {
    "suppressed": 0
  },
  "cost": {
    "credits": 4,
    "cached_items": 0,
    "live_items": 2,
    "upstream_calls": 2
  }
}

Changes

  • ad27b35513a6Revision 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