Submit a lead from a website form

For a website's server holding a Vision API client with crm:intake:create (identity class website_bff or app_service), bound to the CRM workspace. Creates one quarantined intake submission in the caller's own workspace; never reads. See the guide 'Collect leads from your website'.

App

CRM

Contract

CRM API 9.12.1

Lifecycle

preview

Runtime

restricted

Operation ID

Not declared (legacy exception)

Canonical origin

Not declared; gateway routing required

Purpose and use cases

Submit a lead from a website form

The owning App is Vision CRM. CRM owns its records, workflow rules, workspace membership, provenance, and record-level authorization.

Request

POST /api/crm/v1/intake-submissions

This contract intentionally declares no direct server URL. Obtain the routed App origin before attempting the request.

Authentication and authorization

Send a Vision-issued bearer token for the exact App audience. The token must include the crm entitlement and satisfy the crm workspace required binding.

• Required scope: crm:intake:create

Human roles are not declared in OpenAPI. Record-level and business permission checks remain the owning App's authority.

Headers

• Authorization: Bearer <access-token> — required.
• Accept: application/json — recommended where a JSON response is declared.
• Content-Type: application/json — required for the documented request representation.

Undeclared tracing, idempotency, conditional-request, and version headers are not assumed on this page.

Path and query parameters

This operation declares no path or query parameters.

Request body

Media type: application/json. The body is required.

Runnable examples

curl '${APP_BASE_URL}/api/crm/v1/intake-submissions' \
  --request POST \
  --header 'authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "contractVersion": "vision-crm-lead-form.v1",
    "source": "<source>",
    "name": "<name>",
    "email": "<email>",
    "phone": "<phone>",
    "company": "<company>",
    "message": "<message>",
    "answers": [
      {
        "label": "<label>",
        "value": "<value>"
      }
    ],
    "consent": {
      "purpose": "inquiry_response",
      "channel": "email",
      "action": "granted",
      "captureMethod": "explicit_checkbox",
      "noticeVersion": "<noticeVersion>",
      "occurredAt": "2026-08-21T18:00:00Z"
    },
    "pipelineKey": "<pipelineKey>",
    "requestedRoute": "follow_up",
    "page": "/",
    "website": "",
    "test": false,
    "idempotencyKey": "<idempotencyKey>"
  }'

const response = await fetch('${APP_BASE_URL}/api/crm/v1/intake-submissions', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${ACCESS_TOKEN}`,
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
  "contractVersion": "vision-crm-lead-form.v1",
  "source": "<source>",
  "name": "<name>",
  "email": "<email>",
  "phone": "<phone>",
  "company": "<company>",
  "message": "<message>",
  "answers": [
    {
      "label": "<label>",
      "value": "<value>"
    }
  ],
  "consent": {
    "purpose": "inquiry_response",
    "channel": "email",
    "action": "granted",
    "captureMethod": "explicit_checkbox",
    "noticeVersion": "<noticeVersion>",
    "occurredAt": "2026-08-21T18:00:00Z"
  },
  "pipelineKey": "<pipelineKey>",
  "requestedRoute": "follow_up",
  "page": "/",
  "website": "",
  "test": false,
  "idempotencyKey": "<idempotencyKey>"
}),
}

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()

import json
import urllib.parse
import urllib.request

request = urllib.request.Request(
    '${APP_BASE_URL}/api/crm/v1/intake-submissions',
    data=json.dumps({"contractVersion":"vision-crm-lead-form.v1","source":"<source>","name":"<name>","email":"<email>","phone":"<phone>","company":"<company>","message":"<message>","answers":[{"label":"<label>","value":"<value>"}],"consent":{"purpose":"inquiry_response","channel":"email","action":"granted","captureMethod":"explicit_checkbox","noticeVersion":"<noticeVersion>","occurredAt":"2026-08-21T18:00:00Z"},"pipelineKey":"<pipelineKey>","requestedRoute":"follow_up","page":"/","website":"","test":false,"idempotencyKey":"<idempotencyKey>"}).encode(),
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Content-Type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

The current TypeScript reference client covers Platform token exchange and core reads. No native SDK helper is declared for this operation; use the HTTP contract directly and follow the SDK guidance.

Responses

Success response schema

{
  "schemaVersion": "vision-crm-intake-receipt.v1",
  "status": "received_for_review",
  "publicReference": "<publicReference>",
  "receivedAt": "2026-08-21T18:00:00Z",
  "replayed": true,
  "schedulingContinuation": "<schedulingContinuation>",
  "test": true
}

Errors and troubleshooting

Error bodies and codes are shown only where the approved contract declares them. Use status, the declared error schema, and any correlation identifier returned by the App; do not infer that two Apps share one envelope.

• 400 — The request is invalid
• 401 — Authentication is missing or invalid
• 403 — The authenticated actor lacks the CRM capability or workspace binding
• 409 — Idempotency key reused with a different payload
• 413 — Body larger than 64 KiB
• 429 — Too many submissions from this API client (300 per 5 minutes). Honour Retry-After.
• 503 — The CRM dependency or authenticated API configuration is unavailable

Collection behavior

Pagination: not declared. Filtering/search: not declared. Sorting: not declared.

Cursor lifetime, cursor binding, stable ordering, maximum traversal, and unknown-filter behavior are not assumed unless stated by a parameter description or schema constraint above.

Operational behavior

• Rate limit: The operation declares 429, but the numeric policy is not in OpenAPI.
• Retry: Retry only when the documented error model or response headers authorize it. Timeout and backoff values are not declared by this operation.
• Idempotency: No idempotency header or replay window is declared.
• Concurrency: No ETag, If-Match, or optimistic-version header is declared.

Security and privacy

• Keep client credentials and bearer tokens on trusted servers.
• Send only to the exact approved HTTPS origin and audience.
• Treat response data according to the owning App's classification and retention policy; the OpenAPI contract does not itself grant data access.
• Do not log credentials, tokens, complete private payloads, or secrets.

Edge cases and known documentation gaps

• No stable operation ID (legacy exception).
• No direct server URL; gateway routing is unresolved here.
• The request body has no purpose or conditional-rule description.
• Business roles, timeout, retry budget, rate value, idempotency window, and concurrency behavior are absent unless explicitly stated above.

Related operations and workflows

• GET /api/crm/v1/meta — Contract and version metadata
• GET /api/crm/v1/today — Explainable CRM attention queue
• GET /api/crm/v1/intake-submissions — Paginated quarantined intake queue
• GET /api/crm/v1/intake-submissions/{reference} — Quarantined intake detail and provenance
• GET /api/crm/v1/people — Browse canonical people
• GET /api/crm/v1/people/{reference} — Read a canonical person briefing
• GET /api/crm/v1/organizations — Browse canonical organizations
• GET /api/crm/v1/organizations/{reference} — Read a canonical organization briefing

Contract history and evidence

• Contract version: 9.12.1
• Approved snapshot SHA-256: 0f1f55d7aa33ad048b56ae7a49cf674933cf2e73b6635f606da13eb92e1534f7
• Approval: Anthony, 2026-11-03T01:45:33.272Z (anthony-docs-live-20261102)
• Download the authoritative OpenAPI 3.1 snapshot