Provision partner accounts

POST

api

partner

accounts

Error

A valid request URL is required to generate request examples

{
  "account": {
    "id": 412,
    "name": "Acme Legal",
    "external_id": "firm-8675309",
    "plan": "business",
    "created_at": "2026-07-22T18:20:00Z"
  },
  "admin": {
    "id": 991,
    "email": "admin@acme.example"
  },
  "api_token": "9df52c0b6b3c...",
  "identity_handoff_secret": "a62f81f0c0e9..."
}

Provisioning creates the account, confirmed admin, tenant API token, audit event, and optional identity-handoff secret in one transaction. Use an idempotency key because returned secrets are otherwise shown only once.

curl -X POST https://spitshake.io/api/partner/v1/accounts \
  -H "Authorization: Bearer $SPITSHAKE_PARTNER_KEY" \
  -H "Idempotency-Key: provision-firm-8675309" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Legal",
    "external_id": "firm-8675309",
    "plan": "business",
    "admin_email": "admin@acme.example",
    "admin_first_name": "Ada",
    "admin_last_name": "Lovelace",
    "locale": "en",
    "timezone": "America/New_York",
    "generate_identity_handoff_secret": true
  }'

201

{
  "account": {
    "id": 412,
    "name": "Acme Legal",
    "external_id": "firm-8675309",
    "plan": "business",
    "created_at": "2026-07-22T18:20:00Z"
  },
  "admin": {
    "id": 991,
    "email": "admin@acme.example"
  },
  "api_token": "9df52c0b6b3c...",
  "identity_handoff_secret": "a62f81f0c0e9..."
}

name and admin_email are required. Email is trimmed and lowercased. plan defaults to business; it must be both active and present in the partner’s operator-configured allowlist. The identity secret is omitted unless explicitly requested.

Errors

401

{ "error": "Unauthorized" }

403

{ "error": "Plan is not authorized for this partner" }

409

{ "error": "admin_email already exists" }

409 also covers a duplicate external_id within the same partner and uniqueness races.

422

{ "error": "Plan is missing or inactive" }

422 also covers missing fields and reuse of an idempotency key with a different body.

Authorizations

Authorization

string

header

required

Operator-issued partner key. Accepted only under /api/partner/v1.

Headers

Idempotency-Key

string

Retained for 24 hours. Reuse only with the exact same request body.

Maximum string length: 255

Body

application/json

name

string

required

admin_email

string<email>

required

external_id

string | null

plan

string

default:business

admin_first_name

string | null

admin_last_name

string | null

locale

string

timezone

string

generate_identity_handoff_secret

boolean

default:false

Response

Tenant account provisioned

account

object

required

Show child attributes

admin

object

required

Show child attributes

api_token

string

required

Tenant API token returned only once and on exact idempotent replay.

identity_handoff_secret

string

Present only when requested; returned once and on exact idempotent replay.

Error

A valid request URL is required to generate request examples

{
  "account": {
    "id": 412,
    "name": "Acme Legal",
    "external_id": "firm-8675309",
    "plan": "business",
    "created_at": "2026-07-22T18:20:00Z"
  },
  "admin": {
    "id": 991,
    "email": "admin@acme.example"
  },
  "api_token": "9df52c0b6b3c...",
  "identity_handoff_secret": "a62f81f0c0e9..."
}

Overview

Partner API

Templates

Thumbnails

Submissions

Submitters

Users

Access Tokens

Webhooks

Settings

Custom Domains

Teams

Audit Events

MFA

BAA

Security Events

Subscriptions

Plans

Payments

Verification

KBA

AI

Embed

Health

Provision partner accounts

Errors

Authorizations

Headers

Body

Response

​Errors

Authorizations

Headers

Body

Response

Errors