Account

Update workspace preferences

Changed on

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.

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

patch/v1/workspace

Request

  • Base URL: https://api.recruitmcp.com
  • URL: https://api.recruitmcp.com/v1/workspace
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://recruitmcp.com/oauth/authorize, token URL https://recruitmcp.com/oauth/token, scopes: account:manage)

Headers

Idempotency-Keystring

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.

RecruitMCP-Version'2026-10-13'

API version. Defaults to the version the key was created with. Supported: 2026-10-13.

Request body

low_balance_creditsinteger nullable

Whole credits. Null restores the default.

marketing_opt_inboolean

Product updates and tips. Omit to leave the stored choice.

lifecycle_suppressedboolean

Stop follow-up emails for this workspace. Omit to leave the stored flag.

Response

The workspace, with the change applied.

idstring required

ws_… when the request acts on the account. cus_… when RecruitMCP-Customer or a bound key selects a customer.

object'workspace' required
namestring
emailstring nullable
first_namestring nullable

Owner first name from signup, or null. Not taken from the workspace name.

account_idstring required

Always the billing account, ws_…. Credits, keys, and webhooks stay on this id even when id is a customer.

balance_creditsinteger nullable required

Account balance. A customer-bound key gets that customer's remaining daily cap, or null when the customer has no cap.

low_balance_creditsinteger required

credits.low fires when the balance drops below this. Default 250.

plan'free' | 'starter' | 'growth' | 'scale' | 'payg' required

Current plan of the account. free without a subscription, payg with developer billing on. A canceled subscription is free.

marketing_opt_inboolean required

True when this workspace asked for product updates and tips.

marketing_consent_atstring date-time nullable required

When the product-updates choice was stored.

marketing_consent_source'signup' | 'console' nullable required

Where the product-updates choice was made.

marketing_consent_text_versionstring nullable required

Version of the checkbox sentence stored with the choice.

lifecycle_suppressedboolean required

True stops every follow-up email for this workspace.

api_versionstring required

RecruitMCP-Version this request runs under.

Example response

{
  "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"
}

Changes

  • ad27b35513a6Revision changes
    • warning

      added the new approval_forced enum value to the / response property for the response status

    • warning

      added the new approval_forced enum value to the / response property for the response status

    • warning

      added the new approval_forced enum value to the / response property for the response status

    • warning

      added the new approval_forced enum value to the / response property for the response status