docs platform

Customers

Sub-workspaces for builders, one per end customer, each with its own memory and caps.

If you build a product on RecruitMCP for several recruiting teams, give each team a customer. A customer is a sub-workspace under your account: its own seen register, lists, suppressions, caches, searches, outreach accounts, sequences, and conversations. Credits come from your account, and usage can be split per customer.

One recruiter using RecruitMCP for themselves does not need customers.

Create one

curl -s -X POST "$RECRUITMCP_BASE/v1/customers" \
  -H "Authorization: Bearer $RECRUITMCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind Recruiting", "external_id": "tenant_42", "daily_cap_credits": 100}'

Field	Meaning
`name`	Shown in usage and events
`external_id`	Your own id for this tenant. Unique per account. `GET /v1/customers?external_id=tenant_42` finds it
`metadata`	Up to 20 string values for your own bookkeeping. Keys up to 40 characters, values up to 500
`daily_cap_credits`	Most credits this customer may spend per UTC day. Null for no cap
`status`	`active` or `disabled`. A disabled customer refuses every request, and its runs stop at their next step

Act inside a customer

Two ways, and both give the same isolation:

Send RecruitMCP-Customer: cus_… with an account key. Good for a backend that serves every tenant.
Create a key bound to the customer (POST /v1/api-keys with customer_id). The key can only reach that customer. Good for handing a key to a tenant's agent, or for an MCP connection per tenant.

curl -s "$RECRUITMCP_BASE/v1/seen?limit=5" \
  -H "Authorization: Bearer $RECRUITMCP_KEY" \
  -H "RecruitMCP-Customer: cus_3f9a1c0e7b2d4a6815"

A bound key that sends a different RecruitMCP-Customer gets 403 forbidden. An unknown customer is 404 not_found.

MCP works the same: send the header on the MCP connection, or connect with a bound key. OAuth consent lets the recruiter pick a customer for the grant.

What is separate and what is shared

Separate per customer	Shared with the account
Seen register, statuses, and tags	Billing changes: checkout, subscription, and keys
Lists and list items	API version pinning rules
Workspace suppressions	Opt-outs: a person who opted out is suppressed everywhere
Profile, search, and contact caches	Rate limit per key
Intents, search plans, runs, and fetch jobs	Webhook endpoints (filter with `customer_id`)
Outreach accounts, sequences, enrollments, conversations	Events (each carries `customer_id`)
Outreach settings and caps

A person already contacted by one customer is not marked seen in another. A customer's suppression list applies inside that customer only; the global opt-out list applies to all.

Account-level routes act on the account even with the header: keys, customers, webhook endpoints, billing. Keys bound to a customer cannot call them.

Caps and usage

A customer cap and a key cap both apply; the first one reached returns 402 daily_credit_cap_reached with details.cap set to customer or key, and resets_at.

GET /v1/usage?group_by=customer splits spend per customer for invoicing your own clients. A customer key, or the header, limits usage to that customer. A key bound to a customer does not see the account credit pool. Its balance is the remaining daily cap, or null when that customer has no cap. An account key still sees the account balance, including when the request names a customer.

Delete one

DELETE /v1/customers/{customer_id} revokes the customer's keys and deletes its data: seen register, lists, caches, searches, and outreach records. Spend stays on your ledger, tagged with the customer id.

What it costs

Customers are free. Their spend is your spend.

Reference: createCustomer, listCustomers, updateCustomer, deleteCustomer, and getUsage in the API reference.

API reference