API reference

POST/v1/workspaces

Create a workspace

Returns the first API key once. When email verification is on, signup credits are added after the email link is opened. No authentication.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/workspaces" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Northwind Talent","email":"ops@northwind.example"}'

Example response

Created.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/workspaces/verify

Confirm a signup email

No authentication.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/workspaces/verify" \ \
  -H "authorization: Bearer $KEY"

Example response

Verification outcome.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/workspace

Get the current workspace and key

Scope: `account:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/workspace" \ \
  -H "authorization: Bearer $KEY"

Example response

The workspace this request acts on.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/workspace

Set the low-balance alert

credits.low fires when the balance drops below low_balance_credits. The default is 250. Send null to restore the default.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/workspace" \ \
  -H "authorization: Bearer $KEY"

Example response

The workspace, with the threshold applied.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/api-keys

List API keys

Scope: `account:read`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/api-keys" \ \
  -H "authorization: Bearer $KEY"

Example response

Live keys, newest first. Secrets are never returned.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/api-keys

Create an API key

A key never gets more scopes or a higher daily cap than the key that creates it. Set customer_id to bind the key to one customer. The key pins the RecruitMCP-Version sent with this request, or the current version.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/api-keys" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Read-only dashboard","scopes":["sourcing:read","outreach:read","account:read"]}'

Example response

Created. The secret is shown once.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/api-keys/{key_id}

Revoke an API key

Runs and jobs started with the key stop at their next step.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/api-keys/key_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/billing/plans

List plans and credit rules

No authentication.

Credit cost. Free.

Parameters

No parameters.

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/billing/plans" \ \
  -H "authorization: Bearer $KEY"

Example response

Plans, expiry rules, and signup credits.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/billing/balance

Get the credit balance

Account balance by source. A customer-bound key receives that customer's remaining daily cap, or null when the customer has no cap. It does not receive the account pool, buckets, or subscription.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/billing/balance" \ \
  -H "authorization: Bearer $KEY"

Example response

Balance.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/usage

Get credit usage

A customer-bound key or a RecruitMCP-Customer header sees only that customer's spend. A bound key's balance is its remaining daily cap, or null when the customer has no cap. An account key still sees the account balance.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/usage" \ \
  -H "authorization: Bearer $KEY"

Example response

Usage buckets.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/billing/checkout

Start a credit pack checkout

The only pack is topup: €99 for 7,500 credits. Checkout saves the card for off-session auto-refill. Removed pack ids return 400.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/billing/checkout" \ \
  -H "authorization: Bearer $KEY"

Example response

Hosted checkout page.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/billing/subscriptions

Start a subscription checkout

Scope: `billing:manage`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/billing/subscriptions" \ \
  -H "authorization: Bearer $KEY"

Example response

Hosted checkout page.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/billing/subscription/plan

Change the subscription plan

Scope: `billing:manage`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/billing/subscription/plan" \ \
  -H "authorization: Bearer $KEY"

Example response

The updated subscription.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/billing/auto-refill

Get auto-refill

Threshold, monthly caps, whether a card is on file, and how many refills have been granted this UTC month. Account keys only.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/billing/auto-refill" \ \
  -H "authorization: Bearer $KEY"

Example response

Auto-refill settings.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PUT/v1/billing/auto-refill

Enable or update auto-refill

When the balance is below threshold_credits, the worker charges the €99 pack off-session, up to the monthly caps. A card must already be on file from a pack checkout. Credits are granted only after the payment succeeds. Account keys only.

Credit cost. Free.

Parameters

Example request

curl -sS -X PUT "https://api.recruitmcp.com/v1/billing/auto-refill" \ \
  -H "authorization: Bearer $KEY"

Example response

Saved settings.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/billing/auto-refill

Turn auto-refill off

Keeps the saved card and the last threshold. Account keys only.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/billing/auto-refill" \ \
  -H "authorization: Bearer $KEY"

Example response

Auto-refill is off.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/locations

Find location ids

Turns a place name into geo_ids for people search filters. Known places are free; an unknown place costs one lookup credit the first time and is cached for everyone.

Credit cost. Known places are free. An unknown place costs one lookup credit the first time, then it is cached.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/locations" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 402 insufficient_credits. Add credits; do not retry until then.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/areas

Find the location ids around anchor places

Every known city and area within radius_km of the anchors. Free. geo_ids is the full set; entries is paginated.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/areas" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/industries

List industries

Industry ids. Use the ids in industry_ids and exclude_industry_ids. Free.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/industries" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "8",
      "label": "Engineering"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/seniorities

List seniority levels

Seniority ids. Use the ids in seniority_level_ids and exclude_seniority_level_ids. Free.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/seniorities" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "8",
      "label": "Engineering"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/experience-ranges

List experience ranges

Year buckets for total experience and time at the current company. Use the ids in years_of_experience_ids and years_at_current_company_ids. Free.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/experience-ranges" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "8",
      "label": "Engineering"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/functions

List job functions

Job function ids. Use the ids in function_ids and exclude_function_ids. Free.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/functions" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "8",
      "label": "Engineering"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/languages

List profile languages

Languages a profile is written in. Use the ids in profile_languages. Free.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/languages" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "8",
      "label": "Engineering"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/headcounts

List company size ranges

Current employer headcount ranges. Use the ids in company_headcount. Free.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/headcounts" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "8",
      "label": "Engineering"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/people/search

Search people

One page (25 people) of the person index for a filter set. Filters map one to one to what the index supports; an unknown or unsupported filter is refused with unsupported_filter, and an unknown body field with invalid_request, never ignored. Suppressed people are always removed and counted in omitted.suppressed. People already in your seen register are returned with already_seen true unless exclude_seen is true. A page already fetched in this workspace in the last 30 days is free.

Credit cost. Up to 25 × 1 credits when the page is not already cached. A cached page is free. dry_run spends nothing.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/people/search?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-1" \
  -d '{"filters":{"current_job_titles":["Backend Engineer"],"geo_ids":["90009596"]},"page":1}'

Example response

With ?dry_run=true, a PeopleSearchPreview; nothing is charged or sent. Otherwise the PeopleSearchPage.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 402 insufficient_credits. Add credits; do not retry until then.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/people/{profile_id}

Get a person from your cache

Never charges and never calls the person index. Returns 404 not_cached when the person has not been fetched in this workspace within max_age_days; fetch them with POST /v1/people:fetch. profile_id may also be a URL-encoded profile URL.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/people/profile_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "profile_id": "ACwAAA1",
  "full_name": "Ada Peeters",
  "headline": "Backend Engineer at Acme",
  "experience": [
    {
      "position": "Backend Engineer",
      "company": "Acme",
      "started": "2021-03",
      "current": true
    }
  ],
  "skills": [
    "Go",
    "Kubernetes"
  ],
  "source": "profile_index"
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/people/{profile_id}

Erase a person from this workspace

Deletes the cached profile, contacts, seen entries, list items, and run candidates for the person. Does not suppress; use POST /v1/erasures with suppress true to also block future results.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/people/profile_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/people:fetch

Fetch full profiles

Up to 100 profile ids or profile URLs. Cached copies younger than max_age_days are free. When everything is cached the profiles come back now (200); otherwise a job is queued (202) and job.completed is emitted when it finishes. Not-found and suppressed people are never charged.

Credit cost. 2 credits per live profile that is found. Cached profiles, missing profiles, and suppressed people are free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/people:fetch?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-1" \
  -d '{"ids":["ACwAAA1","ACwAAA2"],"max_age_days":30}'

Example response

With ?dry_run=true, a Preview; nothing is charged or sent. Otherwise the ProfileList.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 402 insufficient_credits. Add credits; do not retry until then.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/people:match

Find one person by name and current company

Reads one search page for the name at the 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.

Credit cost. 1 credit when exactly one person matches, the first time only. Ambiguous and no-match results are free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/people:match?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-1" \
  -d '{"first_name":"Ada","last_name":"Peeters","company":"Acme"}'

Example response

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

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 402 insufficient_credits. Add credits; do not retry until then.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/jobs

List profile fetch jobs

Scope: `sourcing:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/jobs" \ \
  -H "authorization: Bearer $KEY"

Example response

Jobs, newest first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/jobs/{job_id}

Get a job

Scope: `sourcing:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/jobs/job_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The job, with profiles once completed.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lookups/companies

Search known companies

Searches the built-in company list. Free. For any other name use POST /v1/companies:resolve.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lookups/companies" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/companies:resolve

Resolve company names to company URLs

Use the URLs in current_companies or past_companies filters. Known and cached companies are free; each new name costs one lookup credit.

Credit cost. 1 credit per live company lookup. Unknown, cached, and already-known companies are free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/companies:resolve?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-1" \
  -d '{"names":["Showpad","Acme Robotics"],"country":"Belgium"}'

Example response

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

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 402 insufficient_credits. Add credits; do not retry until then.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/people/{profile_id}/contacts

Get stored contact details

Free. Only what an earlier lookup found.

Credit cost. A found contact costs 25 credits. A miss is free. The estimate is returned before a confirmed call.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/people/profile_id_example/contacts" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/people/{profile_id}/contacts

Look up personal email and phone

Charged only when an email or phone is found; a miss is free. The person must be fetched first. Results may arrive later; contacts.completed is emitted.

Credit cost. A found contact costs 25 credits. A miss is free. The estimate is returned before a confirmed call.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/people/profile_id_example/contacts?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "idempotency-key: example-1"

Example response

With ?dry_run=true, a Preview; nothing is charged or sent. Otherwise the ContactsLookup.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 402 insufficient_credits. Add credits; do not retry until then.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/people/{profile_id}/contacts

Delete stored contact details

Scope: `privacy:write`.

Credit cost. A found contact costs 25 credits. A miss is free. The estimate is returned before a confirmed call.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/people/profile_id_example/contacts" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/people/contacts:fetch

Look up contact details for many people

Up to 100 fetched people. Same pricing as the single lookup.

Credit cost. A found contact costs 25 credits. A miss is free. The estimate is returned before a confirmed call.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/people/contacts:fetch?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "idempotency-key: example-1"

Example response

With ?dry_run=true, a Preview; nothing is charged or sent. Otherwise the ContactsLookup.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 402 insufficient_credits. Add credits; do not retry until then.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/seen

List the seen register

Everyone this workspace has seen, shortlisted, contacted, or rejected. A people search marks them already_seen, and drops them when exclude_seen is true.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/seen" \ \
  -H "authorization: Bearer $KEY"

Example response

Entries, most recently updated first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/seen

Add or update seen entries

Up to 1000 people. An entry matching an existing one (same profile, or same name and employer) is updated. Use external_ids to keep your ATS ids next to each person.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/seen" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"entries":[{"profile_id":"ACwAAA1","status":"shortlisted","tags":["backend-ghent"],"external_ids":{"ats":"cand_123"}}]}'

Example response

The stored entries.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/seen:check

Check people against the seen register

Up to 1000 identities, each a profile_url, profile_id, or full_name with current_employer. Free.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/seen:check" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"identities":[{"full_name":"Ada Peeters","current_employer":"Acme"}]}'

Example response

One result per identity, in order.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/seen/{seen_id}

Get a seen entry

Scope: `sourcing:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/seen/seen_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The entry.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/seen/{seen_id}

Update a seen entry

external_ids are merged; tags replace the stored tags.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/seen/seen_id_example" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"status":"rejected","note":"Not open to relocation."}'

Example response

Updated.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/seen/{seen_id}

Remove a seen entry

The person can show up in guided runs again.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/seen/seen_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lists

List candidate lists

Scope: `sourcing:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lists" \ \
  -H "authorization: Bearer $KEY"

Example response

Lists, newest first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/lists

Create a candidate list

Scope: `sourcing:spend`.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/lists" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Backend Ghent shortlist","items":[{"profile_id":"ACwAAA1","note":"Strong Go background"}]}'

Example response

Created.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lists/{list_id}

Get a list

Scope: `sourcing:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lists/list_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The list.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/lists/{list_id}

Rename or describe a list

Scope: `sourcing:spend`.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/lists/list_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Updated.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/lists/{list_id}

Delete a list

Scope: `sourcing:spend`.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/lists/list_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lists/{list_id}/items

List the people on a list

Scope: `sourcing:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lists/list_id_example/items" \ \
  -H "authorization: Bearer $KEY"

Example response

Items in the order they were added.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/lists/{list_id}/items

Add people to a list

People already on the list are skipped.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/lists/list_id_example/items" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"items":[{"profile_id":"ACwAAA1"}]}'

Example response

The items that were added.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/lists/{list_id}/items/{item_id}

Remove a person from a list

Scope: `sourcing:spend`.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/lists/list_id_example/items/item_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/lists/{list_id}/export

Export a list as CSV

Scope: `sourcing:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/lists/list_id_example/export" \ \
  -H "authorization: Bearer $KEY"

Example response

CSV with one row per person.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/settings

Get outreach settings

Working hours and workspace-wide caps. Nothing is sent outside these hours.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/settings" \ \
  -H "authorization: Bearer $KEY"

Example response

Settings.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/outreach/settings

Update outreach settings

Workspace caps can only be lowered here. Working hours stay inside the platform window.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/outreach/settings" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"timezone":"Europe/Brussels","start_hour":9,"end_hour":17}'

Example response

Updated.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/templates

List sequence templates

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/templates" \ \
  -H "authorization: Bearer $KEY"

Example response

Templates.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/accounts

Connect a LinkedIn account

Returns a connect_url for the recruiter to sign in. Call it from the recruiter's browser (or pass their IP) so traffic stays in their country. account.connected is emitted when sign-in finishes. Billed per connected account per month.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/accounts" \ \
  -H "authorization: Bearer $KEY"

Example response

Pending until the recruiter signs in.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 428 Error.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.
• 503 Error.

GET/v1/outreach/accounts

List outreach accounts

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/accounts" \ \
  -H "authorization: Bearer $KEY"

Example response

Accounts.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/accounts/{account_id}

Get an outreach account

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/accounts/account_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The account.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/outreach/accounts/{account_id}

Disconnect an outreach account

Stops every open enrollment on the account, archives its sequences, and removes it. Nothing more is sent from it.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/outreach/accounts/account_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Disconnected.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/accounts/{account_id}/limits

Get today's limits for an account

What was sent, what is scheduled, the caps, and when the next invite can go out.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/accounts/account_id_example/limits" \ \
  -H "authorization: Bearer $KEY"

Example response

Limits.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/outreach/accounts/{account_id}/limits

Change an account's caps

Lowering is always allowed. Raising above a default needs risk_acknowledged true and is recorded.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/outreach/accounts/account_id_example/limits" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"limits":{"invitations_per_day":10}}'

Example response

Updated account.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/sequences

List sequences

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/sequences" \ \
  -H "authorization: Bearer $KEY"

Example response

Sequences, newest first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/sequences

Create a sequence

Steps from a template or your own. Creating a sequence sends nothing.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/sequences" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"account_id":"oa_1a2b3c4d5e6f7a8b9c","name":"Backend Ghent","steps":[{"channel":"linkedin","type":"invite","note":"Hi {{first_name}}, ..."},{"channel":"linkedin","type":"message","wait_days":3,"only_after_accept":true,"body":"Thanks for connecting, {{first_name}}."}]}'

Example response

Created.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/sequences/{sequence_id}

Get a sequence

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/sequences/sequence_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The sequence.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/outreach/sequences/{sequence_id}

Update a sequence

New steps apply to enrollments that have not reached them yet. account_id and template cannot be changed; unknown fields are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/outreach/sequences/sequence_id_example" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"status":"paused"}'

Example response

Updated.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/outreach/sequences/{sequence_id}

Delete a sequence

Refused with 409 while it has open enrollments; stop them or archive the sequence.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/outreach/sequences/sequence_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/enrollments

List enrollments

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/enrollments" \ \
  -H "authorization: Bearer $KEY"

Example response

Enrollments, newest first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/enrollments

Enroll people in a sequence

People from candidates, a run (run_id), a list (list_id), or fetched profiles (profile_ids), de-duplicated. Up to 500. ?dry_run=true renders every message and shows when each first step would go out, without enrolling anyone. People who are suppressed, marked do_not_contact, or already contacted are skipped.

Credit cost. No credits. A connected outreach account is €49 per month.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/enrollments?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-1" \
  -d '{"sequence_id":"seq_1a2b3c4d5e6f7a8b9c","run_id":"run_3c4d5e6f7a8b9c0d1e"}'

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/enrollments/{enrollment_id}

Get an enrollment

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/enrollments/enrollment_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The enrollment.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/enrollments/{enrollment_id}/pause

Pause an enrollment

Scope: `outreach:write`.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/enrollments/enrollment_id_example/pause" \ \
  -H "authorization: Bearer $KEY"

Example response

Paused.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/enrollments/{enrollment_id}/resume

Resume an enrollment

?dry_run=true shows when the next step would go out.

Credit cost. No credits. A connected outreach account is €49 per month.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/enrollments/enrollment_id_example/resume?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "idempotency-key: example-1"

Example response

With ?dry_run=true, a ResumePreview; nothing is charged or sent. Otherwise the Enrollment.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/enrollments/{enrollment_id}/stop

Stop an enrollment

Final. Nothing more is sent to this person from this enrollment.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/enrollments/enrollment_id_example/stop" \ \
  -H "authorization: Bearer $KEY"

Example response

Stopped.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/actions

List outreach actions

Every scheduled, sent, failed, or held step. outcome=awaiting_approval lists messages waiting for approval.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/actions" \ \
  -H "authorization: Bearer $KEY"

Example response

Actions, most recent first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/actions/{action_id}

Get an outreach action

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/actions/action_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The action.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/actions/{action_id}/approve

Approve a held message

?dry_run=true returns the message that would be released.

Credit cost. No credits. A connected outreach account is €49 per month.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/actions/action_id_example/approve?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "idempotency-key: example-1"

Example response

With ?dry_run=true, a Action; nothing is charged or sent. Otherwise the Action.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/sends

Send one LinkedIn action

One invite, message, profile visit, or invite withdrawal outside a sequence. Same caps, working hours, and suppression checks as a sequence.

Credit cost. No credits. A connected outreach account is €49 per month.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/sends?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-1" \
  -d '{"account_id":"oa_1a2b3c4d5e6f7a8b9c","channel":"linkedin","type":"invite","candidate":{"profile_url":"https://www.linkedin.com/in/ada-peeters","first_name":"Ada"},"note":"Hi Ada, quick question about your Go work."}'

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/conversations

List conversations

One conversation per enrollment with messages. Inbound text is returned as untrusted_text.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/conversations" \ \
  -H "authorization: Bearer $KEY"

Example response

Conversations, most recent first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/outreach/conversations/{conversation_id}

Get a conversation with its messages

Scope: `outreach:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/outreach/conversations/conversation_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The conversation.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/outreach/conversations/{conversation_id}/replies

Reply in a conversation

Queued for the next slot inside working hours and the account spacing. ?dry_run=true shows when it would go out.

Credit cost. No credits. A connected outreach account is €49 per month.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/outreach/conversations/conversation_id_example/replies?dry_run=true" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-1" \
  -d '{"body":"Thanks Ada, does Thursday at 10:00 work for a call?"}'

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/erasures

Erase a person and suppress them

Deletes every row in this workspace that names the person and, unless suppress is false, adds a hashed suppression so they never come back in search, runs, or outreach.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/erasures" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"profile_id":"ACwAAA1"}'

Example response

{
  "cost": {
    "credits": 1,
    "cached_items": 0,
    "live_items": 1,
    "upstream_calls": 1
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/suppressions

List suppressions

Hashes only. Suppressions always apply to search.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/suppressions" \ \
  -H "authorization: Bearer $KEY"

Example response

Suppressions, newest first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/suppressions

Suppress a person

Blocks this person from search, runs, lists, contact lookups, and outreach in this workspace. Match on a profile URL, a company URL, an email, or a name together with a company. A name alone is refused: it is not unique.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/suppressions" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"full_name":"Ada North","company":"Northwind"}'

Example response

The suppressions written.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/suppressions/{suppression_id}

Lift a suppression

Opt-outs the person filed themselves cannot be lifted.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/suppressions/suppression_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/privacy/cache

Delete cached profiles, pages, and contact details

The next search or fetch pays again.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/privacy/cache" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/privacy/opt-out

Opt out (for the person themselves)

Anyone can ask to be removed. A confirmation link is emailed; once confirmed, the person is suppressed for every workspace. No authentication.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/privacy/opt-out" \ \
  -H "authorization: Bearer $KEY"

Example response

Confirmation sent.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/privacy/opt-out/confirm

Confirm an opt-out

No authentication.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/privacy/opt-out/confirm" \ \
  -H "authorization: Bearer $KEY"

Example response

Confirmed.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/customers

List customers

Customers are sub-workspaces for platforms that serve their own clients. Each has its own seen register, lists, suppressions, outreach accounts, and daily cap; credits come from your account.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/customers" \ \
  -H "authorization: Bearer $KEY"

Example response

Customers, newest first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/customers

Create a customer

Select it on any request with the RecruitMCP-Customer header, or create a key bound to it.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/customers" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Northwind Recruiting","external_id":"tenant_42","daily_cap_credits":100}'

Example response

{
  "id": "cus_8d1f0a2b3c4d5e6f7a",
  "object": "customer",
  "name": "Northwind Recruiting",
  "external_id": "tenant_42",
  "metadata": {
    "plan": "pro"
  },
  "daily_cap_credits": 100,
  "status": "active",
  "created_at": "2026-11-01T09:00:00Z",
  "updated_at": "2026-11-01T09:00:00Z"
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/customers/{customer_id}

Get a customer

Scope: `account:read`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/customers/customer_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "id": "cus_8d1f0a2b3c4d5e6f7a",
  "object": "customer",
  "name": "Northwind Recruiting",
  "external_id": "tenant_42",
  "metadata": {
    "plan": "pro"
  },
  "daily_cap_credits": 100,
  "status": "active",
  "created_at": "2026-11-01T09:00:00Z",
  "updated_at": "2026-11-01T09:00:00Z"
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/customers/{customer_id}

Update a customer

A disabled customer refuses every request and its runs stop at their next step.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/customers/customer_id_example" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"daily_cap_credits":250,"status":"active"}'

Example response

{
  "id": "cus_8d1f0a2b3c4d5e6f7a",
  "object": "customer",
  "name": "Northwind Recruiting",
  "external_id": "tenant_42",
  "metadata": {
    "plan": "pro"
  },
  "daily_cap_credits": 100,
  "status": "active",
  "created_at": "2026-11-01T09:00:00Z",
  "updated_at": "2026-11-01T09:00:00Z"
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/customers/{customer_id}

Delete a customer and its data

Revokes its bound keys and deletes its seen register, lists, caches, and outreach data. Spend stays on your ledger.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/customers/customer_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

Deleted.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/events

List events

Everything that happened on the account in the last 30 days: jobs, contact lookups, enrollments, replies, accounts, and credits. A customer key sees only its customer's events. The same events are pushed to webhook endpoints.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/events" \ \
  -H "authorization: Bearer $KEY"

Example response

Events, newest first.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/events/{event_id}

Get an event

Scope: `account:read`.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/events/event_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

{
  "id": "evt_job_job_3c4d_20261101093000",
  "object": "event",
  "type": "job.completed",
  "created_at": "2026-11-01T09:30:00Z",
  "customer_id": null,
  "data": {
    "job_id": "job_3c4d5e6f7a8b9c0d1e",
    "status": "completed"
  }
}

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/webhook-endpoints

List webhook endpoints

Scope: `account:read`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/webhook-endpoints" \ \
  -H "authorization: Bearer $KEY"

Example response

Endpoints.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

POST/v1/webhook-endpoints

Add a webhook endpoint

Up to 10 per account. The URL must be public https; private, loopback, and link-local addresses are refused, the address is checked again on every delivery, and redirects are not followed. Each delivery is a POST with the event as JSON and a X-RecruitMCP-Signature header: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<exact request body>" with the endpoint secret>. Reject a delivery whose t is more than five minutes old. Failed deliveries are retried with backoff for about a day; use the event id to ignore duplicates.

Credit cost. Free.

Parameters

Example request

curl -sS -X POST "https://api.recruitmcp.com/v1/webhook-endpoints" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://hooks.example.com/recruitmcp","events":["job.completed","reply.received"]}'

Example response

Created. The signing secret is shown once.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 409 Conflict: idempotency_key_reused, idempotency_in_progress, or a state conflict.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

GET/v1/webhook-endpoints/{endpoint_id}

Get a webhook endpoint

Scope: `account:read`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X GET "https://api.recruitmcp.com/v1/webhook-endpoints/endpoint_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response

The endpoint.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

PATCH/v1/webhook-endpoints/{endpoint_id}

Update a webhook endpoint

Scope: `account:manage`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X PATCH "https://api.recruitmcp.com/v1/webhook-endpoints/endpoint_id_example" \ \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"status":"disabled"}'

Example response

Updated.

Errors

• 400 Invalid request. See error.code: invalid_request, unsupported_filter, idempotency_key_required, unsupported_version.
• 401 Missing, invalid, or expired key.
• 403 insufficient_scope or forbidden.
• 404 not_found, not_cached, or feature_disabled.
• 429 rate_limited, a daily cap, or upstream_busy. Wait for Retry-After.

DELETE/v1/webhook-endpoints/{endpoint_id}

Delete a webhook endpoint

Scope: `account:manage`. Acts on the account; keys bound to a customer are refused.

Credit cost. Free.

Parameters

Example request

curl -sS -X DELETE "https://api.recruitmcp.com/v1/webhook-endpoints/endpoint_id_example" \ \
  -H "authorization: Bearer $KEY"

Example response