Pipeline funnel: occupancy, flow and dwell per stage

The approved contract does not provide a longer purpose statement for this operation.

App

CRM

Contract

CRM API 3.0.0

Lifecycle

preview

Runtime

restricted

Operation ID

getFunnel

Canonical origin

Not declared; gateway routing required

Purpose and use cases

Pipeline funnel: occupancy, flow and dwell per stage

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

Business use cases and out-of-scope behavior are not yet declared in the approved OpenAPI description.

Request

GET /api/crm/v1/funnel

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:opportunities:read

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.

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

Path and query parameters

Request body

This operation declares no request body.

Runnable examples

curl '${APP_BASE_URL}/api/crm/v1/funnel' \
  --request GET \
  --header 'authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'accept: application/json'

const response = await fetch('${APP_BASE_URL}/api/crm/v1/funnel', {
  method: 'GET',
  headers: {
    authorization: `Bearer ${ACCESS_TOKEN}`,
    accept: 'application/json',
  },
}

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/funnel',
    data=None,
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>"
},
    method='GET',
)
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-funnel.v1",
  "window": {
    "from": "2026-08-21T18:00:00Z",
    "to": "2026-08-21T18:00:00Z"
  },
  "stages": [
    {
      "stage": "<stage>",
      "openCount": 1,
      "valueMinMinor": "<valueMinMinor>",
      "valueMaxMinor": "<valueMaxMinor>",
      "currency": "<currency>",
      "enteredInWindow": 1,
      "exitedInWindow": 1,
      "medianHoursInStage": "<medianHoursInStage>",
      "medianHoursOpenSoFar": "<medianHoursOpenSoFar>"
    }
  ],
  "outcomes": {
    "won": 1,
    "deferred": 1,
    "closedNotProceeding": 1,
    "byCloseReason": [
      {
        "reasonCode": "<reasonCode>",
        "count": 1
      }
    ]
  },
  "provenance": {
    "countsOpportunitiesCreatedBefore": "2026-08-21T18:00:00Z",
    "backfilledOpeningEvents": 1
  }
}

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

Collection behavior

Pagination: not declared. Filtering/search: declared through the parameters above. 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: No operation-specific limit or 429 response is declared.
• 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 detailed operation description.
• No direct server URL; gateway routing is unresolved here.
• 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: 3.0.0
• Approved snapshot SHA-256: d882d1017797e0731eee99b9a53bde41bcd39e601524cd89e2028da7f7e04ea2
• Approval: Anthony Anderson, 2026-08-21T21:22:26.555Z (crm-presentation-20260821)
• Download the authoritative OpenAPI 3.1 snapshot