{ "openapi": "3.1.0", "info": { "title": "RecruitMCP API", "version": "2026-10-13", "summary": "RecruitMCP gives AI agents and developers recruiting data: search people and companies, enrich profiles, and find email and phone via REST API or MCP.", "description": "RecruitMCP gives AI agents and developers recruiting data: search people and companies, enrich profiles, and find email and phone via REST API or MCP.", "contact": { "name": "RecruitMCP", "url": "https://recruitmcp.com" }, "license": { "name": "Proprietary. Use is governed by the RecruitMCP terms.", "url": "https://recruitmcp.com/legal/terms" } }, "externalDocs": { "description": "Guide, MCP setup, and the LangChain toolkit (langchain-recruitmcp) at /docs/langchain.", "url": "https://recruitmcp.com/docs" }, "servers": [ { "url": "https://api.recruitmcp.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "The workspace and API keys." }, { "name": "Customers", "description": "One workspace per end customer: its own seen register, lists, and caps. Credits stay on the account." }, { "name": "Billing", "description": "Balance, usage, plans, checkout, and auto-refill." }, { "name": "Search", "description": "Search people, and look up places, areas, and filter ids." }, { "name": "Profiles", "description": "Cached profiles, live profile fetches, a name and company match, and profile jobs." }, { "name": "Companies", "description": "Known companies, and resolving a company name to a URL." }, { "name": "Contacts", "description": "Email and phone for a person, when you ask." }, { "name": "Lists", "description": "Saved lists and the seen register." }, { "name": "Privacy", "description": "Erasure, suppression, cache deletion, and the public opt-out." }, { "name": "Events", "description": "Account events and signed webhook endpoints." } ], "x-tagGroups": [ { "name": "Account", "tags": [ "Account" ] }, { "name": "Customers", "tags": [ "Customers" ] }, { "name": "Billing", "tags": [ "Billing" ] }, { "name": "Search", "tags": [ "Search" ] }, { "name": "Profiles", "tags": [ "Profiles" ] }, { "name": "Companies", "tags": [ "Companies" ] }, { "name": "Contacts", "tags": [ "Contacts" ] }, { "name": "Lists", "tags": [ "Lists" ] }, { "name": "Privacy", "tags": [ "Privacy" ] }, { "name": "Events", "tags": [ "Events" ] } ], "paths": { "/v1/workspaces": { "post": { "operationId": "createWorkspace", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Create a workspace", "description": "Returns the first API key once. When email verification is on, signup credits are added after the email link is opened. attribution is optional. When it is omitted, the rmcp_attr cookie from the first visit is stored instead. marketing_opt_in is optional and defaults to false.\n\nNo authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "description": "Owner email. Required: the confirmation link goes there, and the free credits are added once it is opened. A missing or malformed address is 400 invalid_request with details.field email." }, "first_name": { "type": [ "string", "null" ], "description": "Owner first name. Optional. Not taken from the workspace name." }, "marketing_opt_in": { "type": "boolean", "description": "Optional. Leave false, or omit it, until the person ticks the product-updates checkbox." }, "attribution": { "type": "object", "properties": { "utm_source": { "type": [ "string", "null" ], "description": "utm_source from the first visit." }, "utm_medium": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ], "description": "https referrer without a query string." }, "landing_path": { "type": [ "string", "null" ], "description": "Path of the first page. Starts with /." } } } }, "required": [ "name", "email" ] }, "example": { "name": "Northwind Talent", "email": "ops@northwind.example", "marketing_opt_in": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreated" } } } }, "400": { "description": "`invalid_request` (do not retry): email is required. Free credits are added after you confirm it. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "email is required. Free credits are added after you confirm it.", "value": { "error": { "code": "invalid_request", "message": "email is required. Free credits are added after you confirm it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "field": "email" }, "fix": "Send email with the owner's address. The API key comes back at once; the free credits are added when the link in the confirmation email is opened.", "docs": "/docs/errors#400" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/signup": { "post": { "operationId": "signupWorkspace", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Create a workspace", "description": "Same as POST /v1/workspaces. attribution is optional. When it is omitted, the rmcp_attr cookie from the first visit is stored instead.\n\nNo authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "description": "Owner email. Required: the confirmation link goes there, and the free credits are added once it is opened. A missing or malformed address is 400 invalid_request with details.field email." }, "first_name": { "type": [ "string", "null" ], "description": "Owner first name. Optional. Not taken from the workspace name." }, "marketing_opt_in": { "type": "boolean", "description": "Optional. Leave false, or omit it, until the person ticks the product-updates checkbox." }, "attribution": { "type": "object", "properties": { "utm_source": { "type": [ "string", "null" ], "description": "utm_source from the first visit." }, "utm_medium": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ], "description": "https referrer without a query string." }, "landing_path": { "type": [ "string", "null" ], "description": "Path of the first page. Starts with /." } } } }, "required": [ "name", "email" ] }, "example": { "name": "Northwind Talent", "email": "ops@northwind.example", "marketing_opt_in": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreated" } } } }, "400": { "description": "`invalid_request` (do not retry): email is required. Free credits are added after you confirm it. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "email is required. Free credits are added after you confirm it.", "value": { "error": { "code": "invalid_request", "message": "email is required. Free credits are added after you confirm it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "field": "email" }, "fix": "Send email with the owner's address. The API key comes back at once; the free credits are added when the link in the confirmation email is opened.", "docs": "/docs/errors#400" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/workspaces/verify": { "post": { "operationId": "verifyWorkspaceEmail", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Confirm a signup email", "description": "No authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Verification outcome.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`invalid_verification_link` (do not retry): This confirmation link is invalid, used, or expired.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_verification_link": { "summary": "This confirmation link is invalid, used, or expired.", "value": { "error": { "code": "invalid_verification_link", "message": "This confirmation link is invalid, used, or expired.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/workspaces/verify/resend": { "post": { "operationId": "resendWorkspaceVerification", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Send the confirmation email again", "description": "For a workspace whose signup email is not confirmed yet. The answer is the same whether or not the address has such a workspace. At most 3 emails per address per hour; above that the answer is the same and nothing is sent.\n\nNo authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] }, "example": { "email": "ada@example.com" } } } }, "responses": { "202": { "description": "Accepted. Sent when the address has a workspace waiting for confirmation.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "verification_resend" ] }, "message": { "type": "string" } }, "required": [ "object", "message" ] } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/workspaces/recover": { "post": { "operationId": "requestKeyRecovery", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Ask for a new API key by email", "description": "For a lost key. When the address is the exact, confirmed owner address of a workspace, a link is emailed to that address. The link works once, expires in 15 minutes, and asks for a confirmation before it issues a new key. The answer is the same whether or not the address has a workspace. At most 3 emails per address per hour; above that the answer is the same and nothing is sent. At most 10 requests per network per hour.\n\nNo authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] }, "example": { "email": "ada@example.com" } } } }, "responses": { "202": { "description": "Accepted. A link is sent when the address is the confirmed email of a workspace.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "key_recovery_request" ] }, "message": { "type": "string" } }, "required": [ "object", "message" ] } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/workspaces/recover/link": { "post": { "operationId": "describeKeyRecovery", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Check a key recovery link", "description": "Names the workspace a recovery link is for, without using the link. Same 404 for a link that is invalid, used, or expired.\n\nNo authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "The link is live.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "key_recovery_link" ] }, "workspace_name": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "object", "workspace_name", "expires_at" ] } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`invalid_recovery_link` (do not retry): This recovery link is invalid, used, or expired. Ask for a new one at /recover.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_recovery_link": { "summary": "This recovery link is invalid, used, or expired. Ask for a new one at /recover.", "value": { "error": { "code": "invalid_recovery_link", "message": "This recovery link is invalid, used, or expired. Ask for a new one at /recover.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/workspaces/recover/confirm": { "post": { "operationId": "confirmKeyRecovery", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Confirm a key recovery", "description": "Uses the link once. Returns a new API key, shown once, with the scopes the old keys had. The workspace's other secret keys are revoked. Keys bound to a customer and OAuth connections stay. A confirmation email goes to the workspace address with the keys and connections still active and how to revoke them. Same 404 for a link that is invalid, used, or expired.\n\nNo authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "The new key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "key_recovery" ] }, "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" }, "api_key": { "type": "string", "description": "Shown once." }, "key_prefix": { "type": "string" }, "revoked_keys": { "type": "integer", "description": "Old keys revoked." } }, "required": [ "object", "workspace_id", "workspace_name", "api_key", "key_prefix", "revoked_keys" ] } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`invalid_recovery_link` (do not retry): This recovery link is invalid, used, or expired. Ask for a new one at /recover.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_recovery_link": { "summary": "This recovery link is invalid, used, or expired. Ask for a new one at /recover.", "value": { "error": { "code": "invalid_recovery_link", "message": "This recovery link is invalid, used, or expired. Ask for a new one at /recover.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/workspace": { "get": { "operationId": "getWorkspace", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Get the current workspace and key", "description": "Scope: `account:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "The workspace this request acts on.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "`unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "patch": { "operationId": "updateWorkspace", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Update workspace preferences", "description": "credits.low fires when the balance drops below low_balance_credits. The default is 250. Send null to restore the default. marketing_opt_in stores the product-updates choice. lifecycle_suppressed stops follow-up emails. Send at least one of these fields.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "low_balance_credits": { "type": [ "integer", "null" ], "description": "Whole credits. Null restores the default.", "minimum": 0 }, "marketing_opt_in": { "type": "boolean", "description": "Product updates and tips. Omit to leave the stored choice." }, "lifecycle_suppressed": { "type": "boolean", "description": "Stop follow-up emails for this workspace. Omit to leave the stored flag." } } } } } }, "responses": { "200": { "description": "The workspace, with the change applied.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "List API keys", "description": "Scope: `account:read`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Live keys, newest first. Secrets are never returned.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "post": { "operationId": "createApiKey", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Create an API key", "description": "A key never gets more scopes, a higher daily cap, or a higher approval threshold than the key that creates it. Omitted scopes copy the caller. Do not put account:manage or billing:manage on an agent key. Set customer_id to bind the key to one customer. approval_threshold_credits null or omitted means no HTTP threshold and 500 credits on MCP. approval_threshold_enrollments null or omitted means no HTTP threshold and 25 scheduled enrollments on MCP. The key pins the RecruitMCP-Version sent with this request, or the current version.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "sourcing:read", "sourcing:spend", "lists:write", "contacts:spend", "outreach:read", "outreach:write", "outreach:send", "outreach:approve", "privacy:write", "account:read", "account:manage", "billing:manage" ] }, "description": "Default: every scope of the calling key." }, "daily_cap_credits": { "type": [ "number", "null" ], "description": "Credits this key may spend per UTC day." }, "approval_threshold_credits": { "type": [ "integer", "null" ], "description": "Search, profile, company, and contact calls above this estimate return approval_required. Null means unset." }, "approval_threshold_enrollments": { "type": [ "integer", "null" ], "description": "An enrollment whose summary.scheduled is above this returns approval_required. Null means unset." }, "customer_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "name": "Read-only dashboard", "scopes": [ "sourcing:read", "account:read" ] } } } }, "responses": { "201": { "description": "Created. The secret is shown once.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/api-keys/{key_id}": { "delete": { "operationId": "revokeApiKey", "x-recruitmcp-category": "account", "tags": [ "Account" ], "summary": "Revoke an API key", "description": "Runs and jobs started with the key stop at their next step. Revoking the workspace's only active key leaves no key that can call the API, so it needs `?confirm_revoke=true`; without it the call is 409 confirmation_required and nothing is revoked. Create a new key first. If no key is left, \"Lost your key?\" on the console login emails a link to get a new one.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm_revoke", "in": "query", "required": false, "description": "Required to revoke the workspace's only active key. Ignored when other active keys remain.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/customers": { "get": { "operationId": "listCustomers", "x-recruitmcp-category": "account", "tags": [ "Customers" ], "summary": "List customers", "description": "Customers are sub-workspaces for platforms that serve their own clients. Each has its own seen register, lists, suppressions, and daily cap; credits come from your account.\n\nScope: `account:read`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "name": "external_id", "in": "query", "required": false, "description": "Only the customer with this external_id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Customers, newest first.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "post": { "operationId": "createCustomer", "x-recruitmcp-category": "account", "tags": [ "Customers" ], "summary": "Create a customer", "description": "Select it on any request with the RecruitMCP-Customer header, or create a key bound to it.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" }, "example": { "name": "Northwind Recruiting", "external_id": "tenant_42", "daily_cap_credits": 100 } } } }, "responses": { "201": { "description": "Created.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/customers/{customer_id}": { "get": { "operationId": "getCustomer", "x-recruitmcp-category": "account", "tags": [ "Customers" ], "summary": "Get a customer", "description": "Scope: `account:read`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "The customer.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "patch": { "operationId": "updateCustomer", "x-recruitmcp-category": "account", "tags": [ "Customers" ], "summary": "Update a customer", "description": "A disabled customer refuses every request and its runs stop at their next step.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" }, "example": { "daily_cap_credits": 250, "status": "active" } } } }, "responses": { "200": { "description": "Updated.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "delete": { "operationId": "deleteCustomer", "x-recruitmcp-category": "account", "tags": [ "Customers" ], "summary": "Delete a customer and its data", "description": "Revokes its bound keys and deletes its seen register, lists, and caches. Spend stays on your ledger.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/plans": { "get": { "operationId": "listPlans", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "List plans and credit rules", "description": "No authentication.", "security": [], "responses": { "200": { "description": "Plans, expiry rules, and signup credits.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plans" } } } }, "400": { "description": "`unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/balance": { "get": { "operationId": "getBalance", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Get the credit balance", "description": "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.\n\nScope: `account:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Balance.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "`unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Get credit usage", "description": "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.\n\nScope: `account:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "name": "group_by", "in": "query", "required": false, "description": "day, purpose, api_key, or customer. Default day.", "schema": { "type": "string", "enum": [ "day", "purpose", "api_key", "customer" ] } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end.", "schema": { "type": "string", "format": "date-time" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Only spend inside this customer. Account keys only.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Usage buckets.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/checkout": { "post": { "operationId": "createCheckout", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Start a credit pack checkout", "description": "Starts checkout for the credit pack on sale. Prices are listed at https://recruitmcp.com/pricing. Checkout saves the card for off-session auto-refill. Removed pack ids return 400.\n\nScope: `billing:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "billing:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pack": { "type": "string", "description": "Pack id. The only pack is topup." } }, "required": [ "pack" ] }, "example": { "pack": "topup" } } } }, "responses": { "200": { "description": "Hosted checkout page.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/subscriptions": { "post": { "operationId": "createSubscription", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Start a subscription checkout", "description": "Scope: `billing:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "billing:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "description": "Plan id: starter, growth, or scale." } }, "required": [ "plan" ] }, "example": { "plan": "growth" } } } }, "responses": { "200": { "description": "Hosted checkout page.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/subscription/plan": { "post": { "operationId": "changeSubscriptionPlan", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Change the subscription plan", "description": "An upgrade charges the prorated price difference right away. The plan changes only once that invoice is paid; then the workspace gets the new plan's monthly credits minus the old plan's, once per change. status is upgraded when the payment went through, requires_action when the card needs authentication on hosted_invoice_url, and payment_failed when it was declined (the plan does not change). A downgrade (status scheduled_downgrade) is not prorated: there is no refund and no credits are taken back. The plan stays as it is until the next cycle, effective_at; then the lower price and credits start. Asking for the current plan while a downgrade is scheduled cancels the downgrade (status downgrade_canceled). An upgrade while a downgrade is scheduled is refused with status downgrade_scheduled (scheduled_plan and effective_at name the downgrade): cancel the downgrade first. While an upgrade payment is still pending, any change is refused with status payment_pending and hosted_invoice_url. While the plan is set to cancel in the billing portal, any change is refused with status cancel_scheduled, effective_at (the cancel date) and a message: resume the plan in the billing portal first. A subscription without automatic tax is refused with status tax_location_required and a message while the billing address cannot be used to add VAT: add it in the billing portal, then try again. Nothing is changed or charged on a refusal.\n\nScope: `billing:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "billing:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "description": "Plan id: starter, growth, or scale." } }, "required": [ "plan" ] }, "example": { "plan": "growth" } } } }, "responses": { "200": { "description": "The updated subscription.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/auto-refill": { "get": { "operationId": "getAutoRefill", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Get auto-refill", "description": "Threshold, monthly caps, whether a card is on file, and how many refills have been granted this UTC month. Account keys only.\n\nScope: `account:read`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Auto-refill settings.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRefill" } } } }, "400": { "description": "`unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "put": { "operationId": "updateAutoRefill", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Enable or update auto-refill", "description": "When the balance is below threshold_credits, the worker charges the pack on sale off-session, up to the monthly caps. Prices are listed at https://recruitmcp.com/pricing. A card must already be on file from a pack checkout. Credits are granted only after the payment succeeds. Account keys only.\n\nScope: `billing:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "billing:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRefillInput" } } } }, "responses": { "200": { "description": "Saved settings.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRefill" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "delete": { "operationId": "disableAutoRefill", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Turn auto-refill off", "description": "Keeps the saved card and the last threshold. Account keys only.\n\nScope: `billing:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "billing:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Auto-refill is off.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRefill" } } } }, "400": { "description": "`unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/developer": { "get": { "operationId": "getDeveloperBilling", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Get Developer billing", "description": "Spending limit and current-period metered usage. 404 feature_disabled when Developer billing is off for this deployment. Account keys only.\n\nScope: `account:read`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Developer billing.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperBilling" } } } }, "400": { "description": "`unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`feature_disabled` (do not retry): Developer billing is not enabled.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "feature_disabled": { "summary": "Developer billing is not enabled.", "value": { "error": { "code": "feature_disabled", "message": "Developer billing is not enabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "patch": { "operationId": "updateDeveloperSpendLimit", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Set the Developer spending limit", "description": "Whole euros from 10 to 1000. The first unpaid cycle is also capped, and a server ceiling can be lower. 404 feature_disabled when Developer billing is off. Account keys only.\n\nScope: `billing:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "billing:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spend_limit_eur": { "type": "integer", "description": "Monthly limit in euros." } }, "required": [ "spend_limit_eur" ] }, "example": { "spend_limit_eur": 50 } } } }, "responses": { "200": { "description": "Updated Developer billing.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperBilling" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`feature_disabled` (do not retry): Developer billing is not enabled.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "feature_disabled": { "summary": "Developer billing is not enabled.", "value": { "error": { "code": "feature_disabled", "message": "Developer billing is not enabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/billing/developer/checkout": { "post": { "operationId": "createDeveloperCheckout", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "Start Developer card setup", "description": "Stripe Checkout in setup mode saves a card. Usage after the prepaid balance is zero is metered and billed monthly in arrears. Refused while a plan subscription is open. 404 feature_disabled when Developer billing is off. Account keys only.\n\nScope: `billing:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "billing:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Hosted card setup.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "`unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`feature_disabled` (do not retry): Developer billing is not enabled.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "feature_disabled": { "summary": "Developer billing is not enabled.", "value": { "error": { "code": "feature_disabled", "message": "Developer billing is not enabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "503": { "description": "`internal` (do not retry): Developer billing is not configured.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Developer billing is not configured.", "value": { "error": { "code": "internal", "message": "Developer billing is not configured.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/billing/transactions": { "get": { "operationId": "listBillingTransactions", "x-recruitmcp-category": "account", "tags": [ "Billing" ], "summary": "List credit transactions", "description": "Credit grants, purchases, usage, and expiries, newest first. A customer-bound key sees the account ledger. Upstream cost rows are omitted. kind filters to grant, purchase, usage, or expiry. description says what the row is. A profile enrich that did not finish or found nothing is returned as a positive grant with a description that the credits were returned. request_id is the X-Request-Id of the API or MCP call that caused the charge; for an async enrich or contact lookup it is the call that started the job, and job_id names that job. Both are null when unknown, for example on older rows.\n\nScope: `account:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Only rows of this kind.", "schema": { "type": "string", "enum": [ "grant", "purchase", "usage", "expiry" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Ledger rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditTransactionList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lookups/locations": { "get": { "operationId": "lookupLocations", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "Find location ids", "description": "Turns a place name into geo_ids for people search filters. Free, including a place this server has not seen before. The result is cached. This call never charges. An empty result includes a hint. A region name points at a city or the country.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Place name, for example London.", "schema": { "type": "string" } }, { "name": "prefer_area", "in": "query", "required": false, "description": "Prefer the metropolitan area over the city.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Matches, best first.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`free_tier_limit` (do not retry): This workspace has used its free upstream allowance.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "free_tier_limit": { "summary": "This workspace has used its free upstream allowance.", "value": { "error": { "code": "free_tier_limit", "message": "This workspace has used its free upstream allowance.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "kind": "search_pages", "limit": 60 } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded. `upstream_busy` (retry): The profile source is busy. Retry after the delay.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_busy": { "summary": "The profile source is busy. Retry after the delay.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry after the delay.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "502": { "description": "`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.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is busy. Retry shortly.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry shortly.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_error": { "summary": "The profile source returned a response that could not be used. Retry later.", "value": { "error": { "code": "upstream_error", "message": "The profile source returned a response that could not be used. Retry later.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "hint": "retry later" } } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "503": { "description": "`upstream_busy` (retry): The profile source is paused.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is paused.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is paused.", "request_id": "req_01J0REQUEST0EXAMPLE" }, "retry_at": "2026-10-13T15:00:00.000Z" }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/lookups/areas": { "get": { "operationId": "lookupArea", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "Find the location ids around anchor places", "description": "Free. Anchor places and radius_km become at most 12 location ids. Under 20 km only the anchor city is used. At 20 km or more, major cities within radius_km of an anchor are included when coordinates are known. geo_ids is that set. The search index has no radius: pass geo_ids as the location filter of a people search.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "anchors", "in": "query", "required": true, "description": "Place names. Repeat the parameter or separate with |.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "radius_km", "in": "query", "required": false, "description": "Default 30.", "schema": { "type": "integer", "minimum": 10, "maximum": 100 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "geo_ids to put in a filter.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Area" }, "example": { "geo_ids": [ "90009496" ], "entries": [ { "geo_id": "90009496", "title": "London Area, United Kingdom", "is_area": true } ], "next_cursor": null, "has_more": false, "note": "The search index has no radius. Pass these geo ids as the location filter. Major cities within 30 km are included, at most 12 geo ids.", "cost": { "credits": 0 } } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`free_tier_limit` (do not retry): This workspace has used its free upstream allowance.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "free_tier_limit": { "summary": "This workspace has used its free upstream allowance.", "value": { "error": { "code": "free_tier_limit", "message": "This workspace has used its free upstream allowance.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "kind": "search_pages", "limit": 60 } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded. `upstream_busy` (retry): The profile source is busy. Retry after the delay.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_busy": { "summary": "The profile source is busy. Retry after the delay.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry after the delay.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "502": { "description": "`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.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is busy. Retry shortly.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry shortly.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_error": { "summary": "The profile source returned a response that could not be used. Retry later.", "value": { "error": { "code": "upstream_error", "message": "The profile source returned a response that could not be used. Retry later.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "hint": "retry later" } } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "503": { "description": "`upstream_busy` (retry): The profile source is paused.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is paused.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is paused.", "request_id": "req_01J0REQUEST0EXAMPLE" }, "retry_at": "2026-10-13T15:00:00.000Z" }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/lookups/companies": { "get": { "operationId": "lookupCompanies", "x-recruitmcp-category": "sourcing", "tags": [ "Companies" ], "summary": "Search known companies", "description": "Searches the built-in company list. Free. For any other name use POST /v1/companies:resolve.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Part of a company name.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Matches.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/companies:resolve": { "post": { "operationId": "resolveCompanies", "x-recruitmcp-category": "sourcing", "tags": [ "Companies" ], "summary": "Resolve company names to company URLs", "description": "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.\n\nScope: `sourcing:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/DryRun" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResolveRequest" }, "example": { "names": [ "Paperkiln", "Acme Robotics" ], "country": "Belgium" } } } }, "responses": { "200": { "description": "Live response is a CompanyList. With ?dry_run=true, a Preview; nothing is charged or sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CompanyList" }, { "$ref": "#/components/schemas/Preview" } ] }, "examples": { "live": { "summary": "Live response", "value": { "object": "list", "data": [ { "query_name": "Paperkiln", "company_name": "Paperkiln", "company_id": "51207", "company_url": "https://companies.example.com/paperkiln", "universal_name": "paperkiln", "industry": "Computer Software", "employee_count": 400, "website": "https://example.com", "not_found": false } ], "next_cursor": null, "has_more": false, "cost": { "credits": 1, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } } }, "dry_run": { "summary": "With dry_run=true", "value": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 1, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false, "cached_items": 0 }, "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } } } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "value": { "error": { "code": "idempotency_key_required", "message": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "daily_credit_cap_reached": { "summary": "This key's daily credit cap is reached.", "value": { "error": { "code": "daily_credit_cap_reached", "message": "This key's daily credit cap is reached.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "cap": "key", "resets_at": "2026-10-14T00:00:00.000Z" } }, "resets_at": "2026-10-14T00:00:00.000Z" }, "x-retryable": false }, "insufficient_credits": { "summary": "Not enough credits for this operation.", "value": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "required_credits": 25, "balance_credits": 3 } }, "required_credits": 25, "balance_credits": 3 }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "approval_required": { "summary": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "value": { "error": { "code": "approval_required", "message": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "approval_threshold_credits": 500, "credits_max": 25 } }, "estimate": { "credits_min": 0, "credits_max": 25, "requires_confirm": false }, "confirm_token": "v1.payload.sig", "approval_threshold_credits": 500, "cost": { "credits": 0 } }, "x-retryable": false }, "confirm_token_used": { "summary": "This confirm_token was already used. Ask for a new preview to get another.", "value": { "error": { "code": "confirm_token_used", "message": "This confirm_token was already used. Ask for a new preview to get another.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still running. Retry after it finishes.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running. Retry after it finishes.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "idempotency_key_reused": { "summary": "Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded. `upstream_busy` (retry): The profile source is busy. Retry after the delay.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_busy": { "summary": "The profile source is busy. Retry after the delay.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry after the delay.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "502": { "description": "`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.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is busy. Retry shortly.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry shortly.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_error": { "summary": "The profile source returned a response that could not be used. Retry later.", "value": { "error": { "code": "upstream_error", "message": "The profile source returned a response that could not be used. Retry later.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "hint": "retry later" } } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "503": { "description": "`upstream_busy` (retry): The profile source is paused.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is paused.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is paused.", "request_id": "req_01J0REQUEST0EXAMPLE" }, "retry_at": "2026-10-13T15:00:00.000Z" }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "504": { "description": "`gateway_timeout` (retry): The call did not finish in time. Nothing was charged. Retry the same request.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "gateway_timeout": { "summary": "The call did not finish in time. Nothing was charged. Retry the same request.", "value": { "error": { "code": "gateway_timeout", "message": "The call did not finish in time. Nothing was charged. Retry the same request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/lookups/industries": { "get": { "operationId": "listIndustries", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "List industries", "description": "Industry ids. Use the ids in industry_ids and exclude_industry_ids. Free.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Only values whose label contains this text.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Values.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValues" }, "example": { "object": "list", "data": [ { "id": "4", "label": "Computer Software" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lookups/seniorities": { "get": { "operationId": "listSeniorities", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "List seniority levels", "description": "Seniority ids. Use the ids in seniority_level_ids and exclude_seniority_level_ids. Free.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Only values whose label contains this text.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Values.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValues" }, "example": { "object": "list", "data": [ { "id": "120", "label": "Senior" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lookups/experience-ranges": { "get": { "operationId": "listExperienceRanges", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "List experience ranges", "description": "Year buckets for total experience and time at the current company. 1 is under a year, 2 is 1 to 2 years, 3 is 3 to 5 years, 4 is 6 to 10 years, 5 is more than 10 years. Use the ids in years_of_experience_ids and years_at_current_company_ids. Free.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Only values whose label contains this text.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Values.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValues" }, "example": { "object": "list", "data": [ { "id": "4", "label": "6 to 10 years" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lookups/functions": { "get": { "operationId": "listFunctions", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "List job functions", "description": "Job function ids. 8 is Engineering. Use the ids in function_ids and exclude_function_ids. Free.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Only values whose label contains this text.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Values.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValues" }, "example": { "object": "list", "data": [ { "id": "8", "label": "Engineering" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lookups/languages": { "get": { "operationId": "listProfileLanguages", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "List profile languages", "description": "Languages a profile is written in. Use the ids in profile_languages. Free.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Only values whose label contains this text.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Values.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValues" }, "example": { "object": "list", "data": [ { "id": "nl", "label": "Dutch" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lookups/headcounts": { "get": { "operationId": "listCompanyHeadcounts", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "List company size ranges", "description": "Current employer headcount. A is self-employed, B is 1-10, C is 11-50, D is 51-200, E is 201-500, F is 501-1,000, G is 1,001-5,000, H is 5,001-10,000, I is 10,001+. Use the ids in company_headcount. Free.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Only values whose label contains this text.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Values.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValues" }, "example": { "object": "list", "data": [ { "id": "D", "label": "51-200" } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/people/search": { "post": { "operationId": "searchPeople", "x-recruitmcp-category": "sourcing", "tags": [ "Search" ], "summary": "Search people", "description": "Profiles for a filter set. limit is how many profiles to return, from 1 to 100, and defaults to 25. cursor continues a previous search: send the next_cursor from the last response. 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.\n\ncompany_headcount is A through I: A self-employed, B 1-10, C 11-50, D 51-200, E 201-500, F 501-1,000, G 1,001-5,000, H 5,001-10,000, I 10,001+. years_of_experience_ids and years_at_current_company_ids are 1 through 5: 1 is under a year, 2 is 1 to 2 years, 3 is 3 to 5 years, 4 is 6 to 10 years, 5 is more than 10 years. seniority_level_ids run from 100 to 320. function_ids run from 1 to 26.\n\ncurrent_companies and past_companies take a company URL or company id from POST /v1/companies:resolve. A bare name is not resolved and does not match.\n\ndata holds at most limit profiles. next_cursor is null when nothing remains. A suppressed person is never returned and never charged: search counts them in omitted.suppressed and keeps filling limit. exclude_seen defaults to false on REST and MCP, so people already in the seen register come back with already_seen true.\n\nOne credit per profile in data, once per workspace. Profiles fetched and not returned are not charged. A later call with cursor returns those cached profiles without asking the index again, and charges them when they are returned. An empty result costs nothing. A profile already billed in this workspace is free.\n\nAn authorized call runs and charges. confirm is deprecated and ignored. dry_run=true previews and charges nothing; dry_run is true, requires_confirm is false, and estimate.credits_max equals limit. The estimate includes balance_credits, sufficient, and warning. sufficient is false when the visible balance is below credits_max, and warning names 402 insufficient_credits. Above the key's approval_threshold_credits the call returns 409 approval_required with an estimate and a confirm_token.\n\nEach search has a time budget of about 20 seconds. When it ends before limit is reached, the response is 200 with partial: true: data holds the profiles that arrived, only those are charged, and next_cursor continues the rest. Several geo_ids are fetched in parallel and interleaved; a place that did not answer in time is continued by next_cursor. Only when nothing arrived is the response 504 gateway_timeout, with nothing charged. The pages asked for keep loading, so the same request after Retry-After usually reads them from cache. Fewer geo_ids per request also finish faster. A known location drops profiles outside that place; they are counted in omitted.outside_geo and not charged. seniority 310 is CXO, and a CXO-only search drops other titles into omitted.seniority without charging them. profile_id is the search id. alternate_id is the other profile id for the same person, and it is null until that person has been enriched. total_elements is an estimate from the index before the location post-filter. omitted.outside_geo counts profiles dropped from pages already read and is not subtracted from total_elements.\n\nScope: `sourcing:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/DryRun" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleSearchRequest" } } } }, "responses": { "200": { "description": "Live response is a PeopleSearchPage. With ?dry_run=true, a PeopleSearchPreview; nothing is charged or sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PeopleSearchPage" }, { "$ref": "#/components/schemas/PeopleSearchPreview" } ] }, "examples": { "live": { "summary": "Live response", "value": { "object": "people_page", "query_key": "qk_backend_london", "total_elements": 128, "data": [ { "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 }, { "profile_id": "lead_3c71e0_2", "full_name": "Jonas Vermeulen", "location": "London, England, United Kingdom", "alternate_id": null, "photo": null, "profile_url": "https://profiles.example.com/jonas-vermeulen", "current_positions": [ { "title": "Platform Engineer", "company_name": "Paperkiln", "company_id": null, "company_url": "https://companies.example.com/paperkiln", "current": true, "description": null, "started_on": { "year": 2025, "month": 11, "text": "2025-11" }, "tenure_at_position": { "numMonths": 11 }, "tenure_at_company": { "numMonths": 11 } } ], "identity_key": "jonas vermeulen|paperkiln", "already_seen": false }, { "profile_id": "lead_5d09b4_3", "full_name": "Lina Dubois", "location": "London, England, United Kingdom", "alternate_id": null, "photo": null, "profile_url": "https://profiles.example.com/lina-dubois", "current_positions": [ { "title": "Backend Engineer", "company_name": "Acme Robotics", "company_id": null, "company_url": "https://companies.example.com/acme-robotics", "current": true, "description": null, "started_on": { "year": 2023, "month": 1, "text": "2023-01" }, "tenure_at_position": { "numYears": 3, "numMonths": 9 }, "tenure_at_company": { "numYears": 3, "numMonths": 9 } } ], "identity_key": "lina dubois|acme robotics", "already_seen": true } ], "next_cursor": "eyJvZmZzZXQiOjN9", "omitted": { "suppressed": 0, "already_seen": 0, "unpaid": 0 }, "applied_filters": [ { "field": "current_job_titles", "effect": "hard_filter", "detail": "Backend Engineer" } ], "ignored_fields": [], "cost": { "credits": 3, "cached_items": 3, "live_items": 0, "upstream_calls": 1 } } }, "dry_run": { "summary": "With dry_run=true", "value": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 10, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "applied_filters": [ { "field": "current_job_titles", "effect": "hard_filter", "detail": "Backend Engineer" } ], "ignored_fields": [], "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } } } } } }, "400": { "description": "`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_filter` (do not retry): skills is not a supported filter. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "value": { "error": { "code": "idempotency_key_required", "message": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_filter": { "summary": "skills is not a supported filter.", "value": { "error": { "code": "unsupported_filter", "message": "skills is not a supported filter.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "field": "skills" } } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "daily_credit_cap_reached": { "summary": "This key's daily credit cap is reached.", "value": { "error": { "code": "daily_credit_cap_reached", "message": "This key's daily credit cap is reached.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "cap": "key", "resets_at": "2026-10-14T00:00:00.000Z" } }, "resets_at": "2026-10-14T00:00:00.000Z" }, "x-retryable": false }, "free_tier_limit": { "summary": "This workspace has used its free upstream allowance.", "value": { "error": { "code": "free_tier_limit", "message": "This workspace has used its free upstream allowance.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "kind": "search_pages", "limit": 60 } } }, "x-retryable": false }, "insufficient_credits": { "summary": "Not enough credits for this operation.", "value": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "required_credits": 25, "balance_credits": 3 } }, "required_credits": 25, "balance_credits": 3 }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "approval_required": { "summary": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "value": { "error": { "code": "approval_required", "message": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "approval_threshold_credits": 500, "credits_max": 25 } }, "estimate": { "credits_min": 0, "credits_max": 25, "requires_confirm": false }, "confirm_token": "v1.payload.sig", "approval_threshold_credits": 500, "cost": { "credits": 0 } }, "x-retryable": false }, "confirm_token_used": { "summary": "This confirm_token was already used. Ask for a new preview to get another.", "value": { "error": { "code": "confirm_token_used", "message": "This confirm_token was already used. Ask for a new preview to get another.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still running. Retry after it finishes.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running. Retry after it finishes.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "idempotency_key_reused": { "summary": "Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded. `upstream_busy` (retry): The profile source is busy. Retry after the delay.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_busy": { "summary": "The profile source is busy. Retry after the delay.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry after the delay.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "502": { "description": "`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.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is busy. Retry shortly.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry shortly.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_error": { "summary": "The profile source returned a response that could not be used. Retry later.", "value": { "error": { "code": "upstream_error", "message": "The profile source returned a response that could not be used. Retry later.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "hint": "retry later" } } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "503": { "description": "`upstream_busy` (retry): The profile source is paused.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is paused.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is paused.", "request_id": "req_01J0REQUEST0EXAMPLE" }, "retry_at": "2026-10-13T15:00:00.000Z" }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "504": { "description": "`gateway_timeout` (retry): The search did not finish in time. Nothing was charged. The index is still loading these results: retry the same request after Retry-After and it reads them from cache. With 4 geo_ids, fewer per request (or one per request) also finishes faster.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "gateway_timeout": { "summary": "The search did not finish in time. Nothing was charged. The index is still loading these results: retry the same request after Retry-After and it reads them from cache. With 4 geo_ids, fewer per request (or one per request) also finishes faster.", "value": { "error": { "code": "gateway_timeout", "message": "The search did not finish in time. Nothing was charged. The index is still loading these results: retry the same request after Retry-After and it reads them from cache. With 4 geo_ids, fewer per request (or one per request) also finishes faster.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "retry_after_seconds": 10, "geo_ids": 4 } } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/people/{profile_id}": { "get": { "operationId": "getPerson", "x-recruitmcp-category": "sourcing", "tags": [ "Profiles" ], "summary": "Get a person from your cache", "description": "Never charges and never calls the person index. Returns 404 not_cached when the person has not been enriched in this workspace within max_age_days; enrich them with POST /v1/people:enrich. profile_id may also be a URL-encoded profile URL.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "max_age_days", "in": "query", "required": false, "description": "Default 30.", "schema": { "type": "integer", "minimum": 1, "maximum": 365 } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "The cached profile.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_cached` (do not retry): This person is not in your cache. Enrich them with POST /v1/people:enrich. `suppressed` (do not retry): This person is suppressed in this workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_cached": { "summary": "This person is not in your cache. Enrich them with POST /v1/people:enrich.", "value": { "error": { "code": "not_cached", "message": "This person is not in your cache. Enrich them with POST /v1/people:enrich.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "suppressed": { "summary": "This person is suppressed in this workspace.", "value": { "error": { "code": "suppressed", "message": "This person is suppressed in this workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "delete": { "operationId": "erasePerson", "x-recruitmcp-category": "sourcing", "tags": [ "Profiles" ], "summary": "Erase a person from this workspace", "description": "Deletes the cached profile, contacts, seen entries, and list items for this person in the workspace. Does not suppress them. POST /v1/erasures with suppress true also blocks future results.\n\nScope: `privacy:write`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "privacy:write" ] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/people:enrich": { "post": { "operationId": "enrichPeople", "x-recruitmcp-category": "sourcing", "tags": [ "Profiles" ], "summary": "Enrich profiles", "description": "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.\n\nPolling example:\n```bash\nKEY=\"\"\ncurl -s -X POST https://api.recruitmcp.com/v1/people:enrich \\\n -H \"Authorization: Bearer $KEY\" -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" -d '{\"ids\":[\"lead_8f2a1c_1\"]}'\n# 202: {\"job_id\":\"job_01J0JOB0EXAMPLE\",\"poll_url\":\"/v1/jobs/job_01J0JOB0EXAMPLE\",\"status\":\"queued\",...}\nuntil curl -s https://api.recruitmcp.com/v1/jobs/job_01J0JOB0EXAMPLE \\\n -H \"Authorization: Bearer $KEY\" | grep -q '\"status\":\"\\(completed\\|failed\\)\"'; do sleep 3; done\ncurl -s https://api.recruitmcp.com/v1/jobs/job_01J0JOB0EXAMPLE -H \"Authorization: Bearer $KEY\"\n# result.data holds the profiles; credits_charged equals result.cost.credits\n```\n\nScope: `sourcing:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/DryRun" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleFetchRequest" } } } }, "responses": { "200": { "description": "200 when everything is already stored: a ProfileList at once. With ?dry_run=true, a Preview; nothing is charged or sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProfileList" }, { "$ref": "#/components/schemas/Preview" } ] }, "examples": { "live": { "summary": "200 when everything is already stored", "value": { "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 } } }, "dry_run": { "summary": "With dry_run=true", "value": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 4, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } } } } } }, "202": { "description": "Live response, usually. The work is queued: the body has job_id, poll_url, and status. Nothing is charged yet. Poll GET /v1/jobs/{job_id} every few seconds until status is completed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "queued": { "summary": "Live response: 202 with job_id and poll_url", "value": { "id": "job_01J0JOB0EXAMPLE", "object": "job", "kind": "people_fetch", "job_id": "job_01J0JOB0EXAMPLE", "status": "queued", "poll_url": "/v1/jobs/job_01J0JOB0EXAMPLE", "credits_charged": 0, "progress": { "done": 0, "total": 1 }, "error": null, "result": null, "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:00Z" } }, "poll_completed": { "summary": "Then poll GET /v1/jobs/{job_id}: completed, with credits_charged", "value": { "id": "job_01J0JOB0EXAMPLE", "object": "job", "kind": "people_fetch", "job_id": "job_01J0JOB0EXAMPLE", "status": "completed", "poll_url": "/v1/jobs/job_01J0JOB0EXAMPLE", "credits_charged": 2, "progress": { "done": 1, "total": 1 }, "error": null, "result": { "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" } ], "not_found": [], "cost": { "credits": 2, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } }, "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:04Z" } } } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "value": { "error": { "code": "idempotency_key_required", "message": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`insufficient_credits` (do not retry): Not enough credits for this operation.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_credits": { "summary": "Not enough credits for this operation.", "value": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "required_credits": 25, "balance_credits": 3 } }, "required_credits": 25, "balance_credits": 3 }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "approval_required": { "summary": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "value": { "error": { "code": "approval_required", "message": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "approval_threshold_credits": 500, "credits_max": 25 } }, "estimate": { "credits_min": 0, "credits_max": 25, "requires_confirm": false }, "confirm_token": "v1.payload.sig", "approval_threshold_credits": 500, "cost": { "credits": 0 } }, "x-retryable": false }, "confirm_token_used": { "summary": "This confirm_token was already used. Ask for a new preview to get another.", "value": { "error": { "code": "confirm_token_used", "message": "This confirm_token was already used. Ask for a new preview to get another.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still running. Retry after it finishes.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running. Retry after it finishes.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "idempotency_key_reused": { "summary": "Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/people:fetch": { "post": { "operationId": "fetchPeople", "x-recruitmcp-category": "sourcing", "deprecated": true, "tags": [ "Profiles" ], "summary": "Fetch full profiles", "description": "Deprecated alias of POST /v1/people:enrich. Same request, same response, and the same credits: a live call usually answers 202 with job_id and poll_url, and you poll GET /v1/jobs/{job_id} until status is completed. Prefer /v1/people:enrich.\n\nScope: `sourcing:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/DryRun" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleFetchRequest" } } } }, "responses": { "200": { "description": "200 when everything is already stored: a ProfileList at once. With ?dry_run=true, a Preview; nothing is charged or sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProfileList" }, { "$ref": "#/components/schemas/Preview" } ] }, "examples": { "live": { "summary": "200 when everything is already stored", "value": { "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 } } }, "dry_run": { "summary": "With dry_run=true", "value": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 4, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } } } } } }, "202": { "description": "Live response, usually. The work is queued: the body has job_id, poll_url, and status. Nothing is charged yet. Poll GET /v1/jobs/{job_id} every few seconds until status is completed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "queued": { "summary": "Live response: 202 with job_id and poll_url", "value": { "id": "job_01J0JOB0EXAMPLE", "object": "job", "kind": "people_fetch", "job_id": "job_01J0JOB0EXAMPLE", "status": "queued", "poll_url": "/v1/jobs/job_01J0JOB0EXAMPLE", "credits_charged": 0, "progress": { "done": 0, "total": 1 }, "error": null, "result": null, "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:00Z" } }, "poll_completed": { "summary": "Then poll GET /v1/jobs/{job_id}: completed, with credits_charged", "value": { "id": "job_01J0JOB0EXAMPLE", "object": "job", "kind": "people_fetch", "job_id": "job_01J0JOB0EXAMPLE", "status": "completed", "poll_url": "/v1/jobs/job_01J0JOB0EXAMPLE", "credits_charged": 2, "progress": { "done": 1, "total": 1 }, "error": null, "result": { "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" } ], "not_found": [], "cost": { "credits": 2, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } }, "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:04Z" } } } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "value": { "error": { "code": "idempotency_key_required", "message": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`insufficient_credits` (do not retry): Not enough credits for this operation.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_credits": { "summary": "Not enough credits for this operation.", "value": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "required_credits": 25, "balance_credits": 3 } }, "required_credits": 25, "balance_credits": 3 }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "approval_required": { "summary": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "value": { "error": { "code": "approval_required", "message": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "approval_threshold_credits": 500, "credits_max": 25 } }, "estimate": { "credits_min": 0, "credits_max": 25, "requires_confirm": false }, "confirm_token": "v1.payload.sig", "approval_threshold_credits": 500, "cost": { "credits": 0 } }, "x-retryable": false }, "confirm_token_used": { "summary": "This confirm_token was already used. Ask for a new preview to get another.", "value": { "error": { "code": "confirm_token_used", "message": "This confirm_token was already used. Ask for a new preview to get another.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still running. Retry after it finishes.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running. Retry after it finishes.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "idempotency_key_reused": { "summary": "Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/people:match": { "post": { "operationId": "matchPerson", "x-recruitmcp-category": "sourcing", "tags": [ "Profiles" ], "summary": "Find one person by name and current company", "description": "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.\n\nScope: `sourcing:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/DryRun" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleMatchRequest" } } } }, "responses": { "200": { "description": "Live response is a PeopleMatch. With ?dry_run=true, a Preview; nothing is charged or sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PeopleMatch" }, { "$ref": "#/components/schemas/Preview" } ] }, "examples": { "live": { "summary": "Live response", "value": { "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 } } }, "dry_run": { "summary": "With dry_run=true", "value": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 1, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } } } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "value": { "error": { "code": "idempotency_key_required", "message": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "daily_credit_cap_reached": { "summary": "This key's daily credit cap is reached.", "value": { "error": { "code": "daily_credit_cap_reached", "message": "This key's daily credit cap is reached.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "cap": "key", "resets_at": "2026-10-14T00:00:00.000Z" } }, "resets_at": "2026-10-14T00:00:00.000Z" }, "x-retryable": false }, "free_tier_limit": { "summary": "This workspace has used its free upstream allowance.", "value": { "error": { "code": "free_tier_limit", "message": "This workspace has used its free upstream allowance.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "kind": "search_pages", "limit": 60 } } }, "x-retryable": false }, "insufficient_credits": { "summary": "Not enough credits for this operation.", "value": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "required_credits": 25, "balance_credits": 3 } }, "required_credits": 25, "balance_credits": 3 }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "approval_required": { "summary": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "value": { "error": { "code": "approval_required", "message": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "approval_threshold_credits": 500, "credits_max": 25 } }, "estimate": { "credits_min": 0, "credits_max": 25, "requires_confirm": false }, "confirm_token": "v1.payload.sig", "approval_threshold_credits": 500, "cost": { "credits": 0 } }, "x-retryable": false }, "confirm_token_used": { "summary": "This confirm_token was already used. Ask for a new preview to get another.", "value": { "error": { "code": "confirm_token_used", "message": "This confirm_token was already used. Ask for a new preview to get another.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still running. Retry after it finishes.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running. Retry after it finishes.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "idempotency_key_reused": { "summary": "Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded. `upstream_busy` (retry): The profile source is busy. Retry after the delay.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_busy": { "summary": "The profile source is busy. Retry after the delay.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry after the delay.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "502": { "description": "`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.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is busy. Retry shortly.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is busy. Retry shortly.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "upstream_error": { "summary": "The profile source returned a response that could not be used. Retry later.", "value": { "error": { "code": "upstream_error", "message": "The profile source returned a response that could not be used. Retry later.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "hint": "retry later" } } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "503": { "description": "`upstream_busy` (retry): The profile source is paused.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_busy": { "summary": "The profile source is paused.", "value": { "error": { "code": "upstream_busy", "message": "The profile source is paused.", "request_id": "req_01J0REQUEST0EXAMPLE" }, "retry_at": "2026-10-13T15:00:00.000Z" }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/people/{profile_id}/contacts": { "get": { "operationId": "getPersonContacts", "x-recruitmcp-category": "contacts", "tags": [ "Contacts" ], "summary": "Get stored contact details", "description": "Free. Only what an earlier lookup found. Each email includes type work or personal when the lookup provided it. best_email and best_phone are the stored pick. contacts:spend can read contacts it paid for. sourcing:read can read them too.\n\nScope: `sourcing:read`. A key with `contacts:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] }, { "oauth2": [ "contacts:spend" ] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Stored contact details.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contacts" } } } }, "400": { "description": "`invalid_id` (do not retry): profile_id is not a valid person id. `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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "summary": "profile_id is not a valid person id.", "value": { "error": { "code": "invalid_id", "message": "profile_id is not a valid person id.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "field": "profile_id" } } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No contacts are stored for this profile.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No contacts are stored for this profile.", "value": { "error": { "code": "not_found", "message": "No contacts are stored for this profile.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "503": { "description": "`contacts_unavailable` (do not retry): Contact lookup is not available on this server. Nothing was looked up and nothing was charged.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contacts_unavailable": { "summary": "Contact lookup is not available on this server. Nothing was looked up and nothing was charged.", "value": { "error": { "code": "contacts_unavailable", "message": "Contact lookup is not available on this server. Nothing was looked up and nothing was charged.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } }, "post": { "operationId": "lookupPersonContacts", "x-recruitmcp-category": "contacts", "tags": [ "Contacts" ], "summary": "Look up email and phone", "description": "Email and phone, with a confidence score. Each email includes type work or personal when the lookup provides it. Each result includes best_email and best_phone. best_email prefers personal, then an unlabeled address, then work. prefer is personal or work and defaults to personal. best_phone prefers a mobile number. The emails and phones lists stay complete. A flagged entry stays in the list with flagged true and flag_reason, and is left out of best_email and best_phone. Charged only when an email or phone is found; a miss is free. The person must be fetched first. The body is always { data, cost }, including one person and a repeat of a stored lookup. A live lookup usually answers 202 with status pending, job_id, and poll_url, and charges nothing yet: cost.credits, charged_this_request, and credits_charged are 0 and X-Credits-Charged is 0. Poll GET /v1/contacts/jobs/{job_id} every few seconds until status is completed, or wait for contacts.completed. The lookup that started the job is charged when it completes, only for people with an email or phone found. The completed poll shows that charge as credits_charged and charged_this_request, the same number as cost.credits and the ledger row, whose request_id is the X-Request-Id of the call that started the lookup. When every person is already stored the lookup answers 200 at once. A 202 also has canonical_id. Replaying the Idempotency-Key after completion returns the completed result and does not charge again. That replay has replayed: true, cost.credits 0 and charged_this_request 0, like every replay. Each person's credits still show what that lookup charged. dry_run in the query or the JSON body previews and never charges, and accepts contacts:spend or sourcing:read. A malformed person id is 400 invalid_id. The reserved id test_miss_0000 always returns not_found, charges 0, and does not call the contact provider. It does not need a fetched profile, and it applies only to contact lookup.\n\nPolling example:\n```bash\nKEY=\"\"\ncurl -s -X POST https://api.recruitmcp.com/v1/people/lead_8f2a1c_1/contacts \\\n -H \"Authorization: Bearer $KEY\" -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" -d '{}'\n# 202: {\"status\":\"pending\",\"job_id\":\"cjob_01J0CJOB0EXAMPLE\",\"poll_url\":\"/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE\",...}\n# Poll until status is completed (pending until then). The wait doubles from 2 s up to 30 s; stop on an error, give up after about 2 minutes.\ndelay=2\nfor i in 1 2 3 4 5 6 7 8; do\n body=$(curl -sS https://api.recruitmcp.com/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE -H \"Authorization: Bearer $KEY\")\n echo \"$body\" | grep -q '\"status\":\"completed\"' && break\n echo \"$body\" | grep -q '\"error\":{' && break\n sleep $delay\n delay=$((delay*2>30?30:delay*2))\ndone\necho \"$body\"\n# data[].contacts.best_email and best_phone; credits_charged and charged_this_request equal cost.credits\n```\n\nScope: `contacts:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:spend" ] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DryRun" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactLookupRequest" }, "example": { "prefer": "personal" } } } }, "responses": { "200": { "description": "200 when everything is already stored: a ContactsLookup at once. With ?dry_run=true, a Preview; nothing is charged or sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactsLookup" }, { "$ref": "#/components/schemas/Preview" } ] }, "examples": { "live": { "summary": "200 when everything is already stored", "value": { "data": [ { "profile_id": "lead_8f2a1c_1", "contacts": { "status": "ready", "emails": [ { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9 } ], "phones": [ { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8 } ], "best_email": { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9, "reason": "only_candidate" }, "best_phone": { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8, "reason": "only_candidate" }, "expires_at": "2026-11-12T09:00:00Z" }, "credits": 25, "cost": { "credits": 25, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } } ], "cost": { "credits": 25, "cached_items": 0, "live_items": 1, "upstream_calls": 1 }, "charged_this_request": 25 } }, "dry_run": { "summary": "With dry_run=true", "value": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 25, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } } } } } }, "202": { "description": "Live response, usually. The work is queued: the body has job_id, poll_url, and status. Nothing is charged yet. Poll GET /v1/contacts/jobs/{job_id} every few seconds until status is completed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsLookup" }, "examples": { "queued": { "summary": "Live response: 202 with job_id and poll_url", "value": { "status": "pending", "request_id": "req_4f1c2a9b7e3d5a60", "job_id": "cjob_01J0CJOB0EXAMPLE", "poll_url": "/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE", "canonical_id": "lead_8f2a1c_1", "data": [ { "profile_id": "lead_8f2a1c_1", "canonical_id": "lead_8f2a1c_1", "contacts": { "status": "pending", "emails": [], "phones": [], "best_email": null, "best_phone": null, "expires_at": null }, "credits": 0 } ], "cost": { "credits": 0 }, "charged_this_request": 0, "credits_charged": 0 } }, "poll_completed": { "summary": "Then poll GET /v1/contacts/jobs/{job_id}: completed, with credits_charged", "value": { "status": "completed", "request_id": "req_4f1c2a9b7e3d5a60", "job_id": "cjob_01J0CJOB0EXAMPLE", "poll_url": "/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE", "canonical_id": "lead_8f2a1c_1", "data": [ { "profile_id": "lead_8f2a1c_1", "canonical_id": "lead_8f2a1c_1", "contacts": { "status": "ready", "emails": [ { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9 } ], "phones": [ { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8 } ], "best_email": { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9, "reason": "only_candidate" }, "best_phone": { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8, "reason": "only_candidate" }, "expires_at": "2026-11-12T09:00:00Z" }, "credits": 25 } ], "cost": { "credits": 25 }, "charged_this_request": 25, "credits_charged": 25 } } } } } }, "400": { "description": "`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_id` (do not retry): profile_id is not a valid person id. `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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "value": { "error": { "code": "idempotency_key_required", "message": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "invalid_id": { "summary": "profile_id is not a valid person id.", "value": { "error": { "code": "invalid_id", "message": "profile_id is not a valid person id.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "field": "profile_id" } } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "daily_credit_cap_reached": { "summary": "This key's daily credit cap is reached.", "value": { "error": { "code": "daily_credit_cap_reached", "message": "This key's daily credit cap is reached.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "cap": "key", "resets_at": "2026-10-14T00:00:00.000Z" } }, "resets_at": "2026-10-14T00:00:00.000Z" }, "x-retryable": false }, "insufficient_credits": { "summary": "Not enough credits for this operation.", "value": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "required_credits": 25, "balance_credits": 3 } }, "required_credits": 25, "balance_credits": 3 }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): Fetch the profile before asking for contacts. `suppressed` (do not retry): This profile is suppressed. Contact lookup is free.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "Fetch the profile before asking for contacts.", "value": { "error": { "code": "not_found", "message": "Fetch the profile before asking for contacts.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "suppressed": { "summary": "This profile is suppressed. Contact lookup is free.", "value": { "error": { "code": "suppressed", "message": "This profile is suppressed. Contact lookup is free.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "approval_required": { "summary": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "value": { "error": { "code": "approval_required", "message": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "approval_threshold_credits": 500, "credits_max": 25 } }, "estimate": { "credits_min": 0, "credits_max": 25, "requires_confirm": false }, "confirm_token": "v1.payload.sig", "approval_threshold_credits": 500, "cost": { "credits": 0 } }, "x-retryable": false }, "confirm_token_used": { "summary": "This confirm_token was already used. Ask for a new preview to get another.", "value": { "error": { "code": "confirm_token_used", "message": "This confirm_token was already used. Ask for a new preview to get another.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still running. Retry after it finishes.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running. Retry after it finishes.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "idempotency_key_reused": { "summary": "Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "503": { "description": "`contacts_unavailable` (do not retry): Contact lookup is not available on this server. Nothing was looked up and nothing was charged. `upstream_busy` (retry): Contact lookups are not configured on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contacts_unavailable": { "summary": "Contact lookup is not available on this server. Nothing was looked up and nothing was charged.", "value": { "error": { "code": "contacts_unavailable", "message": "Contact lookup is not available on this server. Nothing was looked up and nothing was charged.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "upstream_busy": { "summary": "Contact lookups are not configured on this server.", "value": { "error": { "code": "upstream_busy", "message": "Contact lookups are not configured on this server.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } }, "delete": { "operationId": "deletePersonContacts", "x-recruitmcp-category": "contacts", "tags": [ "Contacts" ], "summary": "Delete stored contact details", "description": "Scope: `privacy:write`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "privacy:write" ] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`invalid_id` (do not retry): profile_id is not a valid person id. `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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "summary": "profile_id is not a valid person id.", "value": { "error": { "code": "invalid_id", "message": "profile_id is not a valid person id.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "field": "profile_id" } } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No contacts are stored for this profile.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No contacts are stored for this profile.", "value": { "error": { "code": "not_found", "message": "No contacts are stored for this profile.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/people/contacts:fetch": { "post": { "operationId": "lookupContacts", "x-recruitmcp-category": "contacts", "tags": [ "Contacts" ], "summary": "Look up email and phone for many people", "description": "Email and phone, with a confidence score, for up to 100 fetched people. Each email includes type work or personal when the lookup provides it. Each result includes best_email and best_phone. best_email prefers personal, then an unlabeled address, then work. prefer is personal or work and defaults to personal. best_phone prefers a mobile number. The emails and phones lists stay complete. A flagged entry stays in the list with flagged true and flag_reason, and is left out of best_email and best_phone. Same pricing and the same { data, cost } body as the single lookup, including a repeat of a stored lookup. A live lookup usually answers 202 with status pending, job_id, and poll_url, and charges nothing yet: cost.credits, charged_this_request, and credits_charged are 0 and X-Credits-Charged is 0. Poll GET /v1/contacts/jobs/{job_id} every few seconds until status is completed, or wait for contacts.completed. The lookup that started the job is charged when it completes, only for people with an email or phone found. The completed poll shows that charge as credits_charged and charged_this_request, the same number as cost.credits and the ledger row, whose request_id is the X-Request-Id of the call that started the lookup. When every person is already stored the lookup answers 200 at once. A 202 also has canonical_id on each person. Replaying the Idempotency-Key after completion returns the completed result and does not charge again. That replay has replayed: true, cost.credits 0 and charged_this_request 0, like every replay. Each person's credits still show what that lookup charged. dry_run in the query or the JSON body previews and never charges, and accepts contacts:spend or sourcing:read. A malformed person id is 400 invalid_id. The reserved id test_miss_0000 always returns not_found, charges 0, and does not call the contact provider. It does not need a fetched profile, and it applies only to contact lookup.\n\nPolling example:\n```bash\nKEY=\"\"\ncurl -s -X POST https://api.recruitmcp.com/v1/people/contacts:fetch \\\n -H \"Authorization: Bearer $KEY\" -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" -d '{\"profile_ids\":[\"lead_8f2a1c_1\"]}'\n# 202: {\"status\":\"pending\",\"job_id\":\"cjob_01J0CJOB0EXAMPLE\",\"poll_url\":\"/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE\",...}\n# Poll until status is completed (pending until then). The wait doubles from 2 s up to 30 s; stop on an error, give up after about 2 minutes.\ndelay=2\nfor i in 1 2 3 4 5 6 7 8; do\n body=$(curl -sS https://api.recruitmcp.com/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE -H \"Authorization: Bearer $KEY\")\n echo \"$body\" | grep -q '\"status\":\"completed\"' && break\n echo \"$body\" | grep -q '\"error\":{' && break\n sleep $delay\n delay=$((delay*2>30?30:delay*2))\ndone\necho \"$body\"\n# data[].contacts.best_email and best_phone; credits_charged and charged_this_request equal cost.credits\n```\n\nScope: `contacts:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/DryRun" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsFetchRequest" } } } }, "responses": { "200": { "description": "200 when everything is already stored: a ContactsLookup at once. With ?dry_run=true, a Preview; nothing is charged or sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactsLookup" }, { "$ref": "#/components/schemas/Preview" } ] }, "examples": { "live": { "summary": "200 when everything is already stored", "value": { "data": [ { "profile_id": "lead_8f2a1c_1", "contacts": { "status": "ready", "emails": [ { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9 } ], "phones": [ { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8 } ], "best_email": { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9, "reason": "only_candidate" }, "best_phone": { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8, "reason": "only_candidate" }, "expires_at": "2026-11-12T09:00:00Z" }, "credits": 25, "cost": { "credits": 25, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } } ], "cost": { "credits": 25, "cached_items": 0, "live_items": 1, "upstream_calls": 1 }, "charged_this_request": 25 } }, "dry_run": { "summary": "With dry_run=true", "value": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 25, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } } } } } }, "202": { "description": "Live response, usually. The work is queued: the body has job_id, poll_url, and status. Nothing is charged yet. Poll GET /v1/contacts/jobs/{job_id} every few seconds until status is completed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Credits-Charged": { "$ref": "#/components/headers/CreditsCharged" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsLookup" }, "examples": { "queued": { "summary": "Live response: 202 with job_id and poll_url", "value": { "status": "pending", "request_id": "req_4f1c2a9b7e3d5a60", "job_id": "cjob_01J0CJOB0EXAMPLE", "poll_url": "/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE", "canonical_id": "lead_8f2a1c_1", "data": [ { "profile_id": "lead_8f2a1c_1", "canonical_id": "lead_8f2a1c_1", "contacts": { "status": "pending", "emails": [], "phones": [], "best_email": null, "best_phone": null, "expires_at": null }, "credits": 0 } ], "cost": { "credits": 0 }, "charged_this_request": 0, "credits_charged": 0 } }, "poll_completed": { "summary": "Then poll GET /v1/contacts/jobs/{job_id}: completed, with credits_charged", "value": { "status": "completed", "request_id": "req_4f1c2a9b7e3d5a60", "job_id": "cjob_01J0CJOB0EXAMPLE", "poll_url": "/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE", "canonical_id": "lead_8f2a1c_1", "data": [ { "profile_id": "lead_8f2a1c_1", "canonical_id": "lead_8f2a1c_1", "contacts": { "status": "ready", "emails": [ { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9 } ], "phones": [ { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8 } ], "best_email": { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9, "reason": "only_candidate" }, "best_phone": { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8, "reason": "only_candidate" }, "expires_at": "2026-11-12T09:00:00Z" }, "credits": 25 } ], "cost": { "credits": 25 }, "charged_this_request": 25, "credits_charged": 25 } } } } } }, "400": { "description": "`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_id` (do not retry): profile_id is not a valid person id. `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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "value": { "error": { "code": "idempotency_key_required", "message": "This route spends credits or sends a message. Send an Idempotency-Key header, or dry_run=true for a preview.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "invalid_id": { "summary": "profile_id is not a valid person id.", "value": { "error": { "code": "invalid_id", "message": "profile_id is not a valid person id.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "field": "profile_id" } } }, "x-retryable": false }, "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "402": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "daily_credit_cap_reached": { "summary": "This key's daily credit cap is reached.", "value": { "error": { "code": "daily_credit_cap_reached", "message": "This key's daily credit cap is reached.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "cap": "key", "resets_at": "2026-10-14T00:00:00.000Z" } }, "resets_at": "2026-10-14T00:00:00.000Z" }, "x-retryable": false }, "insufficient_credits": { "summary": "Not enough credits for this operation.", "value": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "required_credits": 25, "balance_credits": 3 } }, "required_credits": 25, "balance_credits": 3 }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): Fetch the profile before asking for contacts. `suppressed` (do not retry): This profile is suppressed. Contact lookup is free.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "Fetch the profile before asking for contacts.", "value": { "error": { "code": "not_found", "message": "Fetch the profile before asking for contacts.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "suppressed": { "summary": "This profile is suppressed. Contact lookup is free.", "value": { "error": { "code": "suppressed", "message": "This profile is suppressed. Contact lookup is free.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "approval_required": { "summary": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "value": { "error": { "code": "approval_required", "message": "This call is above the key's approval threshold. Nothing was charged. Send confirm_token to run it.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "approval_threshold_credits": 500, "credits_max": 25 } }, "estimate": { "credits_min": 0, "credits_max": 25, "requires_confirm": false }, "confirm_token": "v1.payload.sig", "approval_threshold_credits": 500, "cost": { "credits": 0 } }, "x-retryable": false }, "confirm_token_used": { "summary": "This confirm_token was already used. Ask for a new preview to get another.", "value": { "error": { "code": "confirm_token_used", "message": "This confirm_token was already used. Ask for a new preview to get another.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still running. Retry after it finishes.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running. Retry after it finishes.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true }, "idempotency_key_reused": { "summary": "Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "503": { "description": "`contacts_unavailable` (do not retry): Contact lookup is not available on this server. Nothing was looked up and nothing was charged. `upstream_busy` (retry): Contact lookups are not configured on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contacts_unavailable": { "summary": "Contact lookup is not available on this server. Nothing was looked up and nothing was charged.", "value": { "error": { "code": "contacts_unavailable", "message": "Contact lookup is not available on this server. Nothing was looked up and nothing was charged.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "upstream_busy": { "summary": "Contact lookups are not configured on this server.", "value": { "error": { "code": "upstream_busy", "message": "Contact lookups are not configured on this server.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/contacts/jobs/{job_id}": { "get": { "operationId": "getContactJob", "x-recruitmcp-category": "contacts", "tags": [ "Contacts" ], "summary": "Get a contact lookup", "description": "Free. Poll the job_id from a contact lookup that returned HTTP 202, every few seconds, until status is completed. Requires contacts:spend. status is pending until every person is stored, then completed with the emails, phones, best_email, and best_phone. cost.credits, credits_charged, and each person's credits are the credits that job charged, read from the ledger. While the job is pending they are all 0. charged_this_request is 0 while pending; once completed it is the same number as credits_charged, because the lookup that started the job is charged when the job completes. The poll itself never charges: X-Credits-Charged is 0 and polling again charges nothing more. An idempotent replay of the original lookup has charged_this_request 0 and cost.credits 0.\n\nPolling example:\n```bash\nKEY=\"\"\ncurl -s -X POST https://api.recruitmcp.com/v1/people/contacts:fetch \\\n -H \"Authorization: Bearer $KEY\" -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" -d '{\"profile_ids\":[\"lead_8f2a1c_1\"]}'\n# 202: {\"status\":\"pending\",\"job_id\":\"cjob_01J0CJOB0EXAMPLE\",\"poll_url\":\"/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE\",...}\n# Poll until status is completed (pending until then). The wait doubles from 2 s up to 30 s; stop on an error, give up after about 2 minutes.\ndelay=2\nfor i in 1 2 3 4 5 6 7 8; do\n body=$(curl -sS https://api.recruitmcp.com/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE -H \"Authorization: Bearer $KEY\")\n echo \"$body\" | grep -q '\"status\":\"completed\"' && break\n echo \"$body\" | grep -q '\"error\":{' && break\n sleep $delay\n delay=$((delay*2>30?30:delay*2))\ndone\necho \"$body\"\n# data[].contacts.best_email and best_phone; credits_charged and charged_this_request equal cost.credits\n```\n\nScope: `contacts:spend`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:spend" ] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "example": "cjob_01J0CJOB0EXAMPLE" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "The lookup, pending or completed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsLookup" }, "examples": { "completed": { "summary": "Completed", "value": { "status": "completed", "request_id": "req_4f1c2a9b7e3d5a60", "job_id": "cjob_01J0CJOB0EXAMPLE", "poll_url": "/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE", "canonical_id": "lead_8f2a1c_1", "data": [ { "profile_id": "lead_8f2a1c_1", "canonical_id": "lead_8f2a1c_1", "contacts": { "status": "ready", "emails": [ { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9 } ], "phones": [ { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8 } ], "best_email": { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9, "reason": "only_candidate" }, "best_phone": { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8, "reason": "only_candidate" }, "expires_at": "2026-11-12T09:00:00Z" }, "credits": 25 } ], "cost": { "credits": 25 }, "charged_this_request": 25, "credits_charged": 25 } }, "pending": { "summary": "Pending", "value": { "status": "pending", "request_id": "req_4f1c2a9b7e3d5a60", "job_id": "cjob_01J0CJOB0EXAMPLE", "poll_url": "/v1/contacts/jobs/cjob_01J0CJOB0EXAMPLE", "canonical_id": "lead_8f2a1c_1", "data": [ { "profile_id": "lead_8f2a1c_1", "canonical_id": "lead_8f2a1c_1", "contacts": { "status": "pending", "emails": [], "phones": [], "best_email": null, "best_phone": null, "expires_at": null }, "credits": 0 } ], "cost": { "credits": 0 }, "charged_this_request": 0, "credits_charged": 0 } } } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/jobs": { "get": { "operationId": "listJobs", "x-recruitmcp-category": "sourcing", "tags": [ "Profiles" ], "summary": "List profile fetch jobs", "description": "Scope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only jobs in this status.", "schema": { "type": "string", "enum": [ "queued", "running", "parked", "completed", "failed" ] } }, { "name": "created_after", "in": "query", "required": false, "description": "Only rows created after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Only rows created before this time.", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Jobs, newest first.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/jobs/{job_id}": { "get": { "operationId": "getJob", "x-recruitmcp-category": "sourcing", "tags": [ "Profiles" ], "summary": "Get a job", "description": "Free. Poll the job_id from POST /v1/people:enrich that returned HTTP 202, every few seconds, until status is completed or failed. When the job is completed, result.data holds the profiles and credits_charged is what the ledger charged for the job, the same number as result.cost.credits. It is 0 until then. The call that queued the job is charged when it completes; this poll never charges. view defaults to full, the same profile enrich returns, including education. view=compact is the short profile.\n\nPolling example:\n```bash\nKEY=\"\"\ncurl -s -X POST https://api.recruitmcp.com/v1/people:enrich \\\n -H \"Authorization: Bearer $KEY\" -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" -d '{\"ids\":[\"lead_8f2a1c_1\"]}'\n# 202: {\"job_id\":\"job_01J0JOB0EXAMPLE\",\"poll_url\":\"/v1/jobs/job_01J0JOB0EXAMPLE\",\"status\":\"queued\",...}\nuntil curl -s https://api.recruitmcp.com/v1/jobs/job_01J0JOB0EXAMPLE \\\n -H \"Authorization: Bearer $KEY\" | grep -q '\"status\":\"\\(completed\\|failed\\)\"'; do sleep 3; done\ncurl -s https://api.recruitmcp.com/v1/jobs/job_01J0JOB0EXAMPLE -H \"Authorization: Bearer $KEY\"\n# result.data holds the profiles; credits_charged equals result.cost.credits\n```\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "full is the default and includes education and experience. compact is the short profile.", "schema": { "type": "string", "enum": [ "full", "compact" ] } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "The job, with profiles once completed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "completed": { "summary": "Completed", "value": { "id": "job_01J0JOB0EXAMPLE", "object": "job", "kind": "people_fetch", "job_id": "job_01J0JOB0EXAMPLE", "status": "completed", "poll_url": "/v1/jobs/job_01J0JOB0EXAMPLE", "credits_charged": 2, "progress": { "done": 1, "total": 1 }, "error": null, "result": { "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" } ], "not_found": [], "cost": { "credits": 2, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } }, "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:04Z" } }, "pending": { "summary": "Queued", "value": { "id": "job_01J0JOB0EXAMPLE", "object": "job", "kind": "people_fetch", "job_id": "job_01J0JOB0EXAMPLE", "status": "queued", "poll_url": "/v1/jobs/job_01J0JOB0EXAMPLE", "credits_charged": 0, "progress": { "done": 0, "total": 1 }, "error": null, "result": null, "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:00Z" } } } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/media/{token}": { "get": { "operationId": "getMedia", "x-recruitmcp-category": "sourcing", "tags": [ "Account" ], "summary": "Get a profile photo", "description": "Public. The token in a profile photo field expires after 7 days, and each API response signs a new one. It is not tied to a workspace and does not contain the original address. Requests are limited per network. The image is cached on this server and the response is private for one day. Erasure and a confirmed opt-out delete that person's cached photo; every token for them then returns 404.\n\nNo authentication.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The profile photo.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): Photo not found.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "Photo not found.", "value": { "error": { "code": "not_found", "message": "Photo not found.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "502": { "description": "`upstream_error` (retry): The photo could not be loaded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_error": { "summary": "The photo could not be loaded.", "value": { "error": { "code": "upstream_error", "message": "The photo could not be loaded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/seen": { "get": { "operationId": "listSeen", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "List the seen register", "description": "Everyone this workspace has seen, shortlisted, contacted, or rejected. A people search marks them already_seen, and drops them when exclude_seen is true.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only entries with this status.", "schema": { "type": "string", "enum": [ "seen", "shortlisted", "contacted", "rejected", "do_not_contact" ] } }, { "name": "tag", "in": "query", "required": false, "description": "Only entries with this tag.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Entries, most recently updated first.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeenList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "post": { "operationId": "upsertSeen", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Add or update seen entries", "description": "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.\n\nScope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/SeenEntryInput" }, "maxItems": 1000 } }, "required": [ "entries" ] }, "example": { "entries": [ { "profile_id": "lead_8f2a1c_1", "status": "shortlisted", "tags": [ "backend-berlin" ], "external_ids": { "ats": "cand_123" } } ] } } } }, "responses": { "200": { "description": "The stored entries.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeenList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/seen:check": { "post": { "operationId": "checkSeen", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Check people against the seen register", "description": "Up to 1000 identities, each a profile_url, profile_id, or full_name with current_employer. Free.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "profile_url": { "type": "string" }, "profile_id": { "type": "string" }, "full_name": { "type": "string" }, "current_employer": { "type": "string" } } }, "maxItems": 1000 } }, "required": [ "identities" ] }, "example": { "identities": [ { "full_name": "Ada Peeters", "current_employer": "Acme" } ] } } } }, "responses": { "200": { "description": "One result per identity, in order.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeenCheck" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/seen/{seen_id}": { "get": { "operationId": "getSeenEntry", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Get a seen entry", "description": "Scope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "seen_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "The entry.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeenEntry" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "patch": { "operationId": "updateSeenEntry", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Update a seen entry", "description": "external_ids are merged; tags replace the stored tags.\n\nScope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "name": "seen_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "seen", "shortlisted", "contacted", "rejected", "do_not_contact" ] }, "note": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "external_ids": { "type": "object", "additionalProperties": { "type": "string" } } } }, "example": { "status": "rejected", "note": "Not open to relocation." } } } }, "responses": { "200": { "description": "Updated.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeenEntry" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "delete": { "operationId": "deleteSeenEntry", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Remove a seen entry", "description": "The person can be returned by a later search. exclude_seen no longer drops them.\n\nScope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "name": "seen_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lists": { "get": { "operationId": "listLists", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "List candidate lists", "description": "Scope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Lists, newest first.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lists" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "post": { "operationId": "createList", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Create a candidate list", "description": "Scope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItemInput" } } }, "required": [ "name" ] }, "example": { "name": "Backend Berlin shortlist", "items": [ { "profile_id": "lead_8f2a1c_1", "note": "Strong Go background" } ] } } } }, "responses": { "201": { "description": "Created.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lists/{list_id}": { "get": { "operationId": "getList", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Get a list", "description": "Scope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "The list.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "patch": { "operationId": "updateList", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Rename or describe a list", "description": "Scope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Updated.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "delete": { "operationId": "deleteList", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Delete a list", "description": "Scope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lists/{list_id}/items": { "get": { "operationId": "listListItems", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "List the people on a list", "description": "Scope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Items in the order they were added.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListItems" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "post": { "operationId": "addListItems", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Add people to a list", "description": "People already on the list are skipped. The search id and the other profile id are the same person and are stored once, under the search id.\n\nScope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItemInput" } } }, "required": [ "items" ] }, "example": { "items": [ { "profile_id": "lead_8f2a1c_1" } ] } } } }, "responses": { "200": { "description": "The items that were added.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListItems" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lists/{list_id}/items/{item_id}": { "delete": { "operationId": "removeListItem", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Remove a person from a list", "description": "Scope: `lists:write`. A key with `sourcing:spend` is also accepted.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] }, { "oauth2": [ "sourcing:spend" ] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/lists/{list_id}/export": { "get": { "operationId": "exportList", "x-recruitmcp-category": "sourcing", "tags": [ "Lists" ], "summary": "Export a list as CSV", "description": "One row per person. An empty email is filled from a contact lookup that found one. An opted-out address is left blank, and a suppressed person is omitted. The photo column is this API's media URL.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "CSV with one row per person. Email comes from stored contacts when a lookup found one. Photo is a /v1/media URL.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "text/csv": { "schema": { "type": "string", "description": "CSV with a header row." } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/erasures": { "post": { "operationId": "createErasure", "x-recruitmcp-category": "sourcing", "tags": [ "Privacy" ], "summary": "Erase a person and suppress them", "description": "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 or contact lookup.\n\nScope: `privacy:write`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "privacy:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_id": { "type": "string" }, "profile_url": { "type": "string" }, "suppress": { "type": "boolean", "description": "Default true." } } }, "example": { "profile_id": "lead_8f2a1c_1" } } } }, "responses": { "200": { "description": "What was erased.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erasure" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/suppressions": { "get": { "operationId": "listSuppressions", "x-recruitmcp-category": "sourcing", "tags": [ "Privacy" ], "summary": "List suppressions", "description": "Hashes only. Suppressions always apply to search.\n\nScope: `sourcing:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "sourcing:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Suppressions, newest first.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "post": { "operationId": "createSuppression", "x-recruitmcp-category": "sourcing", "tags": [ "Privacy" ], "summary": "Suppress a person", "description": "Blocks this person from search, runs, lists, and contact lookups 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.\n\nScope: `privacy:write`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "privacy:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_url": { "type": "string" }, "company_url": { "type": "string" }, "email": { "type": "string" }, "full_name": { "type": "string" }, "company": { "type": "string" } } }, "example": { "full_name": "Ada Peeters", "company": "Acme Robotics" } } } }, "responses": { "200": { "description": "The suppressions written.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/suppressions/{suppression_id}": { "delete": { "operationId": "deleteSuppression", "x-recruitmcp-category": "sourcing", "tags": [ "Privacy" ], "summary": "Lift a suppression", "description": "Opt-outs the person filed themselves cannot be lifted.\n\nScope: `privacy:write`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "privacy:write" ] } ], "parameters": [ { "name": "suppression_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/privacy/cache": { "delete": { "operationId": "deleteCaches", "x-recruitmcp-category": "sourcing", "tags": [ "Privacy" ], "summary": "Delete cached profiles, pages, and contact details", "description": "Deletes every cached profile, cached search page, and stored contact detail in this workspace. It cannot be undone, and the next search, fetch, or contact lookup pays again. `?dry_run=true` returns what would be deleted and deletes nothing. Executing needs `?confirm_delete=true`; without it the call is 400 confirmation_required and nothing is deleted.\n\nScope: `privacy:write`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "privacy:write" ] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "Preview only. Nothing is deleted.", "schema": { "type": "boolean" } }, { "name": "confirm_delete", "in": "query", "required": false, "description": "Required to delete. Without it nothing is deleted.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Dry run: what would be deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheDeletionPreview" } } } }, "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/privacy/opt-out": { "post": { "operationId": "requestOptOut", "x-recruitmcp-category": "sourcing", "tags": [ "Privacy" ], "summary": "Opt out (for the person themselves)", "description": "Anyone can ask to be removed. A confirmation link is emailed; once confirmed, the person is suppressed for every workspace.\n\nNo authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_url": { "type": "string" }, "email": { "type": "string" }, "contact_email": { "type": "string", "description": "Where to send the confirmation link, when email is not given." } } } } } }, "responses": { "202": { "description": "Confirmation sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOut" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "503": { "description": "`internal` (do not retry): Opt-out requests are not available on this server yet.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Opt-out requests are not available on this server yet.", "value": { "error": { "code": "internal", "message": "Opt-out requests are not available on this server yet.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/privacy/opt-out/confirm": { "get": { "operationId": "confirmOptOut", "x-recruitmcp-category": "sourcing", "tags": [ "Privacy" ], "summary": "Confirm an opt-out", "description": "No authentication.", "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "Token from the confirmation email.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOut" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Too many requests from this network. Try again later.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Too many requests from this network. Try again later.", "value": { "error": { "code": "rate_limited", "message": "Too many requests from this network. Try again later.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "503": { "description": "`internal` (do not retry): Opt-out requests are not available on this server yet.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Opt-out requests are not available on this server yet.", "value": { "error": { "code": "internal", "message": "Opt-out requests are not available on this server yet.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } } } }, "/v1/events": { "get": { "operationId": "listEvents", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "List events", "description": "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.\n\nScope: `account:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "One event type. Same filter as types.", "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "description": "Event types, comma separated. Default all.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "customer_id", "in": "query", "required": false, "description": "Only events from this customer. Use none for account-level events.", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "required": false, "description": "Only events after this time.", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "Events, newest first.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/events/{event_id}": { "get": { "operationId": "getEvent", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Get an event", "description": "Scope: `account:read`.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/Customer" } ], "responses": { "200": { "description": "The event.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This customer is disabled.", "value": { "error": { "code": "forbidden", "message": "This customer is disabled.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "List webhook endpoints", "description": "Scope: `account:read`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Endpoints.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "post": { "operationId": "createWebhookEndpoint", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Add a webhook endpoint", "description": "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=,v1=.\" 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.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" } } } }, "responses": { "201": { "description": "Created. The signing secret is shown once.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "409": { "description": "`conflict` (do not retry): The resource is in a state that refuses this change.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "summary": "The resource is in a state that refuses this change.", "value": { "error": { "code": "conflict", "message": "The resource is in a state that refuses this change.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/webhook-endpoints/{endpoint_id}": { "get": { "operationId": "getWebhookEndpoint", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Get a webhook endpoint", "description": "Scope: `account:read`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:read" ] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "The endpoint.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "patch": { "operationId": "updateWebhookEndpoint", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Update a webhook endpoint", "description": "Scope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" }, "example": { "status": "disabled" } } } }, "responses": { "200": { "description": "Updated.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Delete a webhook endpoint", "description": "Scope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Rotate an endpoint's signing secret", "description": "The old secret stops working immediately.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "The new secret, shown once.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/test": { "post": { "operationId": "testWebhookEndpoint", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Send a test event", "description": "Sends one signed ping event now and reports the answer. Not retried.\n\nScope: `account:manage`. Acts on the account; keys bound to a customer are refused.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "account:manage" ] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "What the endpoint answered.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" } } } }, "400": { "description": "`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.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "A field is missing or has a value this endpoint does not accept.", "value": { "error": { "code": "invalid_request", "message": "A field is missing or has a value this endpoint does not accept.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "unsupported_version": { "summary": "RecruitMCP-Version is not a supported version.", "value": { "error": { "code": "unsupported_version", "message": "RecruitMCP-Version is not a supported version.", "request_id": "req_01J0REQUEST0EXAMPLE", "details": { "supported": [ "2026-10-13" ] } } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "`unauthorized` (do not retry): Missing bearer API key.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing bearer API key.", "value": { "error": { "code": "unauthorized", "message": "Missing bearer API key.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "403": { "description": "`forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "This route acts on the account. Keys bound to a customer cannot use it.", "value": { "error": { "code": "forbidden", "message": "This route acts on the account. Keys bound to a customer cannot use it.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false }, "insufficient_scope": { "summary": "This key does not include the scope this endpoint requires.", "value": { "error": { "code": "insufficient_scope", "message": "This key does not include the scope this endpoint requires.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "description": "`not_found` (do not retry): No record with this id exists in the workspace.", "x-retryable": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "No record with this id exists in the workspace.", "value": { "error": { "code": "not_found", "message": "No record with this id exists in the workspace.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": false } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "description": "`rate_limited` (retry): Per-key rate limit exceeded.", "x-retryable": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Per-key rate limit exceeded.", "value": { "error": { "code": "rate_limited", "message": "Per-key rate limit exceeded.", "request_id": "req_01J0REQUEST0EXAMPLE" } }, "x-retryable": true } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } } } } }, "webhooks": { "event": { "post": { "operationId": "receiveEvent", "x-recruitmcp-category": "account", "tags": [ "Events" ], "summary": "Event delivered to your webhook endpoint", "description": "Verify X-RecruitMCP-Signature before trusting the body. Answer 2xx within 5 seconds; failed deliveries are retried with backoff.", "parameters": [ { "name": "X-RecruitMCP-Signature", "in": "header", "required": true, "schema": { "type": "string", "description": "t=,v1=" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Received." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (rmcp_live_…) or an OAuth access token (rmcp_oat_…). The same key works on the MCP server at https://mcp.recruitmcp.com/mcp." }, "oauth2": { "type": "oauth2", "description": "Authorization code with PKCE (S256). Clients register at /oauth/register.", "flows": { "authorizationCode": { "authorizationUrl": "https://recruitmcp.com/oauth/authorize", "tokenUrl": "https://recruitmcp.com/oauth/token", "refreshUrl": "https://recruitmcp.com/oauth/token", "scopes": { "sourcing:read": "Read searches, people already fetched, the seen register, lists, and free lookups.", "sourcing:spend": "Run searches, fetch and match people, and resolve companies. Spends credits. Also accepted on lists and the seen register.", "lists:write": "Write lists and the seen register (candidate status). Does not spend credits. A key with sourcing:spend is also accepted.", "contacts:spend": "Look up email and phone, with a confidence score, for fetched people. Each email includes type work or personal when the lookup provides it. A dry run of a contact lookup and reading stored contacts are included. Spends credits when a contact is found.", "outreach:read": "Outreach: enabled per workspace.", "outreach:write": "Outreach: enabled per workspace.", "outreach:send": "Outreach: enabled per workspace.", "outreach:approve": "Outreach: enabled per workspace.", "privacy:write": "Erase people, manage suppressions, and delete caches and contact data.", "account:read": "Read the workspace, balance, usage, events, keys, customers, and webhook endpoints.", "account:manage": "Create and revoke keys, customers, and webhook endpoints.", "billing:manage": "Start checkouts and change the subscription plan." } } } } }, "parameters": { "Limit": { "name": "limit", "in": "query", "description": "How many items to return. Default 25, at most 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Cursor": { "name": "cursor", "in": "query", "description": "next_cursor from the previous response. An invalid cursor is 400 invalid_request, message Invalid cursor.", "schema": { "type": "string" } }, "DryRun": { "name": "dry_run", "in": "query", "description": "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.", "schema": { "type": "boolean", "default": false } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "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.", "schema": { "type": "string", "maxLength": 128 } }, "IdempotencyKeyOptional": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this route. At most 128 characters. When present, the same key and body replays the first response for 24 hours. A different body is 409 idempotency_key_reused. A second call waits for the first and replays it. Omit the header to run the request normally.", "schema": { "type": "string", "maxLength": 128 } }, "Version": { "name": "RecruitMCP-Version", "in": "header", "description": "API version. Defaults to the version the key was created with. Supported: 2026-10-13.", "schema": { "type": "string", "enum": [ "2026-10-13" ] } }, "Customer": { "name": "RecruitMCP-Customer", "in": "header", "description": "Act inside this customer (cus_…). Ignored for keys bound to a customer, which always act inside theirs.", "schema": { "type": "string" } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window ends.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying a 429.", "schema": { "type": "integer" } }, "CreditsCharged": { "description": "Credits charged by this response. 0 on a dry run, a replay, a miss, or a queued enrich (202). The charge happens when the job completes.", "schema": { "type": "integer" } } }, "schemas": { "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "api_key" ] }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string" }, "kind": { "type": "string", "enum": [ "secret", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "sourcing:read", "sourcing:spend", "lists:write", "contacts:spend", "outreach:read", "outreach:write", "outreach:send", "outreach:approve", "privacy:write", "account:read", "account:manage", "billing:manage" ] } }, "customer_id": { "type": [ "string", "null" ], "description": "Keys bound to a customer always act inside it." }, "daily_cap_credits": { "type": [ "integer", "null" ] }, "approval_threshold_credits": { "type": [ "integer", "null" ], "description": "Null when unset. HTTP then has no threshold. MCP uses 500 credits." }, "approval_threshold_enrollments": { "type": [ "integer", "null" ], "description": "Null when unset. HTTP then has no enrollment threshold. MCP uses 25 scheduled enrollments." }, "api_version": { "type": "string", "description": "Pinned RecruitMCP-Version." }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "object", "prefix", "scopes", "created_at" ], "example": { "id": "key_1a2b3c4d5e6f7a8b9c", "object": "api_key", "name": "n8n production", "prefix": "rmcp_live_ab12", "kind": "secret", "scopes": [ "sourcing:read", "sourcing:spend" ], "customer_id": null, "daily_cap_credits": 50, "approval_threshold_credits": null, "approval_threshold_enrollments": null, "api_version": "2026-10-13", "created_at": "2026-10-13T09:00:00Z", "last_used_at": null, "expires_at": null } }, "ApiKeyCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "api_key": { "type": "string", "description": "The secret. Shown once." } }, "required": [ "api_key" ] } ] }, "ApiKeyList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "AppliedFilter": { "type": "object", "properties": { "field": { "type": "string" }, "effect": { "type": "string", "enum": [ "hard_filter", "search_order", "exclusion", "result_filter" ] }, "detail": { "type": "string" } }, "required": [ "field", "effect", "detail" ] }, "Area": { "type": "object", "properties": { "geo_ids": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "note": { "type": "string", "description": "Which anchors and cities became geo_ids. The search index has no radius, so geo_ids is the whole location filter. Under 20 km only the anchor city is used. At 20 km or more, major cities near the anchors are added, at most 12 geo ids. Says so when no place matched." }, "hint": { "type": "string", "description": "Set when an anchor has no city id. The country is not copied into geo_ids." }, "fallback": { "type": "string", "enum": [ "country" ], "description": "country when the only match was a country." }, "cost": { "type": "object", "properties": { "credits": { "type": "integer", "description": "Credits charged by this call. Always 0: area lookups are free." } }, "required": [ "credits" ], "example": { "credits": 0 } } }, "required": [ "geo_ids", "next_cursor", "has_more" ], "example": { "geo_ids": [ "90009496" ], "entries": [ { "geo_id": "90009496", "title": "London Area, United Kingdom", "is_area": true } ], "next_cursor": null, "has_more": false, "note": "The search index has no radius. Pass these geo ids as the location filter. Major cities within 30 km are included, at most 12 geo ids.", "cost": { "credits": 0 } } }, "AutoRefill": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "auto_refill" ] }, "enabled": { "type": "boolean" }, "threshold_credits": { "type": [ "integer", "null" ], "description": "Refill when the balance is below this. Null until it is set." }, "max_refills_per_month": { "type": [ "integer", "null" ], "description": "Maximum charges in a UTC month." }, "max_eur_per_month": { "type": [ "integer", "null" ], "description": "Euro cap for a UTC month." }, "card_on_file": { "type": "boolean", "description": "True after a pack checkout saves a card." }, "refills_this_month": { "type": "integer", "description": "Succeeded refills this UTC month. An in-flight charge is not counted until it is granted." }, "amount_eur_this_month": { "type": "integer" }, "disabled_reason": { "type": [ "string", "null" ], "description": "Why a failed charge turned auto-refill off." } }, "required": [ "object", "enabled", "card_on_file", "refills_this_month", "amount_eur_this_month" ], "example": { "object": "auto_refill", "enabled": true, "threshold_credits": 200, "max_refills_per_month": 3, "max_eur_per_month": 297, "card_on_file": true, "refills_this_month": 0, "amount_eur_this_month": 0, "disabled_reason": null } }, "AutoRefillInput": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Default true. False keeps the card and turns charging off." }, "threshold_credits": { "type": "integer", "description": "Refill when the balance is below this.", "minimum": 1 }, "max_refills_per_month": { "type": "integer", "description": "Maximum charges in a UTC month.", "minimum": 1 }, "max_eur_per_month": { "type": "integer", "description": "Euro cap for a UTC month. At least the price of one pack. Prices are listed at https://recruitmcp.com/pricing.", "minimum": 99 } }, "required": [ "threshold_credits", "max_refills_per_month", "max_eur_per_month" ], "example": { "enabled": true, "threshold_credits": 200, "max_refills_per_month": 3, "max_eur_per_month": 297 } }, "Balance": { "type": "object", "properties": { "balance_credits": { "type": [ "integer", "null" ], "description": "Account balance. A customer-bound key gets that customer's remaining daily cap, or null when the customer has no cap." }, "by_source": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "plan, topup, free, promo (launch bonus), admin, refund, legacy. Empty for a customer-bound key." }, "buckets": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "upcoming_expiries": { "type": "array", "items": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time" }, "credits": { "type": "integer" }, "source": { "type": "string" }, "bucket_id": { "type": "string" } } } }, "next_expiry": { "type": [ "object", "null" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "credits": { "type": "integer" } } }, "rules": { "type": "object", "additionalProperties": {} }, "subscription": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "balance_credits" ], "example": { "balance_credits": 1250, "by_source": { "free": 1250 }, "buckets": [ { "source": "free", "remaining_credits": 1250 } ], "upcoming_expiries": [], "next_expiry": null } }, "CacheDeletionPreview": { "type": "object", "properties": { "object": { "type": "string", "description": "cache_deletion" }, "dry_run": { "type": "boolean" }, "deleted": { "type": "boolean", "description": "Always false on a dry run." }, "would_delete": { "type": "array", "items": { "type": "string" } }, "effect": { "type": "string" }, "execute": { "type": "string", "description": "The call that deletes." }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "object", "dry_run", "deleted", "would_delete", "cost" ] }, "CheckoutSession": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "stripe", "unconfigured" ] }, "url": { "type": [ "string", "null" ], "description": "Hosted checkout URL. Send the buyer here. Null when checkout is not configured." }, "session_id": { "type": [ "string", "null" ], "description": "Checkout session id." }, "credits": { "type": "integer", "description": "Credits this checkout adds after payment." } }, "required": [ "mode", "url", "session_id", "credits" ], "example": { "mode": "stripe", "url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6", "session_id": "cs_test_a1b2c3d4e5f6", "credits": 7500 } }, "Company": { "type": "object", "properties": { "query_name": { "type": "string" }, "company_name": { "type": [ "string", "null" ] }, "company_id": { "type": [ "string", "null" ] }, "company_url": { "type": [ "string", "null" ] }, "universal_name": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "employee_count": { "type": [ "integer", "null" ] }, "website": { "type": [ "string", "null" ] }, "not_found": { "type": "boolean" } }, "required": [ "query_name" ] }, "CompanyList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "object", "data", "next_cursor", "has_more" ], "example": { "object": "list", "data": [ { "query_name": "Paperkiln", "company_name": "Paperkiln", "company_id": "51207", "company_url": "https://companies.example.com/paperkiln", "universal_name": "paperkiln", "industry": "Computer Software", "employee_count": 400, "website": "https://example.com", "not_found": false } ], "next_cursor": null, "has_more": false, "cost": { "credits": 1, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } } }, "CompanyResolveRequest": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "Company names or company URLs. Up to 50.", "maxItems": 50 }, "country": { "type": "string", "description": "Country that disambiguates common names." }, "confirm": { "type": "boolean", "description": "Deprecated. Accepted and ignored. The call runs when the key is authorized.", "deprecated": true }, "confirm_token": { "type": "string", "description": "From approval_required. Required only when the estimate is above the key threshold." } }, "required": [ "names" ] }, "ContactLookupRequest": { "type": "object", "properties": { "prefer": { "type": "string", "enum": [ "personal", "work" ], "description": "Email to prefer. personal, the default, ranks personal, then unlabeled, then work. work reverses that order. Phones still prefer mobile." }, "dry_run": { "type": "boolean", "description": "When true, preview the cost and change nothing. Nothing is charged. Same as the dry_run query." }, "confirm": { "type": "boolean", "description": "Deprecated. Accepted and ignored. An authorized lookup runs without it.", "deprecated": true }, "confirm_token": { "type": "string", "description": "From approval_required. Required only when the estimate is above the key threshold." } }, "example": { "prefer": "personal" } }, "Contacts": { "type": "object", "properties": { "profile_id": { "type": "string" }, "canonical_id": { "type": "string", "description": "Search id for this person when both profile ids are known." }, "contacts": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "not_found", "pending", "expired" ] }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": [ "string", "null" ], "enum": [ "personal", "work" ], "description": "work or personal when the lookup provides it. Null when it does not." }, "line": { "type": "string", "enum": [ "mobile", "work_phone", "work", "personal" ], "description": "Provider line. mobile and work_phone stay on phones." }, "confidence": { "type": [ "number", "null" ] }, "flagged": { "type": "boolean", "description": "True when a plausibility check says this entry is clearly not this person." }, "flag_reason": { "type": "string", "description": "Short reason, at most 12 words. Present when flagged is true." } } } }, "phones": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "enum": [ "personal", "work" ] }, "line": { "type": "string", "enum": [ "mobile", "work_phone", "work", "personal" ], "description": "Provider line. mobile and work_phone stay on phones." }, "confidence": { "type": [ "number", "null" ] }, "flagged": { "type": "boolean", "description": "True when a plausibility check says this entry is clearly not this person." }, "flag_reason": { "type": "string", "description": "Short reason, at most 12 words. Present when flagged is true." } } } }, "best_email": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "type": { "type": [ "string", "null" ], "enum": [ "personal", "work" ], "description": "work or personal when the lookup provides it. Null when it does not." }, "line": { "type": "string", "enum": [ "mobile", "work_phone", "work", "personal" ], "description": "Provider line. mobile and work_phone stay on phones." }, "confidence": { "type": [ "number", "null" ] }, "reason": { "type": "string", "enum": [ "only_candidate", "mobile", "highest_rating", "personal_preferred", "work_preferred", "matches_employer_domain", "llm_plausibility" ], "description": "Why this address or number was chosen. llm_plausibility means a flagged entry changed the pick." } }, "required": [ "value", "type", "confidence", "reason" ] }, "best_phone": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "type": { "type": [ "string", "null" ], "enum": [ "personal", "work" ], "description": "work or personal when the lookup provides it. Null when it does not." }, "line": { "type": "string", "enum": [ "mobile", "work_phone", "work", "personal" ], "description": "Provider line. mobile and work_phone stay on phones." }, "confidence": { "type": [ "number", "null" ] }, "reason": { "type": "string", "enum": [ "only_candidate", "mobile", "highest_rating", "personal_preferred", "work_preferred", "matches_employer_domain", "llm_plausibility" ], "description": "Why this address or number was chosen. llm_plausibility means a flagged entry changed the pick." } }, "required": [ "value", "type", "confidence", "reason" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "status", "emails", "phones", "best_email", "best_phone" ] }, "credits": { "type": "number", "description": "Credits charged for this person on the lookup. 0 on a miss, a cache hit, a pending lookup, and when this response did not itself charge." }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "profile_id", "contacts" ] }, "ContactsFetchRequest": { "type": "object", "properties": { "profile_ids": { "type": "array", "items": { "type": "string" }, "description": "Profile ids already fetched. Up to 100. Send this or ids.", "maxItems": 100 }, "ids": { "type": "array", "items": { "type": "string" }, "description": "Alias of profile_ids, the same name POST /v1/people:enrich uses. Merged with profile_ids.", "maxItems": 100 }, "prefer": { "type": "string", "enum": [ "personal", "work" ], "description": "Email to prefer. personal, the default, ranks personal, then unlabeled, then work. work reverses that order. Phones still prefer mobile." }, "dry_run": { "type": "boolean", "description": "When true, preview the cost and change nothing. Nothing is charged. Same as the dry_run query." }, "confirm": { "type": "boolean", "description": "Deprecated. Accepted and ignored. An authorized lookup runs without it.", "deprecated": true }, "confirm_token": { "type": "string", "description": "From approval_required. Required only when the estimate is above the key threshold." } }, "example": { "profile_ids": [ "lead_8f2a1c_1" ], "prefer": "personal" } }, "ContactsLookup": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contacts" } }, "cost": { "$ref": "#/components/schemas/Cost" }, "status": { "type": "string", "enum": [ "pending", "completed" ], "description": "pending while the lookup is running. completed when the job poll has the stored contacts." }, "request_id": { "type": [ "string", "null" ], "description": "Id of the running lookup." }, "job_id": { "type": "string", "description": "Set on HTTP 202. Poll GET /v1/contacts/jobs/{job_id}." }, "poll_url": { "type": "string", "description": "Path of GET /v1/contacts/jobs/{job_id}. Requires contacts:spend." }, "canonical_id": { "type": [ "string", "null" ], "description": "Search id when one person was requested." }, "charged_this_request": { "type": "number", "description": "Credits charged for the lookup this body describes. Matches cost.credits. On a 202 and on a pending poll it is 0. On a completed poll it is what the lookup that started the job was charged at completion, the same as credits_charged; the poll itself charges nothing. 0 on an idempotent replay, where cost.credits is also 0." }, "credits_charged": { "type": "number", "description": "Set on a contact job (HTTP 202 and GET /v1/contacts/jobs/{job_id}). Credits the ledger charged for this job: 0 while pending, then the same number as cost.credits." } }, "required": [ "data", "cost" ], "additionalProperties": true, "example": { "data": [ { "profile_id": "lead_8f2a1c_1", "contacts": { "status": "ready", "emails": [ { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9 } ], "phones": [ { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8 } ], "best_email": { "value": "ada.peeters@example.com", "type": "personal", "line": "personal", "confidence": 0.9, "reason": "only_candidate" }, "best_phone": { "value": "+447700900001", "type": "personal", "line": "mobile", "confidence": 0.8, "reason": "only_candidate" }, "expires_at": "2026-11-12T09:00:00Z" }, "credits": 25, "cost": { "credits": 25, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } } ], "cost": { "credits": 25, "cached_items": 0, "live_items": 1, "upstream_calls": 1 }, "charged_this_request": 25 } }, "Cost": { "type": "object", "properties": { "credits": { "type": "integer", "description": "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": { "type": "integer", "description": "Items read from cache. On a replay, the value of the first response." }, "live_items": { "type": "integer", "description": "Items fetched live by this call. 0 on a replay." }, "upstream_calls": { "type": "integer", "description": "Index calls made by this call. 0 on a replay." } }, "required": [ "credits" ], "example": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } }, "CreditTransaction": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "credit_transaction" ] }, "kind": { "type": "string", "enum": [ "grant", "purchase", "usage", "expiry" ] }, "purpose": { "type": "string", "description": "Ledger purpose, for example signup_grant, stripe_purchase, or sourcing_lead." }, "description": { "type": "string", "description": "What this row is. A returned profile enrich says the credits were returned, not that new credits were granted." }, "credits": { "type": "number", "description": "Signed credits. Purchases and grants are positive. Usage and expiry are negative." }, "created_at": { "type": "string", "format": "date-time" }, "api_key_id": { "type": [ "string", "null" ] }, "run_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Customer this row was charged to, when the ledger recorded one." }, "request_id": { "type": [ "string", "null" ], "description": "X-Request-Id of the API or MCP call that caused this charge. For a job, the call that started it. null when unknown, for example on older rows and on purchases." }, "job_id": { "type": [ "string", "null" ], "description": "Job that charged this row (GET /v1/jobs/{job_id} or GET /v1/contacts/jobs/{job_id}). null when the charge was not made by a job." } }, "required": [ "id", "object", "kind", "purpose", "description", "credits", "created_at", "customer_id", "request_id", "job_id" ], "example": { "id": "led_01J0LEDGER0EXAMPLE", "object": "credit_transaction", "kind": "usage", "purpose": "contact_enrichment", "description": "Contact lookup", "credits": -25, "created_at": "2026-10-15T04:17:00.000Z", "api_key_id": "key_01J0KEY0EXAMPLE", "run_id": null, "customer_id": null, "request_id": "req_4f1c2a9b7e3d5a60", "job_id": "cjob_01J0CJOB0EXAMPLE" } }, "CreditTransactionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTransaction" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "customer" ] }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ], "description": "Your id for this tenant." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "daily_cap_credits": { "type": [ "integer", "null" ], "description": "Credits this customer may spend per UTC day." }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "name", "status" ], "description": "A sub-workspace for one of your own customers: its own seen register, lists, suppressions, and cap. Credits come from your account.", "example": { "id": "cus_8d1f0a2b3c4d5e6f7a", "object": "customer", "name": "Northwind Recruiting", "external_id": "tenant_42", "metadata": { "plan": "pro" }, "daily_cap_credits": 100, "status": "active", "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:00Z" } }, "CustomerInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "external_id": { "type": [ "string", "null" ], "description": "Your id for this tenant." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "daily_cap_credits": { "type": [ "integer", "null" ], "description": "Credits this customer may spend per UTC day. Null for no cap." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Update only." } }, "example": { "name": "Northwind Recruiting", "external_id": "tenant_42", "daily_cap_credits": 100 } }, "CustomerList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "DeveloperBilling": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "developer_billing" ] }, "status": { "type": "string", "enum": [ "inactive", "active", "suspended", "ending", "ended" ] }, "spend_limit_eur": { "type": "integer", "description": "Customer monthly limit in euros." }, "effective_limit_eur": { "type": "number", "description": "Limit that applies now, after the first-cycle cap and the server ceiling." }, "min_spend_limit_eur": { "type": "integer" }, "max_spend_limit_eur": { "type": "integer" }, "usage_credits": { "type": "number", "description": "Metered credits in the current period." }, "usage_eur": { "type": "number", "description": "Metered euros in the current period." }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "first_invoice_paid": { "type": "boolean" }, "card_on_file": { "type": "boolean" }, "suspended_reason": { "type": [ "string", "null" ] }, "price_eur_per_credit": { "type": "number" } }, "required": [ "object", "status", "spend_limit_eur", "effective_limit_eur", "usage_credits", "usage_eur", "card_on_file", "first_invoice_paid", "price_eur_per_credit" ] }, "Erasure": { "type": "object", "properties": { "subject": { "type": "string", "description": "Hash of the subject, for your records." }, "erased": { "type": "object", "additionalProperties": {} }, "suppressed": { "type": "boolean" }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "subject", "erased", "suppressed" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "invalid_id", "unsupported_filter", "unsupported_version", "idempotency_key_required", "unauthorized", "forbidden", "insufficient_scope", "insufficient_credits", "daily_credit_cap_reached", "spend_limit_reached", "free_tier_limit", "not_found", "feature_disabled", "not_cached", "suppressed", "method_not_allowed", "conflict", "idempotency_key_reused", "idempotency_in_progress", "approval_required", "confirm_token_used", "contacts_unavailable", "client_ip_required", "outreach_cap_reached", "account_paused", "account_not_ready", "rate_limited", "upstream_busy", "upstream_error", "account_connect_unavailable", "account_required", "approval_forced", "gateway_timeout", "confirmation_required", "invalid_verification_link", "invalid_recovery_link", "invalid_confirm_token", "internal" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {}, "description": "Field-specific context, for example available values or a hint." }, "fix": { "type": "string", "description": "A short fix for this error. The same sentences are on /docs/errors." }, "docs": { "type": "string", "description": "Anchor on the docs errors section for that fix." } }, "required": [ "code", "message", "request_id" ] }, "required_credits": { "type": "integer", "description": "Credits this call needed. Present with insufficient_credits, beside error." }, "balance_credits": { "type": "integer", "description": "Balance the caller can see. Omitted when a customer-bound key must not learn the account pool." }, "resets_at": { "type": "string", "format": "date-time", "description": "Next UTC midnight. Present with daily_credit_cap_reached, beside error." }, "retry_at": { "type": "string", "format": "date-time", "description": "When a paused profile source may be tried again. Present with that upstream_busy, beside error." }, "estimate": { "$ref": "#/components/schemas/Estimate" }, "confirm_token": { "type": "string", "description": "Send this back to run a call that returned approval_required. Bound to the same body." }, "approval_threshold_credits": { "type": "integer", "description": "The key threshold this call crossed. Present with approval_required." }, "approval_threshold_enrollments": { "type": "integer", "description": "The enrollment threshold this call crossed. Present with approval_required on an enrollment." }, "enrollments": { "type": "integer", "description": "summary.scheduled for the enrollment that crossed the threshold." }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "error" ], "example": { "error": { "code": "insufficient_credits", "message": "Not enough credits for this operation.", "request_id": "req_4f2a9c0d1e2b3a45", "details": { "required_credits": 21, "balance_credits": 3 } }, "required_credits": 21, "balance_credits": 3, "resets_at": "2026-10-14T00:00:00.000Z", "retry_at": "2026-10-13T15:00:00.000Z" } }, "Estimate": { "type": "object", "properties": { "credits_min": { "type": "integer", "description": "Lowest expected spend. Whole credits." }, "credits_max": { "type": "integer", "description": "Ceiling. Spend never passes it. Whole credits." }, "expected_pages": { "type": "integer" }, "expected_profile_fetches": { "type": "integer" }, "skipped_pages_from_checkpoints": { "type": "integer", "description": "Pages already paid for in an earlier search. Not charged again." }, "cached_items": { "type": "integer", "description": "Items served from cache, free." }, "balance_credits": { "type": [ "integer", "null" ], "description": "Account balance. A customer-bound key gets that customer's remaining daily cap, or null when the customer has no cap." }, "sufficient": { "type": "boolean", "description": "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": { "type": [ "string", "null" ], "description": "Null when sufficient is true. Otherwise the live call can return 402 insufficient_credits." }, "requires_confirm": { "type": "boolean", "description": "False on a search, profile, company, or contact preview. True when the call still needs an explicit confirm." } }, "required": [ "credits_min", "credits_max", "requires_confirm" ], "example": { "credits_min": 0, "credits_max": 10, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "job.completed", "job.failed", "contacts.completed", "enrollment.created", "enrollment.completed", "enrollment.failed", "action.sent", "action.failed", "action.awaiting_approval", "reply.received", "invite.accepted", "account.connected", "account.paused", "account.disconnected", "outreach.cap_reached", "credits.low", "credits.expiring", "credits.purchased", "credits.granted", "credits.used", "credits.payg_alert" ] }, "created_at": { "type": "string", "format": "date-time" }, "customer_id": { "type": [ "string", "null" ] }, "data": { "type": "object", "additionalProperties": {}, "description": "The object the event is about. Fields depend on type." } }, "required": [ "id", "object", "type", "created_at", "data" ], "example": { "id": "evt_job_job_3c4d_20261013093000", "object": "event", "type": "job.completed", "created_at": "2026-10-13T09:30:00Z", "customer_id": null, "data": { "job_id": "job_3c4d5e6f7a8b9c0d1e", "status": "completed" } } }, "EventList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "FilterValues": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "IgnoredField": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "field", "reason" ] }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "job" ] }, "kind": { "type": "string", "enum": [ "people_fetch" ] }, "job_id": { "type": "string", "description": "Same as id." }, "status": { "type": "string", "enum": [ "queued", "running", "parked", "completed", "failed" ] }, "poll_url": { "type": "string", "description": "Path of GET /v1/jobs/{job_id}. Poll it every few seconds until status is completed or failed." }, "credits_charged": { "type": "number", "description": "Credits the ledger charged for this job, the same number as result.cost.credits once completed. 0 until the job completes. The call that queued the job is charged when it completes." }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "error": { "type": [ "string", "null" ] }, "result": { "type": [ "object", "null" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } }, "not_found": { "type": "array", "items": { "type": "string" } }, "cost": { "$ref": "#/components/schemas/Cost" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "status" ], "example": { "id": "job_01J0JOB0EXAMPLE", "object": "job", "kind": "people_fetch", "job_id": "job_01J0JOB0EXAMPLE", "status": "completed", "poll_url": "/v1/jobs/job_01J0JOB0EXAMPLE", "credits_charged": 2, "progress": { "done": 1, "total": 1 }, "error": null, "result": { "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" } ], "not_found": [], "cost": { "credits": 2, "cached_items": 0, "live_items": 1, "upstream_calls": 1 } }, "created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:04Z" } }, "JobList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "List": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "list" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "item_count": { "type": "integer", "description": "People still on the list. Suppressed people are not counted, matching the items view and the CSV." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "name", "item_count" ] }, "ListItem": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "list_item" ] }, "profile_id": { "type": [ "string", "null" ] }, "profile_url": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "added_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object" ] }, "ListItemInput": { "type": "object", "properties": { "profile_id": { "type": "string" }, "profile_url": { "type": "string" }, "email": { "type": "string" }, "full_name": { "type": "string" }, "company": { "type": "string", "description": "With full_name, the normalized name and company match a suppression." }, "company_url": { "type": "string" }, "note": { "type": "string" } }, "description": "Needs profile_id, profile_url, email, company_url, or full_name. A name without a company cannot match a suppression." }, "ListItems": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "Lists": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/List" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "Location": { "type": "object", "properties": { "geo_id": { "type": "string" }, "title": { "type": "string" }, "is_area": { "type": "boolean" } }, "required": [ "geo_id", "title" ], "example": { "geo_id": "90009496", "title": "London Area, United Kingdom", "is_area": true } }, "LocationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" }, "cost": { "$ref": "#/components/schemas/Cost" }, "hint": { "type": "string", "description": "Set when the place has no city id. The country is not returned as a silent stand-in." }, "fallback": { "type": "string", "enum": [ "country" ], "description": "country when the only match was a country. data stays empty." } }, "required": [ "object", "data", "next_cursor", "has_more" ], "example": { "object": "list", "data": [ { "geo_id": "90009496", "title": "London Area, United Kingdom", "is_area": true }, { "geo_id": "102257491", "title": "Greater London, England, United Kingdom", "is_area": false } ], "next_cursor": null, "has_more": false, "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } }, "OptOut": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "PeopleFetchRequest": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Profile ids or public profile URLs. Up to 100.", "maxItems": 100 }, "profile_ids": { "type": "array", "items": { "type": "string" }, "description": "Alias of ids, the same name POST /v1/people/contacts:fetch uses. Merged with ids.", "maxItems": 100 }, "profile_urls": { "type": "array", "items": { "type": "string" }, "description": "Public profile URLs. Up to 100 together with ids.", "maxItems": 100 }, "max_age_days": { "type": "integer", "description": "Cached copies younger than this are free. Default 30.", "minimum": 1, "maximum": 365 }, "enrich_companies": { "type": "boolean", "description": "Add industry and size to each experience entry." }, "confirm": { "type": "boolean", "description": "Deprecated. Accepted and ignored. An authorized enrich runs without it.", "deprecated": true }, "confirm_token": { "type": "string", "description": "From approval_required. Required only when the estimate is above the key threshold." } }, "example": { "ids": [ "lead_8f2a1c_1", "lead_3c71e0_2" ], "max_age_days": 30 } }, "PeopleFilters": { "type": "object", "properties": { "current_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Current job titles. Up to 70." }, "exclude_current_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Current job titles to exclude. Up to 70." }, "past_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Titles held before the current role. Up to 70." }, "exclude_past_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Past titles to exclude. Up to 70." }, "geo_ids": { "type": "array", "items": { "type": "string" }, "description": "Numeric location ids from GET /v1/lookups/locations or /v1/lookups/areas. Up to 70." }, "exclude_geo_ids": { "type": "array", "items": { "type": "string" }, "description": "Location ids to exclude. Up to 70." }, "current_companies": { "type": "array", "items": { "type": "string" }, "description": "Current employers. Pass a company URL or company id from POST /v1/companies:resolve. A bare name is sent as written and does not match a company. Up to 50." }, "exclude_current_companies": { "type": "array", "items": { "type": "string" }, "description": "Current employers to exclude, as company URLs or ids from companies:resolve. Up to 50." }, "past_companies": { "type": "array", "items": { "type": "string" }, "description": "Former employers. Pass a company URL or company id from POST /v1/companies:resolve. A bare name is not resolved. Up to 50." }, "exclude_past_companies": { "type": "array", "items": { "type": "string" }, "description": "Former employers to exclude, as company URLs or ids. Up to 50." }, "schools": { "type": "array", "items": { "type": "string" }, "description": "Schools attended, by name. Up to 50." }, "exclude_schools": { "type": "array", "items": { "type": "string" }, "description": "Schools to exclude. Up to 50." }, "industry_ids": { "type": "array", "items": { "type": "string" }, "description": "Industry ids from GET /v1/lookups/industries." }, "exclude_industry_ids": { "type": "array", "items": { "type": "string" }, "description": "Industry ids to exclude." }, "function_ids": { "type": "array", "items": { "type": "string" }, "description": "Job function ids from GET /v1/lookups/functions." }, "exclude_function_ids": { "type": "array", "items": { "type": "string" }, "description": "Job function ids to exclude." }, "seniority_level_ids": { "type": "array", "items": { "type": "string" }, "description": "Seniority level ids from GET /v1/lookups/seniorities." }, "exclude_seniority_level_ids": { "type": "array", "items": { "type": "string" }, "description": "Seniority level ids to exclude." }, "years_of_experience_ids": { "type": "array", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] }, "description": "Experience ranges from GET /v1/lookups/experience-ranges." }, "years_at_current_company_ids": { "type": "array", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] }, "description": "Experience ranges for time at the current company." }, "company_headcount": { "type": "array", "items": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G", "H", "I" ] }, "description": "Current-company headcount ranges from GET /v1/lookups/headcounts." }, "profile_languages": { "type": "array", "items": { "type": "string" }, "description": "Profile language codes from GET /v1/lookups/languages." }, "first_names": { "type": "array", "items": { "type": "string" }, "description": "First names. Up to 50." }, "last_names": { "type": "array", "items": { "type": "string" }, "description": "Last names. Up to 50." }, "recently_changed_jobs": { "type": "boolean", "description": "Only people who changed jobs in the last 90 days." }, "search": { "type": "string", "description": "Keywords. Quote phrases and combine with OR, AND, NOT. At most 1,000 characters.", "maxLength": 1000 } }, "additionalProperties": false, "description": "People-search filters. Each one maps to a filter the profile index applies; anything else is rejected with unsupported_filter.", "example": { "current_job_titles": [ "Backend Engineer" ], "geo_ids": [ "90009496" ], "past_companies": [ "51207" ], "profile_languages": [ "en" ] } }, "PeopleMatch": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "person_match" ] }, "outcome": { "type": "string", "enum": [ "exact", "ambiguous", "none" ] }, "match": { "oneOf": [ { "$ref": "#/components/schemas/PersonStub" }, { "type": "null" } ] }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "outcome", "match", "cost" ], "example": { "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 } } }, "PeopleMatchRequest": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string", "description": "Instead of first_name and last_name." }, "company": { "type": "string", "description": "Current employer name or company URL." }, "confirm": { "type": "boolean", "description": "Deprecated. Accepted and ignored. An authorized match runs without it.", "deprecated": true }, "confirm_token": { "type": "string", "description": "From approval_required. Required only when the estimate is above the key threshold." } }, "required": [ "company" ], "example": { "first_name": "Ada", "last_name": "Peeters", "company": "Acme" } }, "PeopleSearchPage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "people_page" ] }, "query_key": { "type": "string", "description": "Stable id of this filter set. A lead is charged once per workspace." }, "total_elements": { "type": [ "integer", "null" ], "description": "Estimate from the index before the location post-filter. Profiles dropped for location are counted in omitted.outside_geo and are not subtracted here." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonStub" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this back as cursor to continue. Null when nothing remains." }, "omitted": { "type": "object", "properties": { "suppressed": { "type": "integer", "description": "Always removed." }, "already_seen": { "type": "integer", "description": "Removed because exclude_seen was true." }, "unpaid": { "type": "integer", "description": "Not returned, because the balance ran out. Not charged. Continue with next_cursor." }, "cap": { "type": "integer", "description": "Not returned, because the key or customer daily credit cap was reached. Not charged. Continue with next_cursor after resets_at." }, "outside_geo": { "type": "integer", "description": "Removed because the location is outside a requested place. Not charged." }, "seniority": { "type": "integer", "description": "Removed because the title does not match seniority 310 (CXO). Not charged." } } }, "applied_filters": { "type": "array", "items": { "$ref": "#/components/schemas/AppliedFilter" }, "description": "Each filter as sent to the person index, plus suppression and exclude_seen." }, "ignored_fields": { "type": "array", "items": { "$ref": "#/components/schemas/IgnoredField" }, "description": "Always empty: unsupported filters are refused with unsupported_filter." }, "cost": { "$ref": "#/components/schemas/Cost" }, "partial": { "type": "boolean", "description": "Present and true when the time budget ended before limit was reached. data holds the profiles that arrived, only those are charged, and next_cursor continues the rest, which keep loading in the background." } }, "required": [ "query_key", "data", "next_cursor", "applied_filters", "ignored_fields", "cost" ], "example": { "object": "people_page", "query_key": "qk_backend_london", "total_elements": 128, "data": [ { "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 }, { "profile_id": "lead_3c71e0_2", "full_name": "Jonas Vermeulen", "location": "London, England, United Kingdom", "alternate_id": null, "photo": null, "profile_url": "https://profiles.example.com/jonas-vermeulen", "current_positions": [ { "title": "Platform Engineer", "company_name": "Paperkiln", "company_id": null, "company_url": "https://companies.example.com/paperkiln", "current": true, "description": null, "started_on": { "year": 2025, "month": 11, "text": "2025-11" }, "tenure_at_position": { "numMonths": 11 }, "tenure_at_company": { "numMonths": 11 } } ], "identity_key": "jonas vermeulen|paperkiln", "already_seen": false }, { "profile_id": "lead_5d09b4_3", "full_name": "Lina Dubois", "location": "London, England, United Kingdom", "alternate_id": null, "photo": null, "profile_url": "https://profiles.example.com/lina-dubois", "current_positions": [ { "title": "Backend Engineer", "company_name": "Acme Robotics", "company_id": null, "company_url": "https://companies.example.com/acme-robotics", "current": true, "description": null, "started_on": { "year": 2023, "month": 1, "text": "2023-01" }, "tenure_at_position": { "numYears": 3, "numMonths": 9 }, "tenure_at_company": { "numYears": 3, "numMonths": 9 } } ], "identity_key": "lina dubois|acme robotics", "already_seen": true } ], "next_cursor": "eyJvZmZzZXQiOjN9", "omitted": { "suppressed": 0, "already_seen": 0, "unpaid": 0 }, "applied_filters": [ { "field": "current_job_titles", "effect": "hard_filter", "detail": "Backend Engineer" } ], "ignored_fields": [], "cost": { "credits": 3, "cached_items": 3, "live_items": 0, "upstream_calls": 1 } } }, "PeopleSearchPreview": { "type": "object", "properties": { "dry_run": { "type": "boolean", "description": "True. This response spent nothing and changed nothing.", "const": true }, "estimate": { "$ref": "#/components/schemas/Estimate" }, "applied_filters": { "type": "array", "items": { "$ref": "#/components/schemas/AppliedFilter" } }, "ignored_fields": { "type": "array", "items": { "$ref": "#/components/schemas/IgnoredField" } }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "dry_run", "estimate", "applied_filters", "ignored_fields", "cost" ], "example": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 10, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "applied_filters": [ { "field": "current_job_titles", "effect": "hard_filter", "detail": "Backend Engineer" } ], "ignored_fields": [], "cost": { "credits": 0, "cached_items": 0, "live_items": 0, "upstream_calls": 0 } } }, "PeopleSearchRequest": { "type": "object", "properties": { "filters": { "$ref": "#/components/schemas/PeopleFilters" }, "limit": { "type": "integer", "description": "Profiles to return. 1 to 100. Defaults to 25. A JSON number. Query parameters accept numeric strings; a JSON body does not.", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "From the previous response next_cursor. Omit to start at the beginning." }, "exclude_seen": { "type": "boolean", "description": "Drop people already in the seen register. Default false on REST and MCP: they are returned with already_seen true." }, "confirm": { "type": "boolean", "description": "Deprecated. Accepted and ignored. An authorized search runs without it.", "deprecated": true }, "confirm_token": { "type": "string", "description": "From approval_required. Required only when the estimate is above the key threshold." } }, "required": [ "filters" ], "example": { "filters": { "current_job_titles": [ "Backend Engineer" ], "geo_ids": [ "90009496" ] }, "limit": 10 } }, "PersonStub": { "type": "object", "properties": { "profile_id": { "type": "string", "description": "Search id for this person, an opaque string. GET /v1/people/{profile_id} also accepts the alternate id." }, "alternate_id": { "type": [ "string", "null" ], "description": "The other profile id for the same person. Null until the person has been enriched and both ids are known." }, "full_name": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "profile_url": { "type": [ "string", "null" ] }, "photo": { "type": [ "string", "null" ], "description": "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": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_id": { "type": [ "string", "null" ] }, "company_url": { "type": [ "string", "null" ] }, "current": { "type": "boolean" }, "description": { "type": [ "string", "null" ], "description": "The role description as written on the profile." }, "started_on": { "type": [ "object", "null" ], "properties": { "year": { "type": "integer" }, "month": { "type": "integer" }, "text": { "type": "string" } }, "description": "Start of this role, for example { year: 2020, month: 1, text: \"2020-01\" }. Keys can be missing." }, "tenure_at_position": { "type": [ "object", "null" ], "properties": { "numYears": { "type": "integer" }, "numMonths": { "type": "integer" } }, "description": "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." }, "tenure_at_company": { "type": [ "object", "null" ], "properties": { "numYears": { "type": "integer" }, "numMonths": { "type": "integer" } }, "description": "Time at this company, same shape as tenure_at_position: a key whose value is 0 is left out." } } } }, "identity_key": { "type": [ "string", "null" ] }, "already_seen": { "type": "boolean", "description": "True when the person is in your seen register." } }, "required": [ "profile_id" ], "example": { "profile_id": "lead_8f2a1c_1", "full_name": "Ada Peeters", "location": "London, England, United Kingdom", "profile_url": "https://profiles.example.com/ada-peeters", "current_positions": [ { "title": "Backend Engineer", "company_name": "Acme Robotics", "company_url": "https://companies.example.com/acme-robotics", "current": true } ], "already_seen": false } }, "Plans": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "monthly_credits": { "type": "integer" }, "monthly_eur": { "type": "number" }, "placeholder": { "type": "boolean" } } } }, "rules": { "type": "object", "additionalProperties": {} }, "signup_credits": { "type": "integer" } }, "required": [ "data" ] }, "Preview": { "type": "object", "properties": { "dry_run": { "type": "boolean", "description": "True on this preview. Nothing was charged and nothing was changed.", "const": true }, "estimate": { "$ref": "#/components/schemas/Estimate" }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "dry_run", "estimate" ], "additionalProperties": false, "description": "Returned when dry_run=true. Nothing was spent or changed. Search, profile, company, and contact previews set dry_run true and requires_confirm false.", "example": { "dry_run": true, "estimate": { "credits_min": 0, "credits_max": 10, "balance_credits": 1250, "sufficient": true, "warning": null, "requires_confirm": false }, "cost": { "credits": 0 } } }, "Profile": { "type": "object", "properties": { "profile_id": { "type": "string", "description": "Search id. The same value search returned when both ids are known." }, "alternate_id": { "type": [ "string", "null" ], "description": "The other profile id for the same person. Null until the person has been enriched and both ids are known." }, "full_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "photo": { "type": [ "string", "null" ], "description": "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." }, "profile_url": { "type": [ "string", "null" ] }, "public_identifier": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "experience": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "started": { "type": [ "string", "null" ] }, "ended": { "type": [ "string", "null" ] }, "current": { "type": "boolean" }, "summary": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "company_url": { "type": [ "string", "null" ] }, "company_industry": { "type": [ "string", "null" ] }, "company_size": { "type": [ "string", "null" ] } } } }, "education": { "type": "array", "items": { "type": "object", "properties": { "university": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "description": "School profile URL." }, "degree": { "type": "array", "items": { "type": "string" } }, "faculty": { "type": [ "string", "null" ] }, "started_year": { "type": [ "integer", "null" ] }, "ended_year": { "type": [ "integer", "null" ] } } } }, "skills": { "type": "array", "items": { "type": "string" } }, "language": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "proficiency": { "type": [ "string", "null" ] } } } }, "certification": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "authority": { "type": [ "string", "null" ] } } } }, "open_to_work": { "type": "boolean" }, "source": { "type": "string", "enum": [ "profile_index", "contact_provider" ] }, "fetched_at": { "type": "string", "format": "date-time" } }, "required": [ "profile_id", "source" ], "description": "The complete normalized profile: every field the index returns, in a stable shape. Email and phone are not included. education is part of this full profile.", "example": { "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", "company_url": "https://companies.example.com/acme-robotics", "started": "2021-03", "current": true } ], "education": [ { "university": "University of Amsterdam", "url": "https://example.com/school/university-of-amsterdam", "degree": [ "MSc", "Computer Science" ], "faculty": "Computer Science", "started_year": 2013, "ended_year": 2019 } ], "skills": [ "Go", "Kubernetes" ], "source": "profile_index", "fetched_at": "2026-10-13T09:00:00Z" } }, "ProfileList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } }, "not_found": { "type": "array", "items": { "type": "string" } }, "omitted": { "type": "object", "properties": { "suppressed": { "type": "integer", "description": "Requested people who are suppressed. Never charged." } } }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "data", "not_found" ], "example": { "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 } } }, "SeenCheck": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "seen": { "type": "boolean" }, "match_on": { "type": [ "string", "null" ], "enum": [ "profile", "name_employer" ] }, "entry": { "oneOf": [ { "$ref": "#/components/schemas/SeenEntry" }, { "type": "null" } ] } } } } }, "required": [ "data" ] }, "SeenEntry": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "seen_entry" ] }, "status": { "type": "string", "enum": [ "seen", "shortlisted", "contacted", "rejected", "do_not_contact" ] }, "profile_url": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "current_employer": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "external_ids": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Your ids for this person, for example {\"ats\": \"cand_123\"}." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "object", "status" ] }, "SeenEntryInput": { "type": "object", "properties": { "profile_url": { "type": "string" }, "profile_id": { "type": "string" }, "full_name": { "type": "string" }, "current_employer": { "type": "string" }, "status": { "type": "string", "enum": [ "seen", "shortlisted", "contacted", "rejected", "do_not_contact" ] }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "external_ids": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Needs profile_url, profile_id, or full_name with current_employer." }, "SeenList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeenEntry" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "Suppression": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "suppression" ] }, "kind": { "type": "string", "enum": [ "profile", "email" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "kind" ], "description": "Only a hash is stored; the person cannot be read back." }, "SuppressionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Customer this usage was scoped to. Null for the account." }, "balance_credits": { "type": [ "integer", "null" ], "description": "Account balance, or the bound customer's remaining daily cap. Null when that customer has no cap." }, "daily_cap_credits": { "type": [ "integer", "null" ] }, "group_by": { "type": "string", "enum": [ "day", "purpose", "api_key", "customer" ] }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "credits": { "type": "integer" }, "upstream_calls": { "type": "integer" } } } }, "credits": { "type": "object", "additionalProperties": {} } }, "required": [ "object", "customer_id", "balance_credits", "buckets" ] }, "Verification": { "type": "object", "properties": { "verified": { "type": "boolean" }, "workspace_id": { "type": "string" }, "granted_credits": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "verified" ], "example": { "verified": true, "workspace_id": "ws_01J0WORKSPACE0EXAMPLE", "granted_credits": 1250 } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types, or [\"*\"] for all." }, "customer_id": { "type": [ "string", "null" ], "description": "Only events from this customer." }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "secret_hint": { "type": "string", "description": "Start of the signing secret, to tell secrets apart." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "url", "events", "status" ] }, "WebhookEndpointCreated": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Signing secret. Shown on create and rotate only." } }, "required": [ "secret" ] } ] }, "WebhookEndpointInput": { "type": "object", "properties": { "url": { "type": "string", "description": "Public https URL. Private and loopback addresses are refused." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Default [\"*\"]." }, "customer_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "example": { "url": "https://hooks.example.com/recruitmcp", "events": [ "job.completed", "reply.received" ] } }, "WebhookEndpointList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page. Null on the last page." }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "next_cursor", "has_more" ] }, "WebhookTest": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": [ "integer", "null" ] }, "event_id": { "type": "string" }, "error": { "type": [ "string", "null" ] } }, "required": [ "ok", "event_id" ], "additionalProperties": true }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "description": "ws_… when the request acts on the account. cus_… when RecruitMCP-Customer or a bound key selects a customer." }, "object": { "type": "string", "enum": [ "workspace" ] }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ], "description": "Owner first name from signup, or null. Not taken from the workspace name." }, "account_id": { "type": "string", "description": "Always the billing account, ws_…. Credits, keys, and webhooks stay on this id even when id is a customer." }, "customer": { "oneOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "null" } ] }, "balance_credits": { "type": [ "integer", "null" ], "description": "Account balance. A customer-bound key gets that customer's remaining daily cap, or null when the customer has no cap." }, "low_balance_credits": { "type": "integer", "description": "credits.low fires when the balance drops below this. Default 250." }, "plan": { "type": "string", "enum": [ "free", "starter", "growth", "scale", "payg" ], "description": "Current plan of the account. free without a subscription, payg with developer billing on. A canceled subscription is free." }, "marketing_opt_in": { "type": "boolean", "description": "True when this workspace asked for product updates and tips." }, "marketing_consent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the product-updates choice was stored." }, "marketing_consent_source": { "type": [ "string", "null" ], "enum": [ "signup", "console" ], "description": "Where the product-updates choice was made." }, "marketing_consent_text_version": { "type": [ "string", "null" ], "description": "Version of the checkbox sentence stored with the choice." }, "lifecycle_suppressed": { "type": "boolean", "description": "True stops every follow-up email for this workspace." }, "api_key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string" }, "kind": { "type": "string", "enum": [ "secret", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "sourcing:read", "sourcing:spend", "lists:write", "contacts:spend", "outreach:read", "outreach:write", "outreach:send", "outreach:approve", "privacy:write", "account:read", "account:manage", "billing:manage" ] } }, "daily_cap_credits": { "type": [ "integer", "null" ] }, "approval_threshold_credits": { "type": [ "integer", "null" ] }, "approval_threshold_enrollments": { "type": [ "integer", "null" ], "description": "Null when unset. HTTP then has no enrollment threshold. MCP uses 25 scheduled enrollments." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "api_version": { "type": "string", "description": "RecruitMCP-Version this request runs under." } }, "required": [ "id", "object", "account_id", "balance_credits", "low_balance_credits", "plan", "marketing_opt_in", "marketing_consent_at", "marketing_consent_source", "marketing_consent_text_version", "lifecycle_suppressed", "api_key", "api_version" ], "example": { "id": "ws_01J0WORKSPACE0EXAMPLE", "object": "workspace", "name": "Northwind Search", "email": "ada@northwind.example", "first_name": "Ada", "account_id": "ws_01J0WORKSPACE0EXAMPLE", "customer": null, "balance_credits": 1250, "low_balance_credits": 250, "plan": "free", "marketing_opt_in": false, "marketing_consent_at": "2026-10-15T12:00:00.000Z", "marketing_consent_source": "signup", "marketing_consent_text_version": "2026-10-15", "lifecycle_suppressed": false, "api_key": { "id": "key_01J0APIKEY0EXAMPLE", "name": "default", "prefix": "rmcp_live_ab12", "kind": "secret", "scopes": [ "sourcing:read", "sourcing:spend", "lists:write" ], "daily_cap_credits": null, "approval_threshold_credits": null, "approval_threshold_enrollments": null, "expires_at": null }, "api_version": "2026-10-13" } }, "WorkspaceCreated": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "api_key": { "type": "string", "description": "Shown once. Store it." }, "balance_credits": { "type": "integer" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "sourcing:read", "sourcing:spend", "lists:write", "contacts:spend", "outreach:read", "outreach:write", "outreach:send", "outreach:approve", "privacy:write", "account:read", "account:manage", "billing:manage" ] } }, "email_verification": { "type": "string", "enum": [ "not_required", "sent" ] }, "signup_credits_pending": { "type": "integer" }, "signup_credits_pending_reason": { "type": [ "string", "null" ], "enum": [ "email_already_claimed", "normalized_email_used" ], "description": "Why the free grant is 0. Null when it is still pending or already on the balance. email_already_claimed is the same address. normalized_email_used is a plus-tag or dotted Gmail form of an address that already received it." } }, "required": [ "id", "api_key" ], "example": { "id": "ws_01J0WORKSPACE0EXAMPLE", "name": "Northwind Search", "api_key": "rmcp_live_examplekeyexamplekeyexample", "balance_credits": 0, "scopes": [ "sourcing:read", "sourcing:spend", "lists:write", "contacts:spend", "outreach:read", "outreach:write", "outreach:send", "outreach:approve", "privacy:write", "account:read", "account:manage", "billing:manage" ], "email_verification": "sent", "signup_credits_pending": 1250 } } } } }