Client API Reference | First AI Employee

Start here

Client API overview

The Client API source contract is a tenant-scoped interface for approved partners. V1 has 78 operations: 50 GET, 26 POST, 2 DELETE. It exposes bounded business reads plus operation-specific writes guarded by scopes, idempotency, preconditions, or preview and commit where the route requires them. It is not a read-only API. Production access remains gated behind CLIENT_API_ENABLED, registration, grant, and entitlement; unregistered OAuth clients remain denied.

These docs do not grant access.

These routes require a registered OAuth client, an exact callback URI, and customer consent. Examples on this page are not credentials and cannot authorize a request.

Registered clients only

Unknown or disabled clients are denied. There is no public self-service client-registration endpoint.

Tenant from the grant

Every access token is bound to the customer that approved it. Callers cannot choose another tenant in a path, header, or request body.

Narrow scopes

Read and write permissions are separate. There is no Client API full-access scope, and the MCP-only mcp:full shortcut is never valid here.

Availability

Access and registration

Client API access requires a separate developer account, a submitted application, manual review, operator provisioning, and one-time secret delivery. Business owners cannot currently generate Client API credentials or API keys. Owner-created service accounts are MCP-only and cannot call /api/client/v1.

Source contract available; access review-gated

Review-gated and production-gated

After approval and provisioning, a registered client must use an exact HTTPS redirect URI and PKCE S256. The signed-in customer then approves the requested scopes for one business. Unknown or disabled clients cannot start an authorization flow, and the production gate can keep the whole resource surface closed.

What must happen before a first request

Create a developer account, complete publisher onboarding, and submit a fixed Client API application with its minimum scopes, exact HTTPS redirects, security contact, and data-handling details.
First AI Employee manually reviews the application. An operator provisions the confidential OAuth client, delivers its secret once through the approved secure channel, and finalizes the registration. The portal never displays the secret.
The client creates a PKCE verifier and S256 challenge, then keeps the verifier until the callback.
A signed-in customer approves the scopes on the First AI Employee consent screen.
The partner exchanges the one-time code and stores the returned tokens securely. OAuth client_credentials is not supported for the Client API.

Request developer access

Start here

Quickstart

Use this sequence after First AI Employee registers your integration. The example values are placeholders and will not work as credentials.

1. Submit a developer application

Create a developer account, complete onboarding, and submit the integration name, exact redirect URIs, security contact, data use, retention plan, and requested scopes for manual review and provisioning.

2. Send the customer to consent

Build an Authorization Code request. Use state for request binding and PKCE with S256 for every Client API client.

3. Exchange the code once

POST form-encoded data to /oauth/token. Authorization codes are single use. Reuse is rejected.

4. Call a granted resource

Send the access token as a Bearer credential. Do not put tokens in URLs, logs, analytics, or browser storage.

Request

GET https://api.firstaiemployee.com/oauth/authorize
  ?response_type=code
  &client_id=client_example
  &redirect_uri=https%3A%2F%2Fpartner.example%2Foauth%2Fcallback
  &scope=calls%3Aread%20bookings%3Aread
  &state=opaque_csrf_value
  &code_challenge=base64url_sha256_verifier
  &code_challenge_method=S256

Request

curl "https://api.firstaiemployee.com/api/client/v1/calls?limit=50" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Read and write scopes are separate. Every write uses its documented operation-specific controls. Some CRM, Forms, job, task, and note mutations use preview and commit; exports, webhooks, and asynchronous job lifecycle use their documented idempotency or preconditions.

Core concepts

OAuth 2.0

First AI Employee acts as an OAuth 2.0 authorization server. The implemented flow supports Authorization Code, exact registered redirect URIs, mandatory PKCE S256 for Client API clients, customer consent, hashed token storage, and refresh-token rotation.

Request

curl https://api.firstaiemployee.com/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=client_example" \
  --data-urlencode "client_secret=stored_server_side" \
  --data-urlencode "code=one_time_authorization_code" \
  --data-urlencode "redirect_uri=https://partner.example/oauth/callback" \
  --data-urlencode "code_verifier=original_pkce_verifier"

Response

{
  "access_token": "returned_once_redacted",
  "refresh_token": "returned_once_redacted",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "calls:read bookings:read"
}

Refresh an existing connection

Request

curl https://api.firstaiemployee.com/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=client_example" \
  --data-urlencode "client_secret=stored_server_side" \
  --data-urlencode "refresh_token=current_refresh_token"

Authorization flow

Authorization endpoint: GET /oauth/authorize.
Token endpoint: POST /oauth/token with application/x-www-form-urlencoded.
Resource endpoints accept OAuth Bearer access tokens only. Customer session cookies never authorize Client API requests.
Access token lifetime: 3,600 seconds.
Refresh tokens rotate and expire after 90 days of inactivity. Every successful refresh returns a replacement.
The confidential client secret has no automatic or owner-selected expiry. Operator-controlled rotation is separate from customer grant revocation.
The customer can disconnect the grant, which invalidates the integration.

Token response

Persist the new refresh token before discarding the old one. Presenting a rotated token again is treated as possible theft and can revoke the token family.

Client obligations

Keep confidential client secrets and refresh tokens in a server-side secrets store.
Validate state on the callback and send the original PKCE verifier during the code exchange.
Request only the scopes needed for the current feature.
On an expired-token 401, refresh once and retry once. Serialize refreshes for each connection and save both replacement tokens atomically. Reconnect if refresh is refused.
For 403, inspect the error code: a missing scope needs consent; a missing entitlement or denied operation needs the corresponding account access.

Core concepts

Pagination and time

Paginated lists return data and pagination metadata. Cursor behavior depends on the resource: calls, contacts, bookings, and reviews use offset pages; newer CRM and event resources use stable or signed cursors. No cursor is a cross-resource identifier or a promise of a frozen database snapshot.

Response

{
  "data": [
    {
      "id": "b50ff6fb-1f3a-4f4e-8462-07cbd6546f5f",
      "occurred_at": "2026-08-24T14:32:08.000Z",
      "caller": {
        "name": "Jordan Lee",
        "phone": "+15550100100"
      }
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "opaque_cursor_returned_by_server",
    "has_more": true
  }
}

Use the limit and filters documented for that endpoint. The base lists default to 50 records and allow 1 to 100; companion APIs can use different defaults.
Send the returned next_cursor unchanged. Never parse or construct a cursor.
Keep the same resource, account, sort, and filters when reusing a cursor. If it expires or returns invalid_cursor, restart that resource from the first page.
Deduplicate by stable id and reconcile periodically. Inserts and updates can change the records observed during a long sync.
Save a cursor only after its page commits at the destination. Complete periodic traversals or use a documented update filter. A previously seen id can still contain changed data.

Dates, times, and phone numbers

Most timestamps are UTC ISO 8601 strings. Booking starts_at and ends_at are local wall-clock strings without an offset; interpret them with the current time_zone returned by /me. Phone numbers are returned in E.164 where source data permits. Preserve the original field when your destination has stricter formatting.

Core concepts

Errors and retries

OAuth endpoints use error and error_description. Implemented v1 resource errors add a stable request_id for support. Client API limiters use the smaller { error } body, so retry logic must key off the HTTP status and Retry-After. Normal authenticated budgets are isolated by the verified client and business pair. Do not branch on human-readable descriptions.

Response

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token lacks the contacts:read scope.",
    "request_id": "req_01J..."
  }
}

HTTP	Meaning	Client action
`400`	Malformed request, unsupported field, or invalid OAuth exchange.	Fix the request. Do not retry unchanged.
`401`	Missing, expired, revoked, or otherwise invalid access token.	Refresh once, then reconnect if refresh fails.
`403`	Scope, account entitlement, or operation permission is missing.	Inspect the error code. Request the missing permission or account access.
`404`	The resource is absent or not visible to this tenant.	Treat as absent. Do not infer cross-tenant existence.
`409`	Revision, preview, or idempotency conflict; a request may already be running.	Read the code. Re-read and preview changed records. Retry an in-progress request with the same key and body.
`413`	Request body exceeds the allowed size.	Reduce the payload to the documented limit.
`428`	A required If-Match precondition is missing.	Read the current ETag and review the change before committing.
`429`	Rate limit exceeded.	Honor Retry-After and use exponential backoff with jitter.
`500 / 502 / 503`	Server or provider failure, or temporary unavailability.	Use bounded backoff. Retry writes only with their documented idempotency controls; otherwise reconcile first.

Resources

Calls

Calls are tenant-owned call-history projections. The calls:read scope exposes an allowlisted record with caller details, timing, outcome, intent, sentiment, services mentioned, follow-up state, spam status, summary, and transcript.

Response

{
  "id": "b50ff6fb-1f3a-4f4e-8462-07cbd6546f5f",
  "occurred_at": "2026-08-24T14:32:08.000Z",
  "caller": {
    "name": "Jordan Lee",
    "phone": "+15550100100"
  },
  "duration_seconds": 164,
  "outcome": "follow_up",
  "intent": "estimate",
  "sentiment": "neutral",
  "services_mentioned": "water heater",
  "follow_up_needed": true,
  "spam_status": "not_spam",
  "summary": "Caller asked for a water heater estimate.",
  "transcript": "..."
}

Sensitive text

Call summaries and transcripts can contain personal or sensitive free text. Minimize what you copy, encrypt it at rest, restrict destination access, and apply a documented retention period.

Contacts

Returns identity, notes, tags, classification, history, and recorded consent state. Requires contacts:read.

GET /reviews

Reviews

Returns platform, author, rating, text, analysis, and reply status. Requires reviews:read.

Resources

Bookings

The bookings:read scope returns booking projections with starts_at, ends_at, status, completed_at, and created_at. The official Client API has no booking write route in v1.

Request

curl "https://api.firstaiemployee.com/api/client/v1/bookings?limit=25" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Treat status as source data and preserve the original value before mapping it to a destination enum. A booking record does not by itself prove that a specific third-party calendar still contains an event.

Core concepts

Safe writes

Write controls depend on the operation. A write scope does not replace review of the change or a required precondition. Check the exact route in OpenAPI for its body, headers, and responses.

Read the current record. Keep its ETag and revision when the operation requires them.
Request a preview and review the changes, conflicts, and effects. A preview does not apply the change.
Commit only the reviewed change using the fields returned by that operation. Contacts use expected_revision and preview_key; tasks and Forms have their own contracts.
Where Idempotency-Key is required, use one key per logical change. Retry an uncertain result with the same key and body. Do not create a new key to hide a conflict.
If the revision changes or the preview expires, read and preview again before requesting renewed approval.

Contact preview, no write

curl "https://api.firstaiemployee.com/api/client/v1/crm/contacts:preview" \
  -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"phone":"+12025550142","name":"Example Contact"}'

Events

Webhooks

Event delivery should complement polling, not replace reconciliation. Consumers must be able to process an event more than once and should periodically compare against the source API.

What exists now

Registered Client API integrations can manage verified HTTPS webhook endpoints, receive signed allowlisted events, and inspect sanitized delivery history. Zapier keeps its separate partner-specific hook contract. Subscribable names include the signature.envelope lifecycle family, for example signature.envelope.completed.

Implemented

Operational boundary

Use webhooks:manage to register a public HTTPS URL and event_names. Save the signing_secret returned once. Within ten minutes, POST the returned verification_challenge as challenge to /webhooks/{id}/verify before delivery. Use events:read for event history and webhook_deliveries:read for sanitized delivery status. Delivery-history reads omit payloads, targets, signing references, and provider response bodies.

Request

curl "https://api.firstaiemployee.com/api/client/v1/webhooks" \
  -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://partner.example/events","event_names":["contact.created"]}'

curl "https://api.firstaiemployee.com/api/client/v1/webhooks/ENDPOINT_ID/verify" \
  -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"challenge":"verification_challenge_from_create_response"}'

Acknowledge with a 2xx response only after the event is durably queued.
Use the event id as the idempotency key. Duplicate deliveries must be harmless.
Verify X-Signature: t=<seconds>,v1=<hex>. Compute HMAC-SHA256 over the timestamp, a period, and the exact raw body bytes, using your endpoint signing secret. Compare signatures in constant time.
Reject timestamps outside a short replay window, such as 300 seconds. Verify before parsing JSON or applying business effects.

Data movement

Complete exports

The exports:read scope provides complete CSV portability across every field-allowlisted dataset already available to the account owner. The catalog spans calls, conversations, CRM, jobs, files, sales, tasks, reports, settings, custom fields, and their applicable history.

Implemented

Live with separate export approval

GET /exports returns the live catalog. GET /exports/{dataset}.csv streams a complete UTF-8 CSV. This broad surface is available only when the customer explicitly approves exports:read.

Request

curl "https://api.firstaiemployee.com/api/client/v1/exports" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

curl "https://api.firstaiemployee.com/api/client/v1/exports/jobs.csv" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: text/csv" \
  --output first-ai-employee-jobs.csv

Safe import sequence

Fetch the catalog and explicitly select reviewed dataset ids.
Download each CSV to temporary storage and require a complete connection close.
Validate headers, counts, JSON cells, time offsets, and required relationships.
Import into a staging table before promoting destination changes atomically.
Retry partial downloads from the beginning and delete staging files under the approved retention policy.

Data movement

Porting playbook

A reliable port is a checkpointed synchronization, not one large request. Start with the smallest useful resource set and record provenance in the destination.

1. Inventory

List required fields and decide whether each destination record is a snapshot, an event, or a mutable object.

2. Minimize

Request only the matching read scopes. Do not export recordings, free text, or phone numbers unless the destination actually needs them.

3. Backfill

Read the API's newest-first order in bounded pages. Commit one page atomically, then persist its cursor.

4. Catch up

Repeat from the checkpoint until lag is small. Overlap the final time window and deduplicate by source id.

5. Reconcile

Compare counts, time bounds, null handling, and a sample of source ids. Keep a failure queue for records that need manual mapping.

6. Operate

Use webhooks for low latency when supported, polling for repair, and an auditable disconnect and deletion procedure.

Recommended destination mapping

Source field	Destination field	Rule
`id`	`source_id`	Store verbatim and make unique with source_system.
`occurred_at`	`source_occurred_at`	Parse as UTC. Preserve precision.
`contact.phone`	`phone_e164`	Keep null distinct from an empty string.
`summary`	`source_summary`	Treat as sensitive free text. Do not use as a stable key.
`status`	`source_status`	Store the original value before mapping to local enums.
`business_name`	`source_account_label`	Display label only. Never use it as the tenant identifier.

Lifecycle

Versioning

The major version lives in the resource path. OAuth protocol endpoints remain unversioned. Successful resource responses also carry X-FAE-API-Version: v1. A new major version is required when a safe migration cannot preserve existing client behavior.

New optional response fields are compatible. Clients must ignore fields they do not understand.
New enum values are compatible. Store unknown values instead of rejecting the whole record.
Removing or renaming a field, changing its meaning, or making an optional field required is breaking.
Security fixes can change rejection behavior without a major version when preserving it would be unsafe.

Deprecation policy

V1 is live for approved integrations. A formal deprecation window will be documented before a breaking replacement. Draft and Reserved surfaces can still change before they become available.

Reference

Endpoint status

Complete application API catalog

The Client API includes the operations below, including those Zapier does not use. The public OpenAPI contracts describe parameters, request bodies, permissions, and responses without requiring sign-in. Every success response with a body includes a schema; some nested objects allow fields that depend on the resource. Calling the API still requires approved access, consent, and the relevant modules.

Private dashboard, administration, and infrastructure routes are not supported APIs for external applications and are excluded from this catalog.

Method	Path	Scope
`GET`	`/api/client/v1`	`oauth:authenticated`
`GET`	`/api/client/v1/me`	`oauth:authenticated`
`GET`	`/api/client/v1/openapi.json`	`oauth:authenticated`
`GET`	`/api/client/v1/calls`	`calls:read`
`GET`	`/api/client/v1/contacts`	`contacts:read`
`GET`	`/api/client/v1/crm/contacts`	`contacts:read`
`GET`	`/api/client/v1/crm/contacts/{id}`	`contacts:read`
`POST`	`/api/client/v1/crm/contacts:preview`	`contacts:write`
`POST`	`/api/client/v1/crm/contacts:commit`	`contacts:write`
`GET`	`/api/client/v1/forms`	`front_desk:forms:read or forms:lifecycle`
`POST`	`/api/client/v1/forms`	`forms:lifecycle`
`GET`	`/api/client/v1/forms/{id}`	`front_desk:forms:read or forms:lifecycle`
`DELETE`	`/api/client/v1/forms/{id}`	`forms:lifecycle`
`GET`	`/api/client/v1/forms/{formId}/scheduling`	`front_desk:forms:read`
`POST`	`/api/client/v1/forms/{id}:applyOperations`	`forms:write`
`POST`	`/api/client/v1/forms/validate`	`forms:write or forms:lifecycle`
`POST`	`/api/client/v1/forms/{id}/duplicate`	`forms:lifecycle`
`POST`	`/api/client/v1/forms/{id}/publish-preview`	`forms:lifecycle`
`POST`	`/api/client/v1/forms/{id}/publish`	`forms:lifecycle`
`POST`	`/api/client/v1/forms/{id}/close`	`forms:lifecycle`
`GET`	`/api/client/v1/forms/schema.json`	`front_desk:forms:read or forms:lifecycle`
`GET`	`/api/client/v1/forms/{formId}/responses`	`forms:responses:read`
`GET`	`/api/client/v1/forms/{formId}/responses/{responseId}`	`forms:responses:read`
`GET`	`/api/client/v1/forms/{formId}/analytics`	`forms:analytics:read`
`GET`	`/api/client/v1/forms/{formId}/insights`	`forms:analytics:read`
`POST`	`/api/client/v1/forms/{formId}/exports`	`exports:create`
`GET`	`/api/client/v1/forms/{formId}/exports/{exportId}`	`exports:read`
`GET`	`/api/client/v1/forms/{formId}/exports/{exportId}/download`	`exports:read`
`GET`	`/api/client/v1/payments/deposit-capability`	`bookings:read`
`POST`	`/api/client/v1/workflows/preview`	`automations:read`
`GET`	`/api/client/v1/bookings`	`bookings:read`
`GET`	`/api/client/v1/reviews`	`reviews:read`
`GET`	`/api/client/v1/client-accounts`	`client_accounts:read`
`GET`	`/api/client/v1/jobs`	`jobs:read`
`POST`	`/api/client/v1/jobs`	`jobs:write`
`GET`	`/api/client/v1/jobs/{id}`	`jobs:read`
`POST`	`/api/client/v1/jobs/{id}/cancel`	`jobs:write`
`POST`	`/api/client/v1/jobs/{id}/retry`	`jobs:write`
`GET`	`/api/client/v1/tasks`	`tasks:read`
`GET`	`/api/client/v1/requests`	`requests:read`
`GET`	`/api/client/v1/requests/{requestId}`	`requests:read`
`GET`	`/api/client/v1/pipeline-opportunities`	`pipeline_opportunities:read`
`GET`	`/api/client/v1/activities`	`activities:read`
`GET`	`/api/client/v1/saved-views`	`saved_views:read`
`GET`	`/api/client/v1/saved-views/{id}/results`	`saved_views:execute`
`GET`	`/api/client/v1/report-definitions`	`reports:read`
`GET`	`/api/client/v1/automation-executions`	`automations:read`
`GET`	`/api/client/v1/dashboard`	`dashboard:read`
`GET`	`/api/client/v1/events`	`events:read`
`GET`	`/api/client/v1/webhooks`	`webhooks:manage`
`POST`	`/api/client/v1/webhooks`	`webhooks:manage`
`GET`	`/api/client/v1/webhooks/{id}`	`webhooks:manage`
`DELETE`	`/api/client/v1/webhooks/{id}`	`webhooks:manage`
`POST`	`/api/client/v1/webhooks/{id}/verify`	`webhooks:manage`
`GET`	`/api/client/v1/webhook-deliveries`	`webhook_deliveries:read`
`GET`	`/api/client/v1/webhook-deliveries/{id}`	`webhook_deliveries:read`
`GET`	`/api/client/v1/crm/tasks`	`tasks:read`
`GET`	`/api/client/v1/crm/tasks/{id}`	`tasks:read`
`POST`	`/api/client/v1/crm/tasks/actions/create/preview`	`tasks:prepare`
`POST`	`/api/client/v1/crm/tasks/actions/create/commit`	`tasks:commit`
`POST`	`/api/client/v1/crm/tasks/{id}/actions/status/preview`	`tasks:prepare`
`POST`	`/api/client/v1/crm/tasks/{id}/actions/status/commit`	`tasks:commit`
`GET`	`/api/client/v1/document-templates`	`documents:read`
`GET`	`/api/client/v1/document-templates/{id}`	`documents:read`
`GET`	`/api/client/v1/signature-envelopes`	`signatures:read`
`GET`	`/api/client/v1/signature-envelopes/{id}`	`signatures:read`
`GET`	`/api/client/v1/exports`	`exports:read`
`GET`	`/api/client/v1/exports/{dataset}.csv`	`exports:read`
`GET`	`/api/client/v1/forms/openapi.json`	`front_desk:forms:read`
`GET`	`/api/client/v1/crm/notes`	`activities:read`
`POST`	`/api/client/v1/crm/notes/actions/create/preview`	`activities:write`
`POST`	`/api/client/v1/crm/notes/actions/create/commit`	`activities:write`
`GET`	`/api/client/v1/crm/jobs`	`jobs:read`
`GET`	`/api/client/v1/crm/jobs/{id}`	`jobs:read`
`POST`	`/api/client/v1/crm/jobs/actions/create/preview`	`jobs:write`
`POST`	`/api/client/v1/crm/jobs/actions/create/commit`	`jobs:write`
`POST`	`/api/client/v1/crm/jobs/{id}/actions/lifecycle/preview`	`jobs:write`
`POST`	`/api/client/v1/crm/jobs/{id}/actions/lifecycle/commit`	`jobs:write`

Open an operation for its inputs and responses. Follow named schema links for field definitions. Descriptions and wire names come directly from the published contract.

GET /API discovery

Link to this operation

Authentication and scopes: OAuth2: authenticated

Responses

200

Version and resource links.

application/jsonApiDiscovery

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

GET /meCurrent tenant and grant

Link to this operation

Authentication and scopes: OAuth2: authenticated

Responses

200

The tenant selected by the bearer grant.

application/jsonCurrentClient

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

GET /openapi.jsonOpenAPI document

Link to this operation

Authentication and scopes: OAuth2: authenticated

Responses

200

This OpenAPI 3.1 document.

application/jsonOpenApiDocument

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

GET /callscalls

Link to this operation

Authentication and scopes: OAuth2: calls:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Call
meta · required: PageMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /contactscontacts

Link to this operation

Authentication and scopes: OAuth2: contacts:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Contact
meta · required: PageMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /crm/contactsCRM contacts

Link to this operation

Authentication and scopes: OAuth2: contacts:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 25

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

email · query · optional

string

maxLength: 255

phone · query · optional

string

maxLength: 50

updated_since · query · optional

string

format: "date-time"

fields · query · optional

Optional comma-separated selection: id, name, phone, email, notes, tags, classification, total_jobs, lifetime_value, consent, first_seen_at, last_seen_at, created_at, updated_at, lead_source, lifecycle_stage, qualification, revision.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required

array

Array items: CrmContact

page · required

object

next_cursor · required: string | null
has_more · required: boolean

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /crm/contacts/{id}Read one CRM contact

Link to this operation

Authentication and scopes: OAuth2: contacts:read

Parameters

id · path · required

string

format: "uuid"

fields · query · optional

string

Responses

200

The tenant-owned CRM contact and its strong ETag.

Response headers

ETag

string

application/json

object

data · required: CrmContact
meta · required: object

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Contact not found in this tenant.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/contacts:previewPreview a CRM contact create or update without changing data

Link to this operation

Authentication and scopes: OAuth2: contacts:write

Request body · required

application/jsonCrmContactInput

Responses

200

Exact before/after preview and commit binding.

application/json

object

data · required

ContactUpsertPreview

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/contacts:commitCommit a previously previewed CRM contact create or update

Link to this operation

Authentication and scopes: OAuth2: contacts:write

Parameters

Idempotency-Key · header · required

string

minLength: 8
maxLength: 256

If-Match · header · optional

Required for updates; use the ETag returned by GET or preview.

string

Request body · required

application/json

object

Only the listed fields are accepted.

phone · required: string
minLength: 1
maxLength: 50
email · optional: string
maxLength: 255
name · optional: string
maxLength: 255
expected_revision · required: integer | null
minimum: 1
preview_key · optional: string | null

Responses

200

Existing contact updated or already current.

Response headers

ETag

string

application/json

object

data · required

CrmContact

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
outcome · required: string

201

Contact created.

Response headers

Location

string

ETag

string

application/json

object

data · required

CrmContact

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
outcome · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

409

Idempotency, preview, or revision conflict.

428

If-Match is required for an update.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /formsforms

Link to this operation

Authentication and scopes: OAuth2: front_desk:forms:read OR OAuth2: forms:lifecycle

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 25

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

status · query · optional

Schema

enum: ["draft","published","closed"]

updated_since · query · optional

string

format: "date-time"

fields · query · optional

Optional comma-separated selection: id, ref, title, status, version, received_responses, created_at, updated_at, published_at, draft_revision.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required

array

Array items: FormsAuthoringForm

page · required

object

next_cursor · required: string | null
has_more · required: boolean

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /formsCreate an unpublished form draft

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. One Idempotency-Key (16 to 128 chars) binds the tenant, client, grant, operation, and canonical request; exact retries replay for 24 hours.

Authentication and scopes: OAuth2: forms:lifecycle

Parameters

Idempotency-Key · header · required

One value only. Same request replays; different request returns 409.

string

pattern: "^[A-Za-z0-9._:-]{16,128}$"

Request body · required

application/json

object

Only the listed fields are accepted.

definition · required: object
ref · optional: string
maxLength: 64

Responses

201

Unpublished draft created.

Response headers

Location

string

ETag

string

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringForm
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

409

Idempotency key mismatch, concurrent in-flight request, or deterministic command conflict.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/{id}Read one form draft definition

Link to this operation

Authentication and scopes: OAuth2: front_desk:forms:read OR OAuth2: forms:lifecycle

Parameters

id · path · required

string

format: "uuid"

fields · query · optional

Optional comma-separated selection: id, ref, title, status, version, received_responses, created_at, updated_at, published_at, draft_revision, definition. Select definition explicitly to retrieve the draft. id is always included.

string

Responses

200

The tenant-owned form and strong draft ETag.

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringForm
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

DELETE /forms/{id}Delete only a never-published empty draft

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and the current strong ETag plus canonical draft revision. Only an empty never-published draft can be deleted; published forms and response history are out of scope.

Authentication and scopes: OAuth2: forms:lifecycle

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

string

pattern: "^[A-Za-z0-9._:-]{16,128}$"

If-Match · header · required

One current strong ETag. The body must also contain the current draft revision.

string

pattern: "^\"v1:[a-f0-9]{32}\"$"

Request body · required

application/json

object

Only the listed fields are accepted.

expected_draft_revision · required: string
format: "date-time"

Responses

200

Empty never-published draft deleted.

Response headers

ETag

string

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringDeleted
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

409

Idempotency, revision, or delete-policy conflict.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/{formId}/schedulingRead bounded scheduling configuration

Link to this operation

Returns sanitized scheduler-question settings from the current form draft. It does not query provider availability or create a booking.

Authentication and scopes: OAuth2: front_desk:forms:read

Parameters

formId · path · required

string

format: "uuid"

Responses

200

Scheduler fields and explicit no-provider-effect markers.

application/json

object

data · required

FormScheduling

meta · required

object

request_id · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /forms/{id}:applyOperationsApply a closed batch of edit operations to one form draft

Link to this operation

Authentication and scopes: OAuth2: forms:write

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

string

minLength: 8
maxLength: 256

If-Match · header · required

Strong ETag returned by GET /forms/{id}.

string

Request body · required

application/json

object

Only the listed fields are accepted.

version · required: integer
const: 1
operations · required: array
minItems: 1
maxItems: 100
Array items:
object
expected_draft_revision · required: string
format: "date-time"

Responses

200

Saved draft, operation summary, and exact diff.

Response headers

ETag

string

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringApplied
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

409

Draft revision, idempotency, or operation conflict.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /forms/validateValidate a form definition without persisting

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, and a forms:write or owner-consented forms:lifecycle grant. Canonical semantic validation only; a valid document is not a publication approval.

Authentication and scopes: OAuth2: forms:write OR OAuth2: forms:lifecycle

Request body · required

application/json

object

Only the listed fields are accepted.

definition · required: object

Responses

200

Semantic validation result; publication_authorized is always false.

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringValidation
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /forms/{id}/duplicateCopy a definition into a new draft

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. New draft carries stable child refs and no responses.

Authentication and scopes: OAuth2: forms:lifecycle

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

string

pattern: "^[A-Za-z0-9._:-]{16,128}$"

If-Match · header · required

One current strong ETag. The body must also contain the current draft revision.

string

pattern: "^\"v1:[a-f0-9]{32}\"$"

Request body · required

application/json

object

Only the listed fields are accepted.

ref · required: string
maxLength: 64
title · optional: string
maxLength: 300
expected_draft_revision · required: string
format: "date-time"

Responses

201

New draft duplicated.

Response headers

Location

string

ETag

string

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringForm
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

409

Idempotency, revision, or duplicate conflict.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /forms/{id}/publish-previewReview the exact publish candidate

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. No publication occurs. Preview receipts expire after ten minutes; reuse the same Idempotency-Key for publication.

Authentication and scopes: OAuth2: forms:lifecycle

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

string

pattern: "^[A-Za-z0-9._:-]{16,128}$"

If-Match · header · required

One current strong ETag. The body must also contain the current draft revision.

string

pattern: "^\"v1:[a-f0-9]{32}\"$"

Request body · required

application/json

object

Only the listed fields are accepted.

expected_draft_revision · required: string
format: "date-time"
expected_published_version · required: integer
minimum: 0

Responses

200

Exact publish candidate and expiring preview receipt.

Response headers

ETag

string

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringPreparedPreview
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

409

Idempotency, revision, or review-gate conflict.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /forms/{id}/publishPublish the approved preview as a new revision

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. Requires the preview receipt, unchanged revisions, and confirmed:true. Never publish automatically from validation.

Authentication and scopes: OAuth2: forms:lifecycle

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

Reuse the preview key. Same request replays; different request returns 409.

string

pattern: "^[A-Za-z0-9._:-]{16,128}$"

If-Match · header · required

One current strong ETag. The body must also contain the current draft revision.

string

pattern: "^\"v1:[a-f0-9]{32}\"$"

Request body · required

application/json

object

Only the listed fields are accepted.

expected_draft_revision · required: string
format: "date-time"
expected_published_version · required: integer
minimum: 0
preview_receipt · required: string
minLength: 40
maxLength: 2000
confirmed · required: Schema
const: true

Responses

200

New immutable published revision.

Response headers

ETag

string

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringForm
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

409

Idempotency, revision, receipt, or review-gate conflict.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /forms/{id}/closeStop collection without deleting history

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, and an owner-consented forms:lifecycle grant. Close remains available after module deactivation; history is retained.

Authentication and scopes: OAuth2: forms:lifecycle

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

string

pattern: "^[A-Za-z0-9._:-]{16,128}$"

If-Match · header · required

One current strong ETag. The body must also contain the current draft revision.

string

pattern: "^\"v1:[a-f0-9]{32}\"$"

Request body · required

application/json

object

Only the listed fields are accepted.

expected_draft_revision · required: string
format: "date-time"

Responses

200

Form closed; history retained.

Response headers

ETag

string

application/json

object

Only the listed fields are accepted.

data · required: FormsAuthoringForm
meta · required: FormsAuthoringMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

409

Idempotency, revision, or lifecycle-state conflict.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/schema.jsonRead the Forms authoring structural schema

Link to this operation

Requires CLIENT_API_ENABLED=on, a registered client, and a forms read or owner-consented forms:lifecycle grant. Structural checks only; POST /forms/validate runs the canonical semantic validator. The versioned Forms authoring OpenAPI companion (getFormsAuthoringContract) lives at GET /forms/openapi.json and is cross-linked here rather than duplicated.

Authentication and scopes: OAuth2: front_desk:forms:read OR OAuth2: forms:lifecycle

Responses

200

Structural JSON Schema versioned in $comment.

application/json

object

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/{formId}/responsesList form responses with stable historical columns

Link to this operation

Newest-first tenant-scoped keyset page. The opaque cursor is bound to this form and the complete filter fingerprint; unknown query parameters are rejected.

Authentication and scopes: OAuth2: forms:responses:read

Parameters

formId · path · required

string

format: "uuid"

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor issued for this exact form and filter.

string

status · query · optional

Comma-separated partial, completed, or spam states. Defaults to partial,completed.

string

from · query · optional

Inclusive YYYY-MM-DD in the tenant time zone or a full ISO timestamp.

string

to · query · optional

Exclusive YYYY-MM-DD in the tenant time zone or a full ISO timestamp; must follow from.

string

ending · query · optional

Ending reference from the form definition.

string

pattern: "^[a-z0-9_-]{1,64}$"

revision · query · optional

Published version number, or any.

string

q · query · optional

Free-text search over text, email, and phone answers only.

string

maxLength: 200

fields · query · optional

JSON-encoded array of at most 20 {ref, op, value} field predicates.

string

tag · query · optional

JSON-encoded {op, value} tag predicate.

string

owner_status · query · optional

string

enum: ["new","in_review","done"]

correction_state · query · optional

string

enum: ["corrected","uncorrected"]

Responses

200

Response page, filter definition, total count, and stable current-plus-historical column descriptors.

application/jsonFormResponseCollection

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

application/jsonError

413

Historical revision, unknown-field, or stable-column reconstruction exceeds the public bound.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/{formId}/responses/{responseId}Read one form response

Link to this operation

Returns one tenant- and form-bound response with the same stable column descriptors as the list route. No query parameters are accepted.

Authentication and scopes: OAuth2: forms:responses:read

Parameters

formId · path · required

string

format: "uuid"

responseId · path · required

string

format: "uuid"

Responses

200

Response and stable current-plus-historical column descriptors.

application/jsonFormResponseResource

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form or response not found in this tenant.

application/jsonError

413

Historical revision, unknown-field, or stable-column reconstruction exceeds the public bound.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/{formId}/analyticsRead revision-pinned form analytics

Link to this operation

Deterministic branch-aware analytics. Every metric includes its numerator, denominator, definition, and exclusions; synthetic responses are excluded. Only revision_id is accepted.

Authentication and scopes: OAuth2: forms:analytics:read

Parameters

formId · path · required

string

format: "uuid"

revision_id · query · required

Immutable form revision to analyze.

string

format: "uuid"

Responses

200

Revision-pinned analytics for at most 200 questions.

application/jsonFormAnalyticsResource

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form revision not found in this tenant.

application/jsonError

413

The revision exceeds the bounded analytics population.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/{formId}/insightsList stored evidence-backed form insights

Link to this operation

Reads unexpired tenant-owned insight artifacts with their source population fingerprint and row counts. It never invokes a model or creates a new insight.

Authentication and scopes: OAuth2: forms:analytics:read

Parameters

formId · path · required

string

format: "uuid"

limit · query · optional

integer

minimum: 1
maximum: 50
default: 20

Responses

200

Stored insight artifacts and evidence citations.

application/json

object

data · required

array

Array items: StoredFormInsight

meta · required

object

request_id · required: string
limit · required: integer
generated_new_insight · required: Schema
const: false

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /forms/{formId}/exportsCreate an idempotent frozen form-response export

Link to this operation

Creates CSV or XLSX bytes from a response population and stable column manifest frozen in one transaction at request time. Unknown body, filter, and query keys are rejected.

Authentication and scopes: OAuth2: exports:create

Parameters

formId · path · required

string

format: "uuid"

Idempotency-Key · header · required

Durably bound to the tenant, grant, client, operation, path, and canonical request. Same request replays; different request returns 409.

string

minLength: 8
maxLength: 255
pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{7,254}$"

Request body · required

application/jsonFormExportRequest

Responses

202

Frozen export created, or a completed idempotent response replayed.

Response headers

Idempotency-Replayed

true only when replaying the stored response.

string

enum: ["true"]

application/jsonFormExportResource

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Form not found in this tenant.

application/jsonError

409

Idempotency key mismatch, concurrent in-flight request, or deterministic command conflict.

Response headers

Retry-After

Present while an equivalent request is still in flight.

string

application/jsonError

413

The frozen manifest or export population exceeds the public bound.

application/jsonError

429

Client API rate limit exceeded, or five exports are already queued or running for this tenant.

Response headers

Retry-After

string

application/json

Schema

oneOf

RateLimitError

Error

GET /forms/{formId}/exports/{exportId}Read form export status

Link to this operation

Returns tenant-bound lifecycle and progress metadata only. No object keys, file bytes, download URLs, or query parameters.

Authentication and scopes: OAuth2: exports:read

Parameters

formId · path · required

string

format: "uuid"

exportId · path · required

string

format: "uuid"

Responses

200

Current export metadata.

application/jsonFormExportResource

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Export not found in this tenant and form.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/{formId}/exports/{exportId}/downloadDownload a completed form export once

Link to this operation

Atomically consumes the export one-time download and returns CSV or XLSX bytes directly. The job must be ready, unexpired, and not previously downloaded; no permanent URL is returned.

Authentication and scopes: OAuth2: exports:read

Parameters

formId · path · required

string

format: "uuid"

exportId · path · required

string

format: "uuid"

Responses

200

Completed attachment. A successful response consumes the one-time download.

Response headers

Content-Disposition

Server-generated attachment filename.

string

Cache-Control

string

const: "no-store"

text/csv

string

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

string

format: "binary"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Export not found in this tenant and form.

application/jsonError

409

Export is not ready.

application/jsonError

410

Export expired or its one-time download was already consumed. Both use the generic not_found error body.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /payments/deposit-capabilityRead deposit-link capability state

Link to this operation

Reports whether the business-owned deposit-link lane is configured. It never returns the payment URL, charges, refunds, or confirms settlement.

Authentication and scopes: OAuth2: bookings:read

Responses

200

Provider-free payment capability state.

application/json

object

data · required

DepositCapability

meta · required

object

request_id · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /workflows/previewPreview a bounded CRM workflow rule

Link to this operation

Validates and evaluates one closed workflow rule against exact supplied facts. The deterministic response includes an idempotency basis and never executes an action.

Authentication and scopes: OAuth2: automations:read

Request body · required

application/json

object

Responses

200

Deterministic preview-only evaluation.

application/json

object

data · required

WorkflowPreview

meta · required

object

request_id · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /bookingsbookings

Link to this operation

Authentication and scopes: OAuth2: bookings:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Booking
meta · required: PageMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /reviewsreviews

Link to this operation

Authentication and scopes: OAuth2: reviews:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Review
meta · required: PageMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /client-accountsclient accounts

Link to this operation

Authentication and scopes: OAuth2: client_accounts:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: ClientAccount
meta · required: PageMeta

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Northside Property Group",
      "status": "active"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /jobsjobs

Link to this operation

Authentication and scopes: OAuth2: jobs:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

from · query · optional

Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

to · query · optional

Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Job
meta · required: PageMeta

{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "title": "Water heater repair",
      "status": "scheduled"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /jobsPrepare one bounded asynchronous Client API job

Link to this operation

Authentication and scopes: OAuth2: jobs:write

Parameters

Idempotency-Key · header · required

string

minLength: 8
maxLength: 256

Request body · required

application/jsonClientApiJobCreateRequest

Responses

202

Queued job status. Repeating the same idempotency key and request replays the same job.

Response headers

ETag

string

application/jsonClientApiJobResource

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

409

Idempotency key conflicts with a different request.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /jobs/{id}Read one asynchronous Client API job

Link to this operation

Authentication and scopes: OAuth2: jobs:read

Parameters

id · path · required

string

format: "uuid"

If-None-Match · header · optional

string

Responses

200

Tenant and grant-bound job status with an opaque result manifest.

Response headers

ETag

string

application/jsonClientApiJobResource

304

The job version has not changed.

Response headers

ETag

string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Job not found for this tenant and grant.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /jobs/{id}/cancelCancel one queued or running asynchronous job

Link to this operation

Authentication and scopes: OAuth2: jobs:write

Parameters

id · path · required

string

format: "uuid"

If-Match · header · required

string

Responses

200

Cancelled job status.

Response headers

ETag

string

application/jsonClientApiJobResource

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Job not found.

409

The version or lifecycle state is no longer cancellable.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /jobs/{id}/retryRetry one retryable failed asynchronous job

Link to this operation

Authentication and scopes: OAuth2: jobs:write

Parameters

id · path · required

string

format: "uuid"

If-Match · header · required

string

Responses

200

Queued retry status.

Response headers

ETag

string

application/jsonClientApiJobResource

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Job not found.

409

The version or lifecycle state is not retryable.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /taskstasks

Link to this operation

Authentication and scopes: OAuth2: tasks:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

from · query · optional

Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

to · query · optional

Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Task
meta · required: PageMeta

{
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "title": "Confirm access window",
      "status": "open"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /requestsrequests

Link to this operation

Authentication and scopes: OAuth2: requests:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Request
meta · required: PageMeta

{
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333334",
      "summary": "Needs an estimate",
      "status": "open"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /requests/{requestId}Read one Request with its bounded public conversation

Link to this operation

Authentication and scopes: OAuth2: requests:read

Parameters

requestId · path · required

string

format: "uuid"

Responses

200

The tenant-owned Request and at most its latest 100 public messages.

application/json

object

Only the listed fields are accepted.

data · required

RequestDetail

meta · required

object

Only the listed fields are accepted.

version · required: string
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Request not found in this tenant.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /pipeline-opportunitiespipeline opportunities

Link to this operation

Authentication and scopes: OAuth2: pipeline_opportunities:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

pipeline_key · query · required

string

maxLength: 48

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: PipelineOpportunity
meta · required: PageMeta

{
  "data": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "pipeline_key": "sales",
      "stage_key": "qualified",
      "title": "Boiler replacement"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /activitiesactivities

Link to this operation

Authentication and scopes: OAuth2: activities:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

from · query · optional

Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

to · query · optional

Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: Activity
meta · required: PageMeta

{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "event_type": "job.changed",
      "occurred_at": "2026-08-26T12:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /saved-viewssaved views

Link to this operation

Authentication and scopes: OAuth2: saved_views:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

from · query · optional

Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

to · query · optional

Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: SavedView
meta · required: PageMeta

{
  "data": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "key": "open_jobs",
      "label": "Open jobs",
      "resource": "jobs",
      "revision": 2
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /saved-views/{id}/resultsRun one saved view without changing it

Link to this operation

Authentication and scopes: OAuth2: saved_views:execute

Parameters

id · path · required

string

format: "uuid"

revision · query · required

integer

minimum: 1

cursor · query · optional

string

Responses

200

A source-revision-pinned saved-view result page.

application/json

object

data · required

array

Array items:

object

resource · required: string | null
record_id · required: string | null
display_label · required: string | null
secondary_label · required: string | null
state_label · required: string | null
created_at · required: string | null
updated_at · required: string | null

meta · required

object

limit · required: integer
has_more · required: boolean
next_cursor · required: string | null
data_revision · required: string
saved_view · required: SavedView

{
  "data": [
    {
      "resource": "jobs",
      "record_id": "22222222-2222-4222-8222-222222222222",
      "display_label": "Water heater repair",
      "secondary_label": null,
      "state_label": "scheduled",
      "created_at": null,
      "updated_at": null
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null,
    "data_revision": "42",
    "saved_view": {
      "id": "66666666-6666-4666-8666-666666666666",
      "key": "open_jobs",
      "label": "Open jobs",
      "resource": "jobs",
      "revision": 2
    }
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Saved view not found.

409

Saved view revision changed.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /report-definitionsreport definitions and latest successful runs

Link to this operation

Authentication and scopes: OAuth2: reports:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: ReportDefinition
meta · required: PageMeta

{
  "data": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "version": 1,
      "name": "Open work by status",
      "resource": "jobs",
      "latest_successful_run": null
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /automation-executionsrecent automation execution summaries

Link to this operation

Authentication and scopes: OAuth2: automations:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

from · query · optional

Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

to · query · optional

Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from.

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: AutomationExecution
meta · required: PageMeta

{
  "data": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "rule_id": "99999999-9999-4999-8999-999999999999",
      "rule_version": 3,
      "status": "succeeded"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /dashboardDashboard overview

Link to this operation

Authentication and scopes: OAuth2: dashboard:read

Responses

200

A compact operational overview.

application/json

object

data · required

object

business · required

object

name · required: string | null

ai_employee · required

object

name · required: string | null
status · required: string | null

today · required

object

messages · required: number
voice_minutes · required: number
appointments · required: number

channels · required

object

messenger · required: boolean
whatsapp · required: boolean
instagram · required: boolean
phone · required: boolean
email · required: boolean
calendar · required: boolean

{
  "data": {
    "business": {
      "name": "Acme Plumbing"
    },
    "ai_employee": {
      "name": "Acme Assistant",
      "status": "active"
    },
    "today": {
      "messages": 4,
      "voice_minutes": 12,
      "appointments": 1
    },
    "channels": {
      "messenger": false,
      "whatsapp": false,
      "instagram": false,
      "phone": true,
      "email": false,
      "calendar": true
    }
  }
}

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /eventsAPI events

Link to this operation

Authentication and scopes: OAuth2: events:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: ApiEvent
meta · required: PageMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /webhooksList verified webhook endpoints

Link to this operation

Authentication and scopes: OAuth2: webhooks:manage

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

Tenant-scoped webhook endpoints.

application/json

object

data · required

array

Array items: WebhookEndpoint

page · required

object

next_cursor · required: string | null
has_more · required: boolean

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /webhooksCreate a webhook endpoint and one-time verification challenge

Link to this operation

Authentication and scopes: OAuth2: webhooks:manage

Request body · required

application/json

object

Only the listed fields are accepted.

url · required: string
format: "uri"
maxLength: 2048
event_names · required: array
minItems: 1
maxItems: 64
Array items:
string
"signature.envelope.completed"

Responses

201

Endpoint, one-time signing secret, and verification challenge.

application/json

object

data · required

ProvisionedWebhookEndpoint

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /webhooks/{id}Read one webhook endpoint

Link to this operation

Authentication and scopes: OAuth2: webhooks:manage

Parameters

id · path · required

string

format: "uuid"

Responses

200

Webhook endpoint.

application/json

object

data · required

WebhookEndpoint

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Endpoint not found.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

DELETE /webhooks/{id}Remove one webhook endpoint

Link to this operation

Authentication and scopes: OAuth2: webhooks:manage

Parameters

id · path · required

string

format: "uuid"

Responses

204

Endpoint removed.

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Endpoint not found.

409

Endpoint lifecycle conflict.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /webhooks/{id}/verifyVerify and activate a webhook endpoint

Link to this operation

Authentication and scopes: OAuth2: webhooks:manage

Parameters

id · path · required

string

format: "uuid"

Request body · required

application/json

object

Only the listed fields are accepted.

challenge · required: string
minLength: 32
maxLength: 128

Responses

200

Verified active endpoint.

application/json

object

data · required

WebhookEndpoint

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Endpoint not found.

409

Challenge expired, replayed, or raced.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /webhook-deliveriesList sanitized webhook delivery status

Link to this operation

Authentication and scopes: OAuth2: webhook_deliveries:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

endpoint_id · query · optional

string

format: "uuid"

state · query · optional

string

enum: ["pending","leased","failed_retryable","delivered","dead_letter"]

Responses

200

Tenant-scoped delivery metadata with a sanitized latest attempt; event payloads, endpoint URLs, signing material, provider bodies, and lease identities are never returned.

application/json

object

data · required

array

Array items: WebhookDelivery

page · required

object

next_cursor · required: string | null
has_more · required: boolean

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /webhook-deliveries/{id}Read sanitized webhook delivery attempt history

Link to this operation

Authentication and scopes: OAuth2: webhook_deliveries:read

Parameters

id · path · required

string

format: "uuid"

Responses

200

One tenant-scoped delivery and at most 50 sanitized settled attempts.

application/json

object

data · required

WebhookDeliveryDetail

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Delivery not found.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /crm/tasksCRM tasks

Link to this operation

Authentication and scopes: OAuth2: tasks:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 25

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

status · query · optional

Schema

enum: ["open","done","canceled"]

contact_id · query · optional

string

format: "uuid"

job_id · query · optional

string

format: "uuid"

overdue · query · optional

true selects open tasks past due; combining it with a non-open status is refused. false applies no overdue filter.

boolean

default: false

fields · query · optional

Optional comma-separated selection: id, title, description, status, priority, due_at, contact_id, job_id, owner, completed_at, created_at, updated_at, revision.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required

array

Array items: CrmTask

page · required

object

next_cursor · required: string | null
has_more · required: boolean

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /crm/tasks/{id}Read one CRM task

Link to this operation

Authentication and scopes: OAuth2: tasks:read

Parameters

id · path · required

string

format: "uuid"

fields · query · optional

Optional comma-separated selection: id, title, description, status, priority, due_at, contact_id, job_id, owner, completed_at, created_at, updated_at, revision.

string

Responses

200

Tenant-owned task with a strong ETag.

Response headers

ETag

string

application/json

object

data · required

CrmTask

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Task not found.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/tasks/actions/create/previewPreview one CRM task creation

Link to this operation

Authentication and scopes: OAuth2: tasks:prepare

Request body · required

application/jsonTaskCreateInput

Responses

200

Exact no-effect preview and commit key.

application/json

object

data · required

TaskCreatePreview

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/tasks/actions/create/commitCommit one reviewed CRM task creation

Link to this operation

Authentication and scopes: OAuth2: tasks:commit

Parameters

Idempotency-Key · header · required

string

minLength: 8
maxLength: 256

Request body · required

application/json

object

Only the listed fields are accepted.

title · required: string
minLength: 1
maxLength: 200
description · optional: string | null
due_at · optional: string | null
priority · optional: string
enum: ["low","normal","high"]
contact_id · optional: string | null
job_id · optional: string | null
owner · optional: object
preview_key · required: string
minLength: 16
maxLength: 200
confirmed · required: Schema
const: true

Responses

201

Task created once.

application/json

object

data · required

CrmTask

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
outcome · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

409

Preview or idempotency conflict.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/tasks/{id}/actions/status/previewPreview a CRM task open or done transition

Link to this operation

Authentication and scopes: OAuth2: tasks:prepare

Parameters

id · path · required

string

format: "uuid"

Request body · required

application/jsonTaskStatusInput

Responses

200

Exact no-effect status preview, ETag, and commit key.

application/json

object

data · required

TaskStatusPreview

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Task not found.

409

Task revision or state conflict.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/tasks/{id}/actions/status/commitCommit a reviewed CRM task status transition

Link to this operation

Authentication and scopes: OAuth2: tasks:commit

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

string

minLength: 8
maxLength: 256

If-Match · header · required

string

Request body · required

application/json

object

Only the listed fields are accepted.

target_status · required: string
enum: ["open","done"]
expected_revision · required: integer
minimum: 1
preview_key · required: string
minLength: 16
maxLength: 200
confirmed · required: Schema
const: true

Responses

200

Task status changed once.

application/json

object

data · required

CrmTask

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
outcome · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

409

Preview, state, revision, or idempotency conflict.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /document-templatesdocument templates

Link to this operation

Authentication and scopes: OAuth2: documents:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 25

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: DocumentTemplate
meta · required: PageMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /document-templates/{id}Read one document template

Link to this operation

Authentication and scopes: OAuth2: documents:read

Parameters

id · path · required

string

format: "uuid"

Responses

200

Template and immutable version layouts without storage identifiers.

application/json

object

data · required

DocumentTemplate

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Template not found.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /signature-envelopessignature envelopes

Link to this operation

Authentication and scopes: OAuth2: signatures:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 50

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

Responses

200

A tenant-scoped page.

application/json

object

data · required: array
Array items: SignatureEnvelope
meta · required: PageMeta

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /signature-envelopes/{id}Read one signature envelope status

Link to this operation

Authentication and scopes: OAuth2: signatures:read

Parameters

id · path · required

string

format: "uuid"

If-None-Match · header · optional

string

Responses

200

Envelope lifecycle and retention status without recipients, signer tokens, fields, evidence details, artifacts, storage identifiers, or actor labels.

Response headers

ETag

string

application/json

object

data · required

SignatureEnvelope

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

304

The version-derived ETag still matches.

Response headers

ETag

string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

Envelope not found.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /exportsList every available portability dataset

Link to this operation

Authentication and scopes: OAuth2: exports:read

Responses

200

The complete field-allowlisted CSV export catalog.

application/jsonExportCatalog

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /exports/{dataset}.csvStream one complete tenant dataset as CSV

Link to this operation

Authentication and scopes: OAuth2: exports:read

Parameters

dataset · path · required

Dataset id returned by GET /exports.

string

enum: ["calls","call-insight-reviews","callers","lead-lifecycle-history","lead-reason-sets","lead-import-history","chats","messages","webchat-resolution-feedback","taken-messages","bookings","internal-calendar-events","reviews","client-accounts","account-relationships","account-command-history","jobs","fulfillment-operations","fulfillment-outbox","call-outcomes","call-outcome-steps","equipment","equipment-service-history","equipment-service-evidence","job-status-links","delivery-templates","delivery-plans","delivery-items","delivery-dependencies","delivery-blockers","delivery-history","tasks","task-reminders","task-reminder-deliveries","team-workload-revision","team-queues","team-queue-memberships","team-queue-resources","team-queue-watchers","task-assignment-history","resource-assignment-history","team-threads","team-messages","team-mentions","team-notifications","team-notification-preferences","push-devices","team-command-history","crm-activity","crm-timeline","business-files","business-file-sources","business-file-revisions","business-file-publications","intake-media","attachments","signature-envelopes","signature-recipients","signature-fields","signature-field-values","signature-events","signature-artifacts","signature-templates","signature-verifications","signature-bulk-batches","signature-bulk-items","sales-pipeline-definitions","sales-opportunities","sales-opportunity-history","crm-duplicate-candidates","crm-duplicate-dismissed-pairs","crm-forecast-snapshots","crm-import-mapping-profiles","crm-import-dry-run-fingerprints","sla-policies","sla-ticket-clocks","sla-ticket-clock-pauses","crm-account-classifications","crm-account-segments","csat-survey-definitions","csat-survey-invitations","csat-survey-responses","crm-relationship-edges","territories","territory-visit-events","portal-access-grants","config-draft-versions","config-activations","crm-partner-account-attributes","crm-partner-contacts","crm-partner-onboarding-events","crm-partner-lead-registrations","crm-partner-lead-events","crm-contact-identities","crm-contact-merge-aliases","tenant-referrals","tenant-referral-events","incentive-plan-versions","incentive-period-versions","incentive-period-participants","incentive-revenue-credits","incentive-revenue-credit-splits","incentive-adjustments","incentive-statements","crm-layout-visibility-conditions","crm-layout-approved-actions","crm-report-definitions","crm-report-runs","crm-report-result-rows","crm-report-memberships","crm-report-command-history","custom-field-definitions","custom-field-values","custom-field-definition-history","custom-field-value-history","custom-field-command-history","record-layout-history","customer-cases","customer-case-messages","customer-case-events","customer-case-reply-snippets","service-area-settings","public-faqs","faq-disclosures","consented-visitor-activity","saved-views","search-saved-views","quote-templates","settings"]

Responses

200

A UTF-8 CSV attachment streamed in bounded-memory pages.

text/csv

string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The dataset id is not part of the export catalog.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /forms/openapi.jsonRead the Forms authoring OpenAPI contract

Link to this operation

Authentication and scopes: OAuth2: front_desk:forms:read

Responses

200

The Forms OpenAPI 3.1 companion document.

application/jsonOpenApiDocument

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /crm/notesList append-only notes for one CRM subject

Link to this operation

Requires the activity module. Both subject filters are mandatory; this is not a tenant-wide note scan. Results are ordered by created_at and id descending. Cursors are bound to the tenant and subject filters.

Authentication and scopes: OAuth2: activities:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 25

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

subject_type · query · required

Schema

enum: ["contact","job","task"]

subject_id · query · required

string

format: "uuid"

fields · query · optional

Optional comma-separated selection: id, subject_type, subject_id, body, actor, created_at.

string

Responses

200

Tenant-scoped note page.

application/json

object

data · required

array

Array items: CrmNote

page · required

object

next_cursor · required: string | null
has_more · required: boolean

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/notes/actions/create/previewPreview an append-only CRM note

Link to this operation

Requires the Client API launch gate, configured CRM cursor/preview secret, and the tenant module entitlement. Preview has no side effects. Commit requires explicit confirmation of the sealed preview and never sends messages, places calls, or synchronizes a provider.

Authentication and scopes: OAuth2: activities:write

Request body · required

application/jsonCrmNoteCreateInput

Responses

200

Tenant-scoped reviewed CRM result.

Response headers

application/json

object

data · required

CrmNoteCreatePreview

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The resource or referenced subject is not available in this tenant.

409

Preview expired, grant binding changed, state changed, or idempotency key conflicted.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/notes/actions/create/commitAppend an explicitly reviewed CRM note

Link to this operation

Authentication and scopes: OAuth2: activities:write

Parameters

Idempotency-Key · header · required

Reuse the same key and receipt to replay a successful commit. Receipts are retained for 24 hours.

string

minLength: 8
maxLength: 255
pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"

Request body · required

application/jsonReviewedCrmCommit

Responses

201

Tenant-scoped reviewed CRM result.

Response headers

application/json

object

data · required

CrmNote

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
outcome · required: Schema
const: "create"
mutation_policy · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The resource or referenced subject is not available in this tenant.

409

Preview expired, grant binding changed, state changed, or idempotency key conflicted.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /crm/jobsList CRM business jobs

Link to this operation

Requires the jobs module. These business records are distinct from asynchronous /jobs. Results are ordered by updated_at and id descending; cursors are tenant- and filter-bound.

Authentication and scopes: OAuth2: jobs:read

Parameters

limit · query · optional

integer

minimum: 1
maximum: 100
default: 25

cursor · query · optional

Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export.

string

status · query · optional

Schema

enum: ["lead","quoted","scheduled","in_progress","done","closed","cancelled","lost"]

contact_id · query · optional

string

format: "uuid"

fields · query · optional

Optional comma-separated selection: id, contact_id, status, title, details, service_name, source_channel, lifecycle_stage, qualification, owner, quoted_at, scheduled_at, started_at, completed_at, created_at, updated_at.

string

Responses

200

Tenant-scoped CRM job page.

application/json

object

data · required

array

Array items: CrmJob

page · required

object

next_cursor · required: string | null
has_more · required: boolean

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

GET /crm/jobs/{id}Read one CRM business job

Link to this operation

Authentication and scopes: OAuth2: jobs:read

Parameters

id · path · required

string

format: "uuid"

fields · query · optional

string

Responses

200

CRM job and strong ETag.

Response headers

ETag

string

application/json

object

data · required

CrmJob

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The resource or referenced subject is not available in this tenant.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/jobs/actions/create/previewPreview a CRM business job creation

Link to this operation

Authentication and scopes: OAuth2: jobs:write

Request body · required

application/jsonCrmJobCreateInput

Responses

200

Tenant-scoped reviewed CRM result.

Response headers

application/json

object

data · required

CrmJobCreatePreview

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The resource or referenced subject is not available in this tenant.

409

Preview expired, grant binding changed, state changed, or idempotency key conflicted.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/jobs/actions/create/commitCreate an explicitly reviewed CRM business job

Link to this operation

Authentication and scopes: OAuth2: jobs:write

Parameters

Idempotency-Key · header · required

Reuse the same key and receipt to replay a successful commit. Receipts are retained for 24 hours.

string

minLength: 8
maxLength: 255
pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"

Request body · required

application/jsonReviewedCrmCommit

Responses

201

Tenant-scoped reviewed CRM result.

Response headers

ETag

string

Location

string

application/json

object

data · required

CrmJob

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
outcome · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The resource or referenced subject is not available in this tenant.

409

Preview expired, grant binding changed, state changed, or idempotency key conflicted.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/jobs/{id}/actions/lifecycle/previewPreview a permitted CRM job status transition

Link to this operation

Authentication and scopes: OAuth2: jobs:write

Parameters

id · path · required

string

format: "uuid"

If-Match · header · required

Current strong ETag from GET /crm/jobs/{id}.

string

Request body · required

application/json

object

Only the listed fields are accepted.

to · required: Schema
enum: ["lead","quoted","scheduled","in_progress","done","closed","cancelled","lost"]

Responses

200

Exact before/after status and a sealed 15-minute receipt. The server enforces the allowed transition graph.

Response headers

ETag

string

application/json

object

data · required

CrmJobLifecyclePreview

meta · required

object

request_id · required: string
version · required: Schema
const: "1"

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The resource or referenced subject is not available in this tenant.

409

Preview expired, grant binding changed, state changed, or idempotency key conflicted.

428

If-Match is required.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

POST /crm/jobs/{id}/actions/lifecycle/commitCommit an explicitly reviewed CRM job status transition

Link to this operation

Authentication and scopes: OAuth2: jobs:write

Parameters

id · path · required

string

format: "uuid"

Idempotency-Key · header · required

Reuse the same key and receipt to replay a successful commit. Receipts are retained for 24 hours.

string

minLength: 8
maxLength: 255
pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"

Request body · required

application/jsonReviewedCrmCommit

Responses

200

Tenant-scoped reviewed CRM result.

Response headers

ETag

string

application/json

object

data · required

CrmJob

meta · required

object

request_id · required: string
version · required: Schema
const: "1"
outcome · required: string

400

Invalid request parameters or body.

application/jsonError

401

Missing, invalid, expired or revoked bearer token.

Response headers

WWW-Authenticate

string

application/jsonError

403

The bearer grant lacks the required scope.

application/jsonError

404

The resource or referenced subject is not available in this tenant.

409

Preview expired, grant binding changed, state changed, or idempotency key conflicted.

429

Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.

Response headers

Retry-After

string

application/jsonRateLimitError

Field definitions

Error

object

error · required

object

code · required: string
message · required: string
request_id · optional: string | null

RateLimitError

object

error · required: string

PageMeta

object

limit · required: integer
has_more · required: boolean
next_cursor · required: string | null

Call

object

id · required

string

format: "uuid"

occurred_at · required

string | null

caller · required

object

name · optional: string | null
phone · optional: string | null

duration_seconds · optional

integer | null

outcome · optional

string | null

intent · optional

string | null

sentiment · optional

string | null

services_mentioned · optional

string | null

follow_up_needed · optional

boolean | null

spam_status · optional

string | null

summary · optional

string | null

transcript · optional

string | null

Contact

object

id · required: string
format: "uuid"
name · optional: string | null
phone · optional: string | null
email · optional: string | null
notes · optional: string | null
tags · optional: Schema
classification · optional: string | null
total_jobs · optional: integer | null
lifetime_value · optional: Schema
consent · optional: object
first_seen_at · optional: string | null
last_seen_at · optional: string | null
lead_source · optional: string
lifecycle_stage · optional: string
qualification · optional: string

CrmContactInput

object

Only the listed fields are accepted.

phone · required: string
minLength: 1
maxLength: 50
email · optional: string
maxLength: 255
name · optional: string
maxLength: 255

CrmContact

object

id · required: string
format: "uuid"
name · optional: string | null
phone · optional: string
email · optional: string | null
notes · optional: string | null
tags · optional: array | null
Array items:
string
classification · optional: string | null
total_jobs · optional: integer
lifetime_value · optional: string | null
consent · optional: object
first_seen_at · optional: string | null
last_seen_at · optional: string | null
created_at · optional: string | null
updated_at · optional: string | null
lead_source · optional: string
lifecycle_stage · optional: string
qualification · optional: string
revision · optional: integer
minimum: 1

Form

object

id · required: string
format: "uuid"
ref · required: string
title · required: string
status · required: string
definition · optional: object
version · required: integer
received_responses · optional: integer
draft_revision · required: string
format: "date-time"
created_at · optional: string
format: "date-time"
updated_at · optional: string
format: "date-time"
published_at · optional: string | null

FormResponseColumn

object

Only the listed fields are accepted.

ref · required: string
title · required: string
type · required: string
removed · required: boolean
True when the current definition no longer carries this question.
unknownHistory · required: boolean
True when no referenced revision can recover its label and field type.

FormResponse

object

Only the listed fields are accepted.

id · required: string
format: "uuid"
formId · required: string
format: "uuid"
formVersion · required: integer
minimum: 1
revisionId · required: string | null
format: "uuid"
revisionFingerprint · required: string | null
status · required: string
enum: ["partial","completed","spam"]
answers · required: object
Answers keyed by field reference. File answers omit storage keys and permanent URLs. Signature acknowledgments carry the safe completion projection only: kind, optional printed name, completion, and time. The typed mark, drawn storage id, signer email, and statement text never leave the response-storage boundary.
Additional fields are allowed.
hidden · required: object | null
Additional fields are allowed.
Additional field values:
string
calculated · required: object | null
Allowlisted warnings, logic result, mode result, and clarification prompts only.
Additional fields are allowed.
ending · required: string | null
landedAt · required: string | null
format: "date-time"
submittedAt · required: string | null
format: "date-time"

FormResponseListMeta

object

request_id · required: string
version · required: string
const: "1"
limit · required: integer
minimum: 1
maximum: 100
has_more · required: boolean
next_cursor · required: string | null
total · required: integer
minimum: 0
filter_fingerprint · required: string
pattern: "^[0-9a-f]{32}$"
filter_description · required: string
column_descriptor_fingerprint · required: string
pattern: "^[0-9a-f]{64}$"
columns · required: array
maxItems: 500
Array items: FormResponseColumn

FormResponseCollection

object

Only the listed fields are accepted.

data · required

array

maxItems: 100

Array items: FormResponse

page · required

object

Only the listed fields are accepted.

next_cursor · required: string | null
has_more · required: boolean

meta · required

FormResponseListMeta

FormResponseResource

object

Only the listed fields are accepted.

data · required

FormResponse

meta · required

object

request_id · required: string
version · required: string
const: "1"
column_descriptor_fingerprint · required: string
pattern: "^[0-9a-f]{64}$"
columns · required: array
maxItems: 500
Array items: FormResponseColumn

FormAnalyticsExclusions

object

Only the listed fields are accepted.

input · required: integer
minimum: 0
spam · required: integer
minimum: 0
synthetic · required: integer
minimum: 0
included · required: integer
minimum: 0
policy · required: string

FormAnalyticsMetric

object

Only the listed fields are accepted.

value · required: number | string | null
numerator · required: number
denominator · required: number
definition · required: string
exclusions · required: FormAnalyticsExclusions

FormAnalyticsDistribution

object

Only the listed fields are accepted.

key · required: string
label · required: string
count · required: FormAnalyticsMetric

FormAnalyticsProfileComparison

object

Only the listed fields are accepted.

ref · required: string
title · required: string
wins · required: FormAnalyticsMetric
mean_score · required: FormAnalyticsMetric

FormAnalyticsAggregate

object

Choice uses options/none; boolean uses true/false/none; numeric uses count/mean/median/min/max; NPS adds promoters/passives/detractors/score; date uses min/max; text and presence use answered/skipped.

kind · required: string
enum: ["choice","boolean","numeric","nps","date","text","presence"]
options · optional: array
Array items: FormAnalyticsDistribution
none · optional: FormAnalyticsMetric
true · optional: FormAnalyticsMetric
false · optional: FormAnalyticsMetric
count · optional: FormAnalyticsMetric
mean · optional: FormAnalyticsMetric
median · optional: FormAnalyticsMetric
min · optional: FormAnalyticsMetric
max · optional: FormAnalyticsMetric
promoters · optional: FormAnalyticsMetric
passives · optional: FormAnalyticsMetric
detractors · optional: FormAnalyticsMetric
score · optional: FormAnalyticsMetric
answered · optional: FormAnalyticsMetric
skipped · optional: FormAnalyticsMetric

FormAnalyticsQuestion

object

Only the listed fields are accepted.

ref · required: string
title · required: string
type · required: string
eligible · required: FormAnalyticsMetric
reached · required: FormAnalyticsMetric
answered · required: FormAnalyticsMetric
skipped · required: FormAnalyticsMetric
abandoned_at · required: FormAnalyticsMetric
aggregate · required: FormAnalyticsAggregate

FormAnalytics

object

Only the listed fields are accepted.

schema_version · required

integer

const: 1

revision_id · required

string

format: "uuid"

exclude_synthetic · required

boolean

const: true

exclusions · required

FormAnalyticsExclusions

questions · required

array

maxItems: 200

Array items: FormAnalyticsQuestion

endings · required

array

Array items: FormAnalyticsDistribution

outcomes · required

Schema

oneOf

array

Array items: FormAnalyticsDistribution

null

profile_comparison · required

Schema

Declared-order personality/recommendation profile wins and mean scores. Null when the revision declares no profiles.

oneOf

array

Array items: FormAnalyticsProfileComparison

null

qualification · required

Schema

oneOf

object

Only the listed fields are accepted.

qualified · required: FormAnalyticsMetric
unqualified · required: FormAnalyticsMetric
unknown · required: FormAnalyticsMetric

null

FormAnalyticsResource

object

Only the listed fields are accepted.

data · required

FormAnalytics

meta · required

object

request_id · required: string
version · required: string
const: "1"

FormResponseFieldPredicate

object

ref · required: string
pattern: "^[a-z0-9_-]{1,64}$"
op · required: string
enum: ["contains","not_contains","starts_with","equals","is","is_not","any_of","all_of","eq","gt","gte","lt","lte","between","before","after","last_n_days","answered","not_answered"]
value · optional: Schema
Scalar, two-value range, or choice-reference array as required by the field type and operator.

FormResponseFilter

object

Only the listed fields are accepted.

status · optional

Schema

oneOf

string

array

Array items:

string

enum: ["partial","completed","spam"]

from · optional

string

to · optional

string

ending · optional

string

pattern: "^[a-z0-9_-]{1,64}$"

revision · optional

Schema

oneOf

string

const: "any"

string

pattern: "^[1-9][0-9]*$"

integer

minimum: 1

q · optional

string

maxLength: 200

fields · optional

array

maxItems: 20

Array items: FormResponseFieldPredicate

tag · optional

object

op · required: string
enum: ["has_tag","not_has_tag"]
value · required: string
maxLength: 40

owner_status · optional

string

enum: ["new","in_review","done"]

correction_state · optional

string

enum: ["corrected","uncorrected"]

FormExportRequest

object

Omitted format defaults to CSV; omitted filter uses the default non-spam population.

Only the listed fields are accepted.

format · optional: string
enum: ["csv","xlsx"]
default: "csv"
filter · optional: FormResponseFilter

FormExport

object

Only the listed fields are accepted.

id · required: string
format: "uuid"
format · required: string
enum: ["csv","xlsx"]
status · required: string
enum: ["queued","running","ready","cancelled","failed","expired"]
filterFingerprint · required: string
pattern: "^[0-9a-f]{32}$"
descriptorFingerprint · required: string | null
pattern: "^[0-9a-f]{64}$"
revisionScope · required: string
progressRows · required: integer
minimum: 0
rowCount · required: integer
minimum: 0
error · required: string | null
downloaded · required: boolean
expiresAt · required: string
Expires 24 hours after creation.
format: "date-time"
createdAt · required: string
format: "date-time"
percent · required: integer | null
minimum: 0
maximum: 100

FormExportResource

object

Only the listed fields are accepted.

data · required

FormExport

meta · required

object

request_id · required: string
version · required: string
const: "1"
filter_description · optional: string
Present on creation and describes the frozen population.

ApiEvent

object

id · required: string
format: "uuid"
name · required: string
occurred_at · required: string
format: "date-time"
payload · required: object

Booking

object

id · required: string
format: "uuid"
starts_at · optional: string | null
ends_at · optional: string | null
status · optional: string | null
completed_at · optional: string | null
created_at · optional: string | null

Review

object

id · required: string
format: "uuid"
platform · optional: string | null
author_name · optional: string | null
rating · optional: integer | null
text · optional: string | null
sentiment · optional: string | null
topic · optional: string | null
reviewed_at · optional: string | null
reply · optional: object

ClientAccount

object

id · required: string | null
format: "uuid"
version · optional: integer | null
kind · optional: string | null
name · required: string | null
display_name · optional: string | null
status · required: string | null
owner · optional: object
rollup · optional: object
created_at · optional: string | null
updated_at · optional: string | null

ClientApiJob

object

Only the listed fields are accepted.

id · required

string

format: "uuid"

operation · required

string

enum: ["form_export","ai_insight","report_run","integration_sync"]

state · required

string

enum: ["queued","running","ready","failed","cancelled","expired"]

progress · required

object

Only the listed fields are accepted.

completed · required: integer
minimum: 0
maximum: 1000
total · required: integer
minimum: 0
maximum: 1000

result_manifest · optional

object | null

Only the listed fields are accepted.

item_count · optional: integer
minimum: 0
maximum: 20
byte_count · optional: integer
minimum: 0
maximum: 52428800
result_ref · optional: string
pattern: "^result_[A-Za-z0-9_-]{16,128}$"

error_code · optional

string | null

retryable · required

boolean

attempt · required

integer

minimum: 0
maximum: 3

max_attempts · required

integer

minimum: 1
maximum: 3

version · required

integer

minimum: 1

created_at · required

string

format: "date-time"

updated_at · required

string

format: "date-time"

expires_at · required

string

format: "date-time"

ClientApiJobResource

object

Only the listed fields are accepted.

data · required

ClientApiJob

meta · required

object

Only the listed fields are accepted.

request_id · required: string
version · required: string
const: "1"

ClientApiJobCreateRequest

object

Only the listed fields are accepted.

operation · required: string
enum: ["form_export","ai_insight","report_run","integration_sync"]
total · required: integer
minimum: 0
maximum: 1000
expires_at · required: string
format: "date-time"
approved · required: Schema
const: true
retryable · optional: boolean
max_attempts · optional: integer
minimum: 1
maximum: 3

Job

object

id · required: string | null
format: "uuid"
title · required: string | null
status · required: string | null
contact_id · optional: string | null
client_account_id · optional: string | null
service_name · optional: string | null
scheduled_at · optional: string | null
completed_at · optional: string | null
accepted_quote_total_cents · optional: integer | null
source_channel · optional: string | null
created_at · optional: string | null
updated_at · optional: string | null

Task

object

id · required: string | null
format: "uuid"
revision · optional: integer | null
title · required: string | null
description · optional: string | null
status · required: string | null
priority · optional: string | null
contact_id · optional: string | null
job_id · optional: string | null
due_at · optional: string | null
completed_at · optional: string | null
created_at · optional: string | null
updated_at · optional: string | null

RequestOwner

object

Only the listed fields are accepted.

kind · required: string
enum: ["unassigned","owner","team_member"]
team_member_id · required: string | null

Request

object

Only the listed fields are accepted.

id · required: string
format: "uuid"
contact_id · required: string
format: "uuid"
job_id · required: string | null
source · required: string
summary · required: string
category · required: string
priority · required: string
status · required: string
owner · required: RequestOwner
tags · required: array
Array items:
string
revision · required: integer
minimum: 1
responded_at · required: string | null
resolved_at · required: string | null
created_at · required: string
format: "date-time"
updated_at · required: string
format: "date-time"

RequestConversationItem

object

Only the listed fields are accepted.

id · required: string
format: "uuid"
type · required: string
enum: ["customer_message","public_reply"]
text · required: string
maxLength: 4000
created_at · required: string
format: "date-time"
author · required: string
enum: ["customer","business"]

RequestDetail

object

Only the listed fields are accepted.

id · required

string

format: "uuid"

contact_id · required

string

format: "uuid"

job_id · required

string | null

source · required

string

summary · required

string

category · required

string

priority · required

string

status · required

string

owner · required

RequestOwner

tags · required

array

Array items:

string

revision · required

integer

minimum: 1

responded_at · required

string | null

resolved_at · required

string | null

created_at · required

string

format: "date-time"

updated_at · required

string

format: "date-time"

description · required

string | null

conversation · required

object

Only the listed fields are accepted.

items · required: array
maxItems: 100
Array items: RequestConversationItem
truncated · required: boolean

TaskCreateInput

object

Only the listed fields are accepted.

title · required: string
minLength: 1
maxLength: 200
description · optional: string | null
due_at · optional: string | null
priority · optional: string
enum: ["low","normal","high"]
contact_id · optional: string | null
job_id · optional: string | null
owner · optional: object

TaskStatusInput

object

Only the listed fields are accepted.

target_status · required: string
enum: ["open","done"]
expected_revision · required: integer
minimum: 1

DocumentTemplate

object

id · required: string
format: "uuid"
form_id · optional: string | null
name · required: string
description · optional: string
kind · required: string
status · required: string
active_version_id · optional: string | null
versions · required: array
Array items: DocumentTemplateVersion
created_at · optional: string
format: "date-time"
updated_at · optional: string
format: "date-time"

SignatureEnvelope

object

Only the listed fields are accepted.

id · required

string

format: "uuid"

version · required

integer

minimum: 1

status · required

string

enum: ["draft","ready","sent","in_progress","finalizing","completed","declined","voided","expired","finalization_failed","abandoned"]

title · required

string

document_kind · required

string

enum: ["agreement","quote_acceptance"]

related_record · required

object

Only the listed fields are accepted.

kind · optional: string
enum: ["business","contact","account","job","task"]
id · optional: string
format: "uuid"

oneOf

object

Only the listed fields are accepted.

kind · required: string
const: "business"

object

Only the listed fields are accepted.

kind · required: string
enum: ["contact","account","job","task"]
id · required: string
format: "uuid"

delivery_method · required

string

enum: ["copy_link","email"]

legal_hold · required

boolean

retention_policy · required

string

enum: ["90_days","1_year","3_years","7_years"]

retention_until · optional

string | null

format: "date-time"

expires_at · optional

string | null

format: "date-time"

sent_at · optional

string | null

format: "date-time"

completed_at · optional

string | null

format: "date-time"

created_at · required

string

format: "date-time"

updated_at · required

string

format: "date-time"

PipelineOpportunity

object

id · required: string | null
format: "uuid"
version · optional: integer | null
pipeline_key · required: string | null
stage_key · required: string | null
title · required: string | null
value_cents · optional: integer | null
expected_close_date · optional: string | null
contact_id · optional: string | null
job_id · optional: string | null
created_at · optional: string | null
updated_at · optional: string | null

Activity

object

id · required: string | null
format: "uuid"
event_type · required: string | null
payload · optional: object
actor · optional: object
subjects · optional: array
Array items:
object
occurred_at · required: string | null
record · optional: object | null

SavedView

object

id · required: string | null
format: "uuid"
key · required: string | null
label · required: string | null
resource · required: string | null
revision · required: integer | null
presentation · optional: object
created_at · optional: string | null
updated_at · optional: string | null

ReportDefinition

object

id · required: string | null
format: "uuid"
version · required: integer | null
name · required: string | null
description · optional: string | null
resource · required: string | null
dimensions · optional: array
measures · optional: array
date_range · optional: object
archived_at · optional: string | null
updated_at · optional: string | null
latest_successful_run · optional: object | null

AutomationExecution

object

id · required: string | null
format: "uuid"
rule_id · required: string | null
rule_version · required: integer | null
status · required: string | null
attempt_count · optional: integer | null
maximum_attempts · optional: integer | null
event_label · optional: string | null
started_at · optional: string | null
completed_at · optional: string | null
next_retry_at · optional: string | null
last_error_code · optional: string | null
actions · optional: array
Array items:
object
subject · optional: object

CrmJob

object

Tenant-owned CRM business job, distinct from the asynchronous /jobs resource. fields can select any subset of these properties.

id · optional

string

contact_id · optional

string | null

status · optional

Schema

enum: ["lead","quoted","scheduled","in_progress","done","closed","cancelled","lost"]

title · optional

string

details · optional

string | null

service_name · optional

string | null

source_channel · optional

string | null

lifecycle_stage · optional

string

qualification · optional

string

owner · optional

object

kind · required: string
team_member_id · required: string | null

quoted_at · optional

string | null

scheduled_at · optional

string | null

started_at · optional

string | null

completed_at · optional

string | null

created_at · optional

string | null

updated_at · optional

string | null

CrmNote

object

Append-only CRM note. fields may select a subset; id is always included. Mutation responses return all listed fields.

id · required

string

subject_type · optional

Schema

enum: ["contact","job","task"]

subject_id · optional

string

body · optional

string | null

actor · optional

object

email · required: string | null
role · required: string | null

created_at · optional

string | null

ReviewedCrmCommit

object

Only the listed fields are accepted.

preview_token · required: string
minLength: 32
maxLength: 8192
confirmed · required: Schema
const: true

CrmJobCreateInput

object

Only the listed fields are accepted.

title · required: string
Trimmed; whitespace-only titles are refused.
minLength: 1
maxLength: 200
details · optional: string | null
maxLength: 20000
contact_id · optional: string | null
format: "uuid"
service_name · optional: string | null
maxLength: 80
status · optional: Schema
Must also satisfy the current job creation policy.
enum: ["lead","quoted","scheduled","in_progress","done","closed","cancelled","lost"]
default: "lead"

CrmNoteCreateInput

object

Only the listed fields are accepted.

subject_type · required: Schema
enum: ["contact","job","task"]
subject_id · required: string
format: "uuid"
body · required: string
Trimmed; blank notes are refused.
minLength: 1
maxLength: 5000

CrmJobCreatePreview

object

operation · required

Schema

const: "job.create"

before · required

null

after · required

object

title · required: string
details · required: string | null
contactId · required: string | null
serviceName · required: string | null
status · required: Schema
enum: ["lead","quoted","scheduled","in_progress","done","closed","cancelled","lost"]

commit · required

ReviewedCrmPreviewReceipt

non_effects · required

array

Array items:

string

CrmJobLifecyclePreview

object

operation · required

Schema

const: "job.lifecycle"

before · required

object

id · required: string
status · required: string
version · required: string
format: "date-time"

after · required

object

id · required: string
status · required: string

commit · required

ReviewedCrmPreviewReceipt

non_effects · required

array

Array items:

string

CrmNoteCreatePreview

object

operation · required

Schema

const: "note.create"

before · required

null

after · required

object

subject_type · required

string

subject_id · required

string

body · required

string

actor · required

object

kind · required: Schema
const: "oauth_grant"
grant_id · required: string | null
client_id · required: string | null

commit · required

ReviewedCrmPreviewReceipt

non_effects · required

array

Array items:

string

ReviewedCrmPreviewReceipt

object

preview_token · required: string
Sealed, expiring receipt bound to this tenant and OAuth grant. Do not log it or substitute edited fields at commit.
expires_at · required: string
format: "date-time"
requires_confirmation · required: Schema
const: true

DocumentTemplateVersion

object

id · required

string

kind · required

string

status · required

string

is_active · required

boolean

source_pdf_configured · required

boolean

version_fingerprint · required

string

merge_placements · required

array

Array items:

object

placement_ref · required: string
source_kind · required: string
source_ref · required: string
page · required: integer
x · required: number
y · required: number
w · required: number
h · required: number
font · required: string
font_size · required: number
alignment · required: string
line_limit · required: integer
overflow_policy · required: string
required · required: boolean

signature_placements · required

array

Array items:

object

placement_ref · required: string
recipient_role_ref · required: string
field_type · required: string
page · required: integer
x · required: number
y · required: number
w · required: number
h · required: number
required · required: boolean

approved_at · required

string | null

created_at · required

string

format: "date-time"

updated_at · required

string

format: "date-time"

ApiDiscovery

object

name · required: string
version · required: string
read_only · required: boolean
resources · required: object
Additional fields are allowed.
Additional field values:
string
granted_scopes · required: array
Array items:
string

CurrentClient

object

data · required

object

id · required: string
business_name · required: string | null
email · required: string | null
time_zone · required: string | null
oauth_client_id · required: string
scopes · required: array
Array items:
string

OpenApiDocument

object

An OpenAPI 3.1 document. Path items and components follow the OpenAPI specification.

openapi · required

Schema

const: "3.1.0"

info · required

object

title · required: string
version · required: string
description · required: string

servers · optional

array

Array items:

object

url · required: string

paths · required

object

components · optional

object

security · optional

array

Array items:

object

ContactUpsertPreview

object

kind · required

Schema

enum: ["create","update","no_op","ambiguous","conflict"]

contact_id · required

string | null

before · required

object

email · optional: string | null
phone · optional: string | null
name · optional: string | null

after · required

object

email · optional: string | null
phone · optional: string | null
name · optional: string | null

expected_revision · required

integer | null

non_effects · required

array

Array items:

string

candidate_ids · optional

array

Array items:

string

ambiguity · optional

string

refusal · optional

string

reason · optional

string

commit · required

object

committable · required: boolean
preview_key · required: string
expected_revision · required: integer | null
if_match_required · required: boolean
etag · optional: string | null
idempotency_key_header · optional: string
confirmation_required · optional: boolean

CrmTask

object

The CRM task projection. fields may select a subset; id is always returned. Mutation responses return all listed properties.

id · required

string

format: "uuid"

title · optional

string

description · optional

string | null

status · optional

string

priority · optional

string

due_at · optional

string | null

contact_id · optional

string | null

job_id · optional

string | null

owner · optional

object

kind · required: string
team_member_id · required: string | null

completed_at · optional

string | null

created_at · optional

string | null

updated_at · optional

string | null

revision · optional

integer

TaskCreatePreview

object

kind · required

string

before · required

object

title · required: null
due_at · required: null
priority · required: null
owner · required: null

after · required

object

title · required

string

due_at · required

string | null

priority · required

string

owner · required

object

kind · required: string
team_member_id · required: string | null

description · required

string | null

contact_id · required

string | null

job_id · required

string | null

expected_revision · required

null

non_effects · required

array

Array items:

string

commit · required

object

committable · required: boolean
preview_key · required: string
expected_revision · required: integer | null
if_match_required · required: boolean
etag · optional: string | null
idempotency_key_header · optional: string
confirmation_required · optional: boolean

TaskStatusPreview

object

kind · required

string

task_id · required

string

before · required

object

status · required: string

after · required

object

status · required: string

expected_revision · required

integer

non_effects · required

array

Array items:

string

commit · required

object

committable · required: boolean
preview_key · required: string
expected_revision · required: integer | null
if_match_required · required: boolean
etag · optional: string | null
idempotency_key_header · optional: string
confirmation_required · optional: boolean

FormScheduling

object

form_id · required

string

source · required

Schema

const: "draft"

scheduling_fields · required

array

Array items:

object

field_ref · required: string
title · required: string
provider · required: string
duration_minutes · required: integer
buffer_minutes · required: integer
max_days_ahead · required: integer
weekdays · required: array
Array items:
integer
minimum: 0
maximum: 6
working_hours_source · required: string

provider_availability_queried · required

Schema

const: false

booking_created · required

Schema

const: false

StoredFormInsight

object

id · required

string

question · required

string

answer · required

string

evidence · required

object

filter_fingerprint · required: string
filter_summary · required: string
population_rows · required: integer
rows_read · required: integer
window_from · required: string | null
window_to · required: string | null

generated_at · required

string

format: "date-time"

expires_at · required

string

format: "date-time"

DepositCapability

object

capability · required: Schema
const: "business_owned_deposit_link"
enabled · required: boolean
ready · required: boolean
mode · required: string | null
unavailable_reason · required: string | null
trigger · required: string
charge_supported · required: Schema
const: false
refund_supported · required: Schema
const: false
provider_settlement_confirmed · required: Schema
const: false
payment_url_disclosed · required: Schema
const: false

WorkflowPreview

object

contractVersion · required

string

mode · required

Schema

const: "preview_only"

status · required

string

ruleKey · required

string

ruleVersion · required

integer

ruleStatus · required

string

ruleFingerprint · required

string

eventFingerprint · required

string

idempotencyBasis · required

string

triggerMatched · required

boolean

conditionsMatched · required

boolean

wouldMatch · required

boolean

humanApprovalRequired · required

boolean

actionPreviews · required

array

Array items:

object

index · required: integer
type · required: string
approvalRequirement · required: string
decision · required: string

conditionTrace · required

array

Array items:

object

path · required: string
fact · required: string
operator · required: string
expected · required: string | boolean | number
actual · required: string | boolean | number | null
matched · required: boolean
reason · required: Schema
enum: ["matched","not_matched","missing_fact"]

executionPerformed · required

Schema

const: false

executionAllowed · required

Schema

const: false

WebhookEndpoint

object

id · required: string
url · required: string
format: "uri"
event_names · required: array
Array items:
string
status · required: string
verification_status · required: string
created_at · required: string
format: "date-time"
updated_at · required: string
format: "date-time"

ProvisionedWebhookEndpoint

object

id · required: string
url · required: string
format: "uri"
event_names · required: array
Array items:
string
status · required: string
verification_status · required: string
created_at · required: string
format: "date-time"
updated_at · required: string
format: "date-time"
signing_secret · required: string
Returned only on creation. Store securely; subsequent reads cannot recover this value.
verification_challenge · required: string
verification_expires_at · required: string
format: "date-time"

WebhookDeliveryAttempt

object

attempt · required: integer
state · required: string
started_at · required: string
format: "date-time"
finished_at · required: string
format: "date-time"
latency_ms · required: integer
http_status · required: integer | null
error_code · required: string | null

WebhookDelivery

object

id · required

string

endpoint_id · required

string

event · required

object

id · required: string
name · required: string
occurred_at · required: string
format: "date-time"

state · required

string

attempt_count · required

integer

next_attempt_at · required

string | null

latest_attempt · required

Schema

anyOf

WebhookDeliveryAttempt

null

created_at · required

string

format: "date-time"

updated_at · required

string

format: "date-time"

delivered_at · required

string | null

dead_lettered_at · required

string | null

WebhookDeliveryDetail

object

id · required

string

endpoint_id · required

string

event · required

object

id · required: string
name · required: string
occurred_at · required: string
format: "date-time"

state · required

string

attempt_count · required

integer

next_attempt_at · required

string | null

latest_attempt · required

Schema

anyOf

WebhookDeliveryAttempt

null

created_at · required

string

format: "date-time"

updated_at · required

string

format: "date-time"

delivered_at · required

string | null

dead_lettered_at · required

string | null

attempts · required

array

maxItems: 50

Array items: WebhookDeliveryAttempt

ExportCatalog

object

data · required

array

Array items:

object

id · required: Schema
enum: ["calls","call-insight-reviews","callers","lead-lifecycle-history","lead-reason-sets","lead-import-history","chats","messages","webchat-resolution-feedback","taken-messages","bookings","internal-calendar-events","reviews","client-accounts","account-relationships","account-command-history","jobs","fulfillment-operations","fulfillment-outbox","call-outcomes","call-outcome-steps","equipment","equipment-service-history","equipment-service-evidence","job-status-links","delivery-templates","delivery-plans","delivery-items","delivery-dependencies","delivery-blockers","delivery-history","tasks","task-reminders","task-reminder-deliveries","team-workload-revision","team-queues","team-queue-memberships","team-queue-resources","team-queue-watchers","task-assignment-history","resource-assignment-history","team-threads","team-messages","team-mentions","team-notifications","team-notification-preferences","push-devices","team-command-history","crm-activity","crm-timeline","business-files","business-file-sources","business-file-revisions","business-file-publications","intake-media","attachments","signature-envelopes","signature-recipients","signature-fields","signature-field-values","signature-events","signature-artifacts","signature-templates","signature-verifications","signature-bulk-batches","signature-bulk-items","sales-pipeline-definitions","sales-opportunities","sales-opportunity-history","crm-duplicate-candidates","crm-duplicate-dismissed-pairs","crm-forecast-snapshots","crm-import-mapping-profiles","crm-import-dry-run-fingerprints","sla-policies","sla-ticket-clocks","sla-ticket-clock-pauses","crm-account-classifications","crm-account-segments","csat-survey-definitions","csat-survey-invitations","csat-survey-responses","crm-relationship-edges","territories","territory-visit-events","portal-access-grants","config-draft-versions","config-activations","crm-partner-account-attributes","crm-partner-contacts","crm-partner-onboarding-events","crm-partner-lead-registrations","crm-partner-lead-events","crm-contact-identities","crm-contact-merge-aliases","tenant-referrals","tenant-referral-events","incentive-plan-versions","incentive-period-versions","incentive-period-participants","incentive-revenue-credits","incentive-revenue-credit-splits","incentive-adjustments","incentive-statements","crm-layout-visibility-conditions","crm-layout-approved-actions","crm-report-definitions","crm-report-runs","crm-report-result-rows","crm-report-memberships","crm-report-command-history","custom-field-definitions","custom-field-values","custom-field-definition-history","custom-field-value-history","custom-field-command-history","record-layout-history","customer-cases","customer-case-messages","customer-case-events","customer-case-reply-snippets","service-area-settings","public-faqs","faq-disclosures","consented-visitor-activity","saved-views","search-saved-views","quote-templates","settings"]
label · required: string
description · required: string
format · required: Schema
const: "text/csv"
endpoint · required: string

meta · required

object

count · required: integer

FormsAuthoringDefinition

object

Structural checks only. POST /forms/validate runs the canonical semantic validator. Saving also checks references, logic, settings and owned assets. Validation never authorizes publication.

Additional fields are allowed.

title · required

string

minLength: 1
maxLength: 300

ref · optional

string

pattern: "^[a-z0-9_-]{1,64}$"

fields · required

array

Array items:

object

Additional fields are allowed.

ref · optional: string
pattern: "^[a-z0-9_-]{1,64}$"
type · required: string
enum: ["short_text","long_text","email","phone_number","multiple_choice","checkbox","picture_choice","dropdown","yes_no","opinion_scale","rating","nps","number","date","time","address","website","file_upload","signature","contact","ranking","matrix","scheduler","statement","legal"]
title · required: string

theme · optional

object

The canonical validator checks colors, layout, fonts and tenant-owned image references.

FormsAuthoringCreate

object

Only the listed fields are accepted.

definition · required: FormsAuthoringDefinition
ref · optional: string
pattern: "^[a-z0-9_-]{1,64}$"

FormsAuthoringDuplicate

object

Only the listed fields are accepted.

ref · required: string
pattern: "^[a-z0-9_-]{1,64}$"
title · optional: string
minLength: 1
maxLength: 300
expected_draft_revision · required: string
format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"

FormsAuthoringPreview

object

Only the listed fields are accepted.

expected_draft_revision · required: string
format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
expected_published_version · required: integer
minimum: 0

FormsAuthoringPublish

object

Only the listed fields are accepted.

expected_draft_revision · required: string
format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
expected_published_version · required: integer
minimum: 0
preview_receipt · required: string
minLength: 40
maxLength: 2000
confirmed · required: Schema
const: true

FormsAuthoringConditionalWrite

object

Only the listed fields are accepted.

expected_draft_revision · required: string
format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"

FormsAuthoringValidate

object

Only the listed fields are accepted.

definition · required: FormsAuthoringDefinition

FormsAuthoringApply

object

Only the listed fields are accepted.

version · required

Schema

const: 1

expected_draft_revision · required

string

format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"

operations · required

array

The closed operation vocabulary and semantic constraints are enforced by the canonical Forms operation parser.

Array items:

object

op · required: string

FormsAuthoringMeta

object

Additional fields are allowed.

request_id · required: string
version · required: Schema
const: "1"

FormsAuthoringForm

object

id · required: string
format: "uuid"
ref · optional: string
pattern: "^[a-z0-9_-]{1,64}$"
title · optional: string
status · optional: Schema
enum: ["draft","published","closed"]
version · optional: integer
draft_revision · optional: string
format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
definition · optional: FormsAuthoringDefinition
received_responses · optional: integer
created_at · optional: string | null
updated_at · optional: string | null
published_at · optional: string | null

FormsAuthoringPreparedPreview

object

preview_receipt · required: string
definition · required: FormsAuthoringDefinition
fingerprint · required: string
expires_at · required: string
format: "date-time"
expected_draft_revision · required: string
format: "date-time"
pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
expected_published_version · required: integer
published · required: Schema
const: false
confirmation_instruction · optional: string

FormsAuthoringDeleted

object

Only the listed fields are accepted.

id · required: string
format: "uuid"
deleted · required: Schema
const: true
scope · required: Schema
const: "never_published_empty_draft"

FormsAuthoringValidation

object

definition · optional: FormsAuthoringDefinition
warnings · optional: array
publication_authorized · optional: Schema
const: false
validation_scope · optional: Schema
const: "definition_only"

FormsAuthoringApplied

object

form · optional: FormsAuthoringForm
applied · optional: object
diff · optional: object
warnings · optional: array

FormsAuthoringError

object

Only the listed fields are accepted.

error · required

object

code · required: string
message · required: string
request_id · required: string
retryable · required: boolean
field · optional: string | null
details · optional: object

Implementation and access notes

The authenticated OpenAPI 3.1 document is the exact 78-operation source contract. The table below groups compatible operations by OAuth scope and calls out important companion routes. Implemented means the route exists in source and still remains subject to the production gate (CLIENT_API_ENABLED), registration, grant, and entitlement. Draft is a design example only. Reserved means no Client API resource implementation exists.

Official base path

https://api.firstaiemployee.com/api/client/v1

Method	Path	Scope	Status	Notes
`GET`	`/oauth/authorize`	`requested scopes`	Implemented	Browser consent. Registered clients only.
`POST`	`/oauth/token`	`none`	Implemented	Authorization code and rotating refresh grants.
`GET`	`/api/client/v1/me`	`any valid grant`	Implemented	Tenant-safe connection identity.
`GET`	`/api/client/v1`	`any valid grant`	Implemented	Read-only service discovery.
`GET`	`/api/client/v1/openapi.json`	`any valid grant`	Implemented	Authenticated OpenAPI 3.1 contract.
`GET`	`/api/client/v1/calls`	`calls:read`	Implemented	Call history and transcript projection.
`GET`	`/api/client/v1/contacts`	`contacts:read`	Implemented	Contacts and recorded consent state.
`POST`	`/api/client/v1/crm/contacts:preview`	`contacts:write`	Implemented	Preview and commit a bounded contact upsert.
`GET`	`/api/client/v1/bookings`	`bookings:read`	Implemented	Read-only booking projection.
`GET`	`/api/client/v1/reviews`	`reviews:read`	Implemented	Reviews and reply status.
`GET`	`/api/developer/v1/forms`	`forms:read`	Implemented	Forms a business owns and the responses they collected.
`GET`	`/api/client/v1/forms`	`front_desk:forms:read`	Implemented	Forms metadata and safe draft definitions. List and detail also accept forms:lifecycle. Select definition explicitly on detail.
`POST`	`/api/client/v1/forms/{id}:applyOperations`	`forms:write`	Implemented	Apply a closed batch of revision-checked form edits.
`GET`	`/api/client/v1/forms/{formId}/responses`	`forms:responses:read`	Implemented	Bounded form responses with stable historical columns.
`GET`	`/api/client/v1/forms/{formId}/analytics`	`forms:analytics:read`	Implemented	Deterministic branch-aware form analytics.
`GET`	`/api/client/v1/exports`	`exports:read`	Implemented	Complete field-allowlisted dataset catalog.
`POST`	`/api/client/v1/forms/{formId}/exports`	`exports:create`	Implemented	Create, inspect, and download frozen form exports.
`GET`	`/api/client/v1/client-accounts`	`client_accounts:read`	Implemented	Client accounts with bounded contact and job summaries.
`GET`	`/api/client/v1/jobs`	`jobs:read`	Implemented	Tenant-scoped job records.
`POST`	`/api/client/v1/crm/jobs/actions/create/preview`	`jobs:write`	Implemented	Create jobs and apply explicitly reviewed lifecycle changes.
`GET`	`/api/client/v1/tasks`	`tasks:read`	Implemented	Tenant-scoped Front Desk tasks.
`GET`	`/api/client/v1/requests`	`requests:read`	Implemented	Tenant-scoped Request list and exact detail projections.
`GET`	`/api/client/v1/pipeline-opportunities`	`pipeline_opportunities:read`	Implemented	Pipeline opportunity projections.
`GET`	`/api/client/v1/activities`	`activities:read`	Implemented	Bounded CRM activity timeline.
`POST`	`/api/client/v1/crm/notes/actions/create/preview`	`activities:write`	Implemented	Add an append-only CRM note after explicit review.
`GET`	`/api/client/v1/saved-views`	`saved_views:read`	Implemented	Saved-view definitions visible to the account.
`GET`	`/api/client/v1/saved-views/{id}/results`	`saved_views:execute`	Implemented	Execute an authorized saved view.
`GET`	`/api/client/v1/report-definitions`	`reports:read`	Implemented	Report definitions and current summaries.
`GET`	`/api/client/v1/automation-executions`	`automations:read`	Implemented	Recent automation execution projections.
`GET`	`/api/client/v1/dashboard`	`dashboard:read`	Implemented	Owner-facing dashboard summary.
`GET`	`/api/client/v1/events`	`events:read`	Implemented	Tenant-scoped API event history.
`POST`	`/api/client/v1/webhooks`	`webhooks:manage`	Implemented	Verified webhook endpoint lifecycle.
`GET`	`/api/client/v1/webhook-deliveries`	`webhook_deliveries:read`	Implemented	Sanitized webhook delivery status and attempt history.
`GET`	`/api/client/v1/document-templates`	`documents:read`	Implemented	Read document templates and immutable version layouts.
`GET`	`/api/client/v1/signature-envelopes`	`signatures:read`	Implemented	Read signature envelope status without signer-sensitive details.
`POST`	`/api/client/v1/crm/tasks/actions/create/preview`	`tasks:prepare`	Implemented	Preview bounded CRM task changes without applying them.
`POST`	`/api/client/v1/crm/tasks/actions/create/commit`	`tasks:commit`	Implemented	Commit only an explicitly reviewed CRM task change.
`POST`	`/api/client/v1/forms`	`forms:lifecycle`	Implemented	Create an unpublished draft. 201 with ETag and Location. Idempotency-Key 16 to 128 chars; exact retries replay for 24 hours.
`POST`	`/api/client/v1/forms/{id}/duplicate`	`forms:lifecycle`	Implemented	Copy a definition into a new draft with stable child refs and no responses. 201. Requires If-Match and expected draft revision.
`POST`	`/api/client/v1/forms/{id}/publish-preview`	`forms:lifecycle`	Implemented	Review the exact publish candidate. No publication occurs. Receipt expires after ten minutes; reuse the same Idempotency-Key for publish.
`POST`	`/api/client/v1/forms/{id}/publish`	`forms:lifecycle`	Implemented	Publish the approved preview as a new immutable revision. Requires receipt, unchanged revisions, and confirmed:true.
`POST`	`/api/client/v1/forms/{id}/close`	`forms:lifecycle`	Implemented	Stop collection without deleting history. Remains available after module deactivation.
`DELETE`	`/api/client/v1/forms/{id}`	`forms:lifecycle`	Implemented	Delete only an empty never-published draft. Requires If-Match and expected draft revision.
`POST`	`/api/client/v1/forms/validate`	`forms:write, forms:lifecycle`	Implemented	Canonical semantic validation without persistence. A valid document is not a publication approval.
`GET`	`/api/client/v1/forms/schema.json`	`front_desk:forms:read, forms:lifecycle`	Implemented	Structural JSON Schema versioned in $comment. Cross-links the versioned Forms authoring OpenAPI companion at GET /forms/openapi.json.
`GET`	`/api/client/v1/forms/openapi.json`	`front_desk:forms:read`	Implemented	Versioned Forms authoring OpenAPI companion (2026-09-05.1). Cross-linked from the main contract; requires the same gates.
`GET`	`/api/client/v1/signature-envelopes/{id}`	`signatures:read`	Implemented	Privacy-minimized envelope detail. It omits signer capabilities and storage identifiers.
`GET`	`/api/client/v1/exports/{dataset}.csv`	`exports:read`	Implemented	Bounded-memory complete CSV stream.
`GET`	`/api/developer/v1/forms`	`forms:read`	Implemented	Forms, revisions and responses. Read only.

Do not build production dependencies against a Reserved row. An Implemented row still requires the production gate (CLIENT_API_ENABLED), reviewed registration, the exact customer grant, and live entitlement.

Forms has two documents of its own

The forms:read routes and the browser embed each have a full contract page: every endpoint with its page size, cursor and error envelope, and every embed mode with its attributes and events.

The Forms developer API Embed a form on your website

Client API overview

These docs do not grant access.

Registered clients only

Tenant from the grant

Narrow scopes

Access and registration

Review-gated and production-gated

What must happen before a first request

Quickstart

1. Submit a developer application

2. Send the customer to consent

3. Exchange the code once

4. Call a granted resource

OAuth 2.0

Refresh an existing connection

Authorization flow

Token response

Client obligations

Pagination and time

Dates, times, and phone numbers

Errors and retries

Calls

Sensitive text

Related read-only resources

Contacts

Reviews

Bookings

Safe writes

Webhooks

What exists now

Operational boundary

Complete exports

Live with separate export approval

Safe import sequence

Porting playbook

1. Inventory

2. Minimize

3. Backfill

4. Catch up

5. Reconcile

6. Operate

Recommended destination mapping

Versioning

Deprecation policy

Endpoint status

Complete application API catalog

Responses

Response headers

Responses

Response headers

Responses

Response headers

Parameters

Responses

Response headers

Response headers

Parameters

Responses

Response headers

Response headers

Parameters

Responses

Response headers

Response headers

Parameters

Responses

Response headers

Response headers

Response headers

Request body · required

Responses

Response headers

Response headers

Parameters

Request body · required

Responses

Response headers

Response headers

Response headers

Response headers