{ "openapi": "3.1.0", "info": { "title": "adaptlive API", "version": "v1", "description": "Public REST API for adaptlive — the schema-of-record for live conversational work (calls, SMS, voicemails, drafts, facts, work records). Two auth paths: Bearer ApiKey (`ak_live_…` or `ak_test_…`) for external integrators, and the Clerk session cookie for the in-app cockpit. Access to /api/v1 from third-party integrators is gated per organization — contact developers@adaptlive.app to enable it on your workspace.", "contact": { "name": "adaptlive developers", "email": "developers@adaptlive.app", "url": "https://adaptlive.app/developers" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://adaptlive.app/api/v1", "description": "production" }, { "url": "/api/v1", "description": "relative (use when calling from a deployment of the platform itself)" } ], "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ApiKey", "description": "Send `Authorization: Bearer ak_live_<32-base32>` (or `ak_test_…` for sandbox). Mint and revoke keys at /settings/api-keys. Keys carry a scope: READ, WRITE, or ADMIN." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__session", "description": "Clerk session cookie used by the in-app cockpit. Not for external integrators." } }, "parameters": { "Limit": { "name": "limit", "in": "query", "description": "Page size (1–100). Defaults to 50.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor returned in the previous page's `pagination.nextCursor`. Omit on the first page.", "required": false, "schema": { "type": "string" } }, "Query": { "name": "q", "in": "query", "description": "Full-text query against the entity's searchable fields.", "required": false, "schema": { "type": "string" } }, "PathId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "EntitySlug": { "name": "entity", "in": "path", "required": true, "description": "Entity slug as listed at GET /schema. Examples: parties, work-records, field-values, field-history-entries, integration-connections.", "schema": { "type": "string" } } }, "headers": { "XRequestId": { "description": "Echoes the request's `x-request-id` (or a server-generated UUID when missing).", "schema": { "type": "string" } } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "unsupported_auth_scheme", "internal_error", "rate_limited", "idempotency_conflict" ], "description": "Stable, machine-readable code. See /developers/docs/api/errors." }, "message": { "type": "string", "description": "Human-readable description of the failure." }, "details": { "description": "Optional structured context (e.g. Zod validation issues). Shape varies per error code." } } }, "meta": { "type": "object", "required": [ "requestId" ], "properties": { "requestId": { "type": "string" } } } } }, "Pagination": { "type": "object", "required": [ "limit", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "type": [ "string", "null" ] } } }, "SchemaRecord": { "type": "object", "description": "Canonical schema record. Concrete shape depends on the entity; see GET /schema for the per-entity field list.", "additionalProperties": true }, "WorkRecord": { "type": "object", "description": "A unit of work — appointment, job, case, matter, delivery, ticket, etc.", "required": [ "id", "organizationId", "canonicalKind", "title", "recordState", "status", "stage", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "canonicalKind": { "$ref": "#/components/schemas/CanonicalWorkKind" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "recordState": { "type": "string", "enum": [ "draft", "active", "blocked", "completed", "canceled" ] }, "status": { "type": "string" }, "stage": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "source": { "type": "string", "description": "Where the record originated.", "enum": [ "call", "sms", "voicemail", "manual", "api", "import" ] }, "customerId": { "type": "string", "format": "uuid" }, "primaryPersonId": { "type": [ "string", "null" ], "format": "uuid" }, "primaryCompanyId": { "type": [ "string", "null" ], "format": "uuid" }, "primaryLocationId": { "type": [ "string", "null" ], "format": "uuid" }, "sourceCallSessionId": { "type": [ "string", "null" ], "format": "uuid" }, "structuredFieldsJson": { "type": "object", "additionalProperties": true }, "requestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "dueAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledStart": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledEnd": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CanonicalWorkKind": { "type": "string", "description": "The platform-wide canonical work kind. Most integrations map this to their own type system.", "enum": [ "job", "work_order", "matter", "case", "appointment_encounter", "permit_record", "repair_order", "move", "claim", "engagement", "arrangement", "ticket_generic", "service_request" ] }, "Person": { "type": "object", "required": [ "id", "organizationId", "displayName" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "legalName": { "type": [ "string", "null" ] }, "primaryEmail": { "type": [ "string", "null" ], "format": "email" }, "primaryPhone": { "type": [ "string", "null" ], "description": "E.164." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PhoneNumber": { "type": "object", "required": [ "id", "organizationId", "e164" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "e164": { "type": "string", "description": "E.164 (`+15551234567`)." }, "provider": { "type": "string", "description": "Telephony provider that owns the number, e.g. `twilio`." }, "providerSid": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "released", "retired" ] } } }, "Sms": { "type": "object", "required": [ "id", "organizationId", "direction", "from", "to", "body", "sentAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "from": { "type": "string", "description": "E.164." }, "to": { "type": "string", "description": "E.164." }, "body": { "type": "string" }, "threadId": { "type": [ "string", "null" ], "format": "uuid" }, "sentAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Voicemail": { "type": "object", "required": [ "id", "organizationId", "callerNumber", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "callSessionId": { "type": [ "string", "null" ], "format": "uuid" }, "callerNumber": { "type": "string" }, "transcript": { "type": [ "string", "null" ] }, "recordingUrl": { "type": [ "string", "null" ], "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Draft": { "type": "object", "required": [ "id", "organizationId", "callSessionId", "status", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "callSessionId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "pending_review", "approved", "rejected", "synced" ] }, "workRecordId": { "type": [ "string", "null" ], "format": "uuid" }, "payload": { "type": "object", "additionalProperties": true }, "approvedBy": { "type": [ "string", "null" ], "format": "uuid" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Fact": { "type": "object", "required": [ "id", "organizationId", "subjectType", "subjectId", "key", "status", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "subjectType": { "type": "string", "enum": [ "person", "company", "customer", "work_record" ] }, "subjectId": { "type": "string", "format": "uuid" }, "key": { "type": "string", "description": "Fact definition key, e.g. `gate_code`, `preferred_language`." }, "value": { "description": "Type depends on the fact definition." }, "status": { "type": "string", "enum": [ "proposed", "confirmed", "rejected", "promoted", "superseded" ] }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "sourceCallSessionId": { "type": [ "string", "null" ], "format": "uuid" }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time" }, "confirmedBy": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FactDefinition": { "type": "object", "required": [ "id", "organizationId", "key", "valueType", "subjectScope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "enum", "date", "json" ] }, "subjectScope": { "type": "string", "enum": [ "person", "company", "customer", "work_record", "polymorphic" ] }, "description": { "type": [ "string", "null" ] } } }, "Signal": { "type": "object", "required": [ "id", "organizationId", "kind", "confidence", "firedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "e.g. `complaint`, `upsell_opportunity`, `escalation`." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "callSessionId": { "type": [ "string", "null" ], "format": "uuid" }, "workRecordId": { "type": [ "string", "null" ], "format": "uuid" }, "firedAt": { "type": "string", "format": "date-time" }, "details": { "type": "object", "additionalProperties": true } } }, "WebhookSubscription": { "type": "object", "required": [ "id", "organizationId", "url", "eventTypes", "status", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "description": "Event types this subscription receives. Empty array = subscribed to all events.", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "signingSecretPreview": { "type": "string", "description": "First 12 chars of the signing secret (`whsec_...`). Full secret is returned ONCE at create time." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookEventType": { "type": "string", "enum": [ "call.ended", "sms.received", "sms.sent", "voicemail.received", "call.missed", "person.created", "work_record.created", "work_record.updated", "fact.confirmed", "fact.promoted", "draft.approved", "signal.fired", "workflow.finished", "appointment.scheduled", "task.created", "note.added" ] }, "WebhookDelivery": { "type": "object", "required": [ "id", "subscriptionId", "eventType", "status", "attemptCount", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "subscriptionId": { "type": "string", "format": "uuid" }, "eventType": { "$ref": "#/components/schemas/WebhookEventType" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "RETRYING", "DEAD_LETTERED" ] }, "attemptCount": { "type": "integer", "minimum": 0 }, "lastResponseStatus": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Message": { "type": "object", "required": [ "id", "threadId", "direction", "body", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "threadId": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "channel": { "type": "string", "enum": [ "sms", "voice", "email" ] }, "body": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "CallSurface": { "type": "object", "description": "Schema-of-record cockpit read model for one call. Combines the CallSession row, the WorkRecord being drafted, captured facts, the live transcript pointer, and surface events. See lib/api-v1/call-surface-types.ts.", "additionalProperties": true }, "SchemaRegistry": { "type": "object", "description": "Auto-generated list of canonical schema entities exposed via /{entity}.", "additionalProperties": true } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "Credentials are valid but the org is not enabled for the developer portal, or the key's scope does not permit the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "BadRequest": { "description": "Validation or shape error. `error.details` includes Zod issues when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "No record matches the given identifier (or the requester can't see it).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Rate limit exceeded. The response includes `Retry-After` (seconds) and the standard `X-RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "IdempotencyConflict": { "description": "An idempotency key was reused with a different request body. Either drop the key or use the original body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "security": [ { "bearerApiKey": [] }, { "sessionCookie": [] } ], "tags": [ { "name": "Meta", "description": "Schema registry + OpenAPI document." }, { "name": "Calls", "description": "Live and historical call data." }, { "name": "Work records", "description": "Jobs, appointments, cases, matters, deliveries, etc." }, { "name": "People", "description": "Person directory." }, { "name": "Phone numbers", "description": "Owned numbers." }, { "name": "SMS", "description": "Inbound + outbound text messages." }, { "name": "Voicemails", "description": "Caller voicemails with transcripts." }, { "name": "Drafts", "description": "Post-call drafts pending human approval." }, { "name": "Facts", "description": "Conversational facts captured during calls." }, { "name": "Signals", "description": "High-confidence event signals (complaints, upsells, etc.)." }, { "name": "Webhooks", "description": "Outbound event subscriptions + delivery introspection." }, { "name": "Generic schema", "description": "Dynamic CRUD for any registered canonical entity." } ], "paths": { "/openapi.json": { "get": { "tags": [ "Meta" ], "summary": "Return this OpenAPI document", "security": [], "responses": { "200": { "description": "The OpenAPI 3.1 spec for this API.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/schema": { "get": { "tags": [ "Meta" ], "summary": "List the canonical schema entity registry", "description": "Returns every entity slug exposed via `/{entity}` and `/{entity}/{id}`, with its scalar fields, search fields, and writeability. The Zapier app uses this for dynamic dropdowns.", "responses": { "200": { "description": "The schema registry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRegistry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/calls/{id}/surface": { "get": { "tags": [ "Calls" ], "summary": "Get the cockpit read model for one call", "description": "Combines the CallSession row, the WorkRecord being drafted, captured facts, the live transcript pointer, and surface events. Stable shape across versions — see lib/api-v1/call-surface-types.ts.", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "CallSurface envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallSurface" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/work-records": { "get": { "tags": [ "Work records" ], "summary": "List work records", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Query" }, { "name": "kind", "in": "query", "description": "Filter to one canonical kind. Used by the Zapier `job_created`, `appointment_created`, … triggers.", "required": false, "schema": { "$ref": "#/components/schemas/CanonicalWorkKind" } }, { "name": "status", "in": "query", "description": "Filter by status (free-text per org configuration).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "WorkRecord list envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Work records" ], "summary": "Create a work record", "description": "Creates a new WorkRecord. The `canonicalKind` must match an enabled WorkTypeDefinition on your org. `structuredFieldsJson` accepts the org's configured fields for that kind.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "canonicalKind", "customerId" ], "properties": { "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "canonicalKind": { "$ref": "#/components/schemas/CanonicalWorkKind" }, "customerId": { "type": "string", "format": "uuid" }, "primaryPersonId": { "type": [ "string", "null" ], "format": "uuid" }, "primaryCompanyId": { "type": [ "string", "null" ], "format": "uuid" }, "structuredFieldsJson": { "type": "object", "additionalProperties": true }, "status": { "type": "string" }, "stage": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "scheduledStart": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledEnd": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "responses": { "200": { "description": "Created WorkRecord.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/work-records/search": { "get": { "tags": [ "Work records" ], "summary": "Search work records", "description": "Free-text + filter search used by the Zapier `find_work_record` search action.", "parameters": [ { "$ref": "#/components/parameters/Query" }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CanonicalWorkKind" } }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Matching WorkRecord list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkRecord" } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/people/by-phone": { "get": { "tags": [ "People" ], "summary": "Look up a person by phone number", "description": "Used by the Zapier `find_person_by_phone` search action. Returns the first matching Person row, if any.", "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "E.164 (`+15551234567`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Matching Person (or null if none).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "type": "null" } ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/people/upsert": { "post": { "tags": [ "People" ], "summary": "Create or update a person", "description": "Idempotent by `primaryPhone` or `primaryEmail` — matches an existing Person if one is found, otherwise creates a new one. Used by the Zapier `create_or_update_person` create action.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "legalName": { "type": [ "string", "null" ] }, "primaryPhone": { "type": [ "string", "null" ], "description": "E.164." }, "primaryEmail": { "type": [ "string", "null" ], "format": "email" }, "customFields": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Upserted Person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/phone-numbers": { "get": { "tags": [ "Phone numbers" ], "summary": "List phone numbers owned by your org", "description": "Used by the Zapier `send_sms` action's dynamic dropdown for the From number.", "responses": { "200": { "description": "PhoneNumber list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/sms": { "get": { "tags": [ "SMS" ], "summary": "List SMS messages", "description": "Polling endpoint for Zapier `sms_received` / `sms_sent` triggers. Filter by direction.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "since", "in": "query", "required": false, "description": "ISO-8601. Only return messages with `sentAt >= since`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "SMS list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sms" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "SMS" ], "summary": "Send an SMS", "description": "Used by the Zapier `send_sms` create action.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" }, "to": { "type": "string", "description": "E.164." }, "personId": { "type": "string", "format": "uuid", "description": "Alternative to `to` — looks up the person's primary number." }, "fromPhoneNumberId": { "type": "string", "format": "uuid", "description": "Which owned number to send from." } } } } } }, "responses": { "200": { "description": "Queued SMS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sms" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/messages": { "get": { "tags": [ "SMS" ], "summary": "List messages across all threads", "description": "Cross-channel message list (SMS, voice notes, email when wired). Generic message-bus polling endpoint.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sms", "voice", "email" ] } } ], "responses": { "200": { "description": "Message list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/voicemails": { "get": { "tags": [ "Voicemails" ], "summary": "List voicemails", "description": "Polling endpoint for Zapier `voicemail_received` trigger.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Voicemail list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Voicemail" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/drafts": { "get": { "tags": [ "Drafts" ], "summary": "List post-call drafts", "description": "Polling endpoint for Zapier `draft_approved` trigger. Filter by `status=approved` for the trigger's poll loop.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "pending_review", "approved", "rejected", "synced" ] } } ], "responses": { "200": { "description": "Draft list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/fact-definitions": { "get": { "tags": [ "Facts" ], "summary": "List fact definitions for your org", "description": "Lookup the set of facts your org tracks (key, value type, subject scope). Use this to make sense of /facts payloads.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "FactDefinition list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FactDefinition" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/facts/{id}/confirm": { "post": { "tags": [ "Facts" ], "summary": "Confirm a proposed fact", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Updated Fact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/facts/{id}/promote": { "post": { "tags": [ "Facts" ], "summary": "Promote a fact to a broader subject (person → company / customer)", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetSubjectType": { "type": "string", "enum": [ "person", "company", "customer" ] }, "targetSubjectId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Promoted Fact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/facts/{id}/reject": { "post": { "tags": [ "Facts" ], "summary": "Reject a proposed fact", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Updated Fact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/signals": { "get": { "tags": [ "Signals" ], "summary": "List high-confidence event signals", "description": "Polling endpoint for the Zapier `signal_fired` trigger.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "kind", "in": "query", "required": false, "description": "Filter by signal kind, e.g. `complaint`, `upsell_opportunity`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signal list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook subscriptions", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "WebhookSubscription list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook subscription", "description": "Returns the full `signingSecret` ONCE in the response — store it, then verify incoming events with HMAC-SHA256 of `${timestamp}.${rawBody}` against the secret. See /developers/docs/api/webhooks for verifier code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "description": "Event types to subscribe to. Omit or send `[]` to subscribe to all events.", "items": { "$ref": "#/components/schemas/WebhookEventType" } } } } } } }, "responses": { "200": { "description": "Created subscription. `signingSecret` is shown ONCE.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscription" }, { "type": "object", "properties": { "signingSecret": { "type": "string", "description": "Full `whsec_…` secret. Shown ONCE." } } } ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get one webhook subscription", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "WebhookSubscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook subscription (URL, event types, status)", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] } } } } } }, "responses": { "200": { "description": "Updated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook subscription", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Deletion acknowledged." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List delivery attempts for one subscription", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "RETRYING", "DEAD_LETTERED" ] } } ], "responses": { "200": { "description": "WebhookDelivery list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks/{id}/deliveries/{deliveryId}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Replay a webhook delivery attempt", "description": "Re-fires the saved payload at the subscription's current URL with a fresh signature. Useful for debugging a receiver that was down when the event originally fired.", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Replayed delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/{entity}": { "get": { "tags": [ "Generic schema" ], "summary": "List records for any registered canonical entity", "description": "Entity slugs come from /schema. Examples: parties, work-records, integration-connections, external-refs, field-values, field-history-entries.", "parameters": [ { "$ref": "#/components/parameters/EntitySlug" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Query" } ], "responses": { "200": { "description": "Generic list envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Generic schema" ], "summary": "Create / upsert one record for any registered canonical entity", "parameters": [ { "$ref": "#/components/parameters/EntitySlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRecord" } } } }, "responses": { "200": { "description": "Persisted record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } } } }, "/{entity}/{id}": { "get": { "tags": [ "Generic schema" ], "summary": "Get one record", "parameters": [ { "$ref": "#/components/parameters/EntitySlug" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Generic schema" ], "summary": "Partially update one record", "parameters": [ { "$ref": "#/components/parameters/EntitySlug" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRecord" } } } }, "responses": { "200": { "description": "Updated record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Generic schema" ], "summary": "Replace/upsert writable fields for one record", "parameters": [ { "$ref": "#/components/parameters/EntitySlug" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRecord" } } } }, "responses": { "200": { "description": "Persisted record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } } }