{ "openapi": "3.0.0", "info": { "title": "SparrowDesk Developer API", "version": "1.0.0" }, "servers": [ { "url": "https://app.sparrowdesk.com/v1", "description": "SparrowDesk Developer API Host" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "token" } }, "schemas": { "ReplyImportAttachment": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Publicly reachable URL of the attachment to fetch and store" }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional request headers used when fetching the attachment URL" } } }, "ReplyImport": { "type": "object", "description": "A single historical reply. Either author_id or author_email must be provided to resolve the reply author.", "required": [ "author_type", "html_body", "created_at" ], "properties": { "external_id": { "type": "string", "maxLength": 255, "description": "Caller-supplied id used for idempotency/deduplication" }, "author_type": { "type": "string", "enum": [ "agent", "requester" ] }, "author_id": { "type": "integer", "minimum": 1, "description": "SparrowDesk author id (provide this or author_email)" }, "author_email": { "type": "string", "format": "email", "description": "Author email, resolved to an author (provide this or author_id)" }, "public": { "type": "boolean", "default": true, "description": "Whether the reply is public (false = internal note)" }, "html_body": { "type": "string", "minLength": 1 }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp with offset. Must not be in the future." }, "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ReplyImportAttachment" } } } }, "EmbeddedNotes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/zoona/start": { "post": { "operationId": "startZoonaConversation", "summary": "Start conversation", "tags": [ "Zoona" ], "parameters": [ { "in": "header", "name": "idempotency-key", "required": false, "description": "Optional idempotency key. Repeating the same key with an identical body returns the cached response for 5 minutes; a different body returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "attributes": { "type": "object", "additionalProperties": true } } }, "session_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Opaque session token returned by a previous /zoona/start call. Pass it to continue an existing session instead of starting a fresh one." }, "message": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Conversation accepted for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "status": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "session_token": { "type": "string", "description": "Session token to reuse on subsequent /zoona/start calls to continue this session." }, "identity_state": { "type": "string", "enum": [ "anonymous", "identified" ], "description": "Whether the session is tied to an identified user (id/email supplied) or anonymous." } } } } } }, "400": { "description": "Invalid request body or missing API key context" }, "401": { "description": "Missing or invalid bearer token" }, "409": { "description": "Idempotency key was reused with a different body" }, "422": { "description": "Request body failed validation" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } } } }, "/zoona/reply": { "post": { "operationId": "sendZoonaReply", "summary": "Add reply", "tags": [ "Zoona" ], "parameters": [ { "in": "header", "name": "idempotency-key", "required": false, "description": "Optional idempotency key (same semantics as /zoona/start)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conversation_id", "message" ], "properties": { "conversation_id": { "type": "string" }, "message": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "responses": { "202": { "description": "Reply accepted for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "status": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid request body or missing API key context" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "API channel is not enabled for this agent" }, "404": { "description": "Conversation not found" }, "409": { "description": "Idempotency key was reused with a different body" }, "422": { "description": "Request body failed validation" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } } } }, "/webhooks": { "post": { "operationId": "createWebhookTarget", "summary": "Subscribe a webhook target", "description": "Registers an endpoint URL to receive deliveries for a supported event type. Requires the \"MANAGE_WEBHOOKS\" scope and the account's plan to include the Webhooks feature. The response's signing_secret is shown once and used to verify the X-Sparrowdesk-Signature header on each delivery.", "tags": [ "Webhook Targets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "endpoint_url", "event_type" ], "properties": { "endpoint_url": { "type": "string", "format": "uri", "example": "https://hooks.zapier.com/hooks/standard/123456/abcdef/" }, "event_type": { "type": "string", "example": "conversation.created" } } } } } }, "responses": { "201": { "description": "Webhook target created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "endpoint_url": { "type": "string" }, "event_type": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "integer" }, "signing_secret": { "type": "string" } } } } } } } }, "400": { "description": "Invalid endpoint_url/event_type, or target limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } }, "get": { "operationId": "listWebhookTargets", "summary": "List all webhook targets on the account", "description": "Returns every webhook target on the account, regardless of which credential created it.", "tags": [ "Webhook Targets" ], "responses": { "200": { "description": "Webhook targets retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "endpoint_url": { "type": "string" }, "event_type": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "integer" } } } }, "total_count": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } } }, "/webhooks/{id}": { "delete": { "operationId": "deleteWebhookTarget", "summary": "Unsubscribe a webhook target", "description": "Any authenticated credential on the account can remove any webhook target, regardless of which credential created it.", "tags": [ "Webhook Targets" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook target removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } }, "404": { "description": "Webhook target not found (or not owned by the calling credential)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } } }, "/tags": { "get": { "operationId": "listTags", "summary": "List all tags", "tags": [ "Tags" ], "parameters": [ { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true }, "examples": { "withCursor": { "value": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=", "summary": "With pagination cursor" }, "withoutCursor": { "summary": "First page (no cursor)" } } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "nullable": true } }, { "in": "query", "name": "search", "required": false, "description": "Search tags by name", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved tags list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000001 }, "name": { "type": "string", "example": "bug" }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1672531200 } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=" }, "next_url": { "type": "string", "nullable": true, "example": "https://api.sparrowdesk.com/tags?per_page=25&starting_after=eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=" } } }, "total_count": { "type": "integer", "example": 156 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid query parameters" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Resource not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "An error occurred while retrieving tags" } } } } } } } } } } }, "/contacts/{contactId}/notes": { "get": { "operationId": "listContactNotes", "summary": "List all contact notes", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "starting_after", "required": false, "description": "Cursor from a previous response's pages.next_cursor", "schema": { "type": "string" } }, { "in": "query", "name": "per_page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Notes retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1837 }, "contact_id": { "type": "integer", "nullable": true, "example": 8821 }, "company_id": { "type": "integer", "nullable": true, "example": null }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 904 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/contract.pdf" }, "file_name": { "type": "string", "example": "contract.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 20481 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "nullable": true, "example": "John Doe" }, "email": { "type": "string", "nullable": true, "example": "john.doe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 57 }, "name": { "type": "string", "nullable": true, "example": "Jane Doe" }, "email": { "type": "string", "nullable": true, "example": "jane.doe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string", "description": "Absent on the last page", "example": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMVQxMjowMDowMC4wMDBaIiwiaWQiOjE4MzZ9" }, "next_url": { "type": "string", "description": "Absent on the last page", "example": "https://api.sparrowdesk.com/v1/contacts/8821/notes?starting_after=eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMVQxMjowMDowMC4wMDBaIiwiaWQiOjE4MzZ9&per_page=25" } } }, "total_count": { "type": "integer", "example": 128 } } } } } }, "400": { "description": "Invalid cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid cursor" } } } } } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact not found" } } } } } } } }, "422": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Required" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } }, "post": { "operationId": "createContactNote", "summary": "Create a contact note", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "attachments": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly reachable URL. The file is fetched server-side and re-hosted; the caller never uploads bytes. A URL already pointing at SparrowDesk storage is recognised and kept rather than fetched again, so a note can be edited by sending back what a GET returned.\n", "example": "https://example.com/contract.pdf" }, "file_name": { "type": "string", "example": "contract.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "example": 20481 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Sent when fetching the URL. Never returned.\n" } } } } } } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1837 }, "contact_id": { "type": "integer", "nullable": true, "example": 8821 }, "company_id": { "type": "integer", "nullable": true, "example": null }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 904 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/contract.pdf" }, "file_name": { "type": "string", "example": "contract.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 20481 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "nullable": true, "example": "John Doe" }, "email": { "type": "string", "nullable": true, "example": "john.doe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 57 }, "name": { "type": "string", "nullable": true, "example": "Jane Doe" }, "email": { "type": "string", "nullable": true, "example": "jane.doe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } } } } } }, "400": { "description": "Description over the cap, attachment too large or of an unsupported type, attachment fetch failed, or the API key has no member attached\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Description must not exceed 10000 characters" } } } } } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact not found" } } } } } } } }, "422": { "description": "Invalid body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Required" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } } }, "/contacts/notes/{id}": { "get": { "operationId": "retrieveContactNote", "summary": "Retrieve a contact note", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the note", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The note", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1837 }, "contact_id": { "type": "integer", "nullable": true, "example": 8821 }, "company_id": { "type": "integer", "nullable": true, "example": null }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 904 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/contract.pdf" }, "file_name": { "type": "string", "example": "contract.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 20481 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "nullable": true, "example": "John Doe" }, "email": { "type": "string", "nullable": true, "example": "john.doe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 57 }, "name": { "type": "string", "nullable": true, "example": "Jane Doe" }, "email": { "type": "string", "nullable": true, "example": "jane.doe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } } } } } }, "404": { "description": "Contact or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Note not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } }, "patch": { "operationId": "updateContactNote", "summary": "Update a contact note", "description": "Only the fields sent are changed. Sending `attachments` replaces the whole set — include the SparrowDesk urls of the attachments to keep.\n", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the note", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "attachments": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly reachable URL. The file is fetched server-side and re-hosted; the caller never uploads bytes. A URL already pointing at SparrowDesk storage is recognised and kept rather than fetched again, so a note can be edited by sending back what a GET returned.\n", "example": "https://example.com/contract.pdf" }, "file_name": { "type": "string", "example": "contract.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "example": 20481 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Sent when fetching the URL. Never returned.\n" } } } } } } } } }, "responses": { "200": { "description": "Note updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1837 }, "contact_id": { "type": "integer", "nullable": true, "example": 8821 }, "company_id": { "type": "integer", "nullable": true, "example": null }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 904 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/contract.pdf" }, "file_name": { "type": "string", "example": "contract.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 20481 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "nullable": true, "example": "John Doe" }, "email": { "type": "string", "nullable": true, "example": "john.doe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 57 }, "name": { "type": "string", "nullable": true, "example": "Jane Doe" }, "email": { "type": "string", "nullable": true, "example": "jane.doe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } } } } } }, "400": { "description": "Validation failed on the note or one of its attachments", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Attachment exceeds the maximum size allowed for its type" } } } } } } } }, "404": { "description": "Contact or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Note not found" } } } } } } } }, "422": { "description": "Invalid body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Required" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } }, "delete": { "operationId": "deleteContactNote", "summary": "Delete a contact note", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the note", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Note deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } } }, "404": { "description": "Contact or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Note not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } } }, "/companies/{companyId}/notes": { "get": { "operationId": "listCompanyNotes", "summary": "List all company notes", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "companyId", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "per_page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Notes retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1902 }, "contact_id": { "type": "integer", "nullable": true, "example": null }, "company_id": { "type": "integer", "nullable": true, "example": 4410 }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1120 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/master-services-agreement.pdf" }, "file_name": { "type": "string", "example": "master-services-agreement.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 88214 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 61 }, "name": { "type": "string", "nullable": true, "example": "Richard Roe" }, "email": { "type": "string", "nullable": true, "example": "richard.roe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 73 }, "name": { "type": "string", "nullable": true, "example": "Jane Roe" }, "email": { "type": "string", "nullable": true, "example": "jane.roe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string", "description": "Absent on the last page", "example": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMVQxMjowMDowMC4wMDBaIiwiaWQiOjE4MzZ9" }, "next_url": { "type": "string", "description": "Absent on the last page", "example": "https://api.sparrowdesk.com/v1/companies/4410/notes?starting_after=eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMVQxMjowMDowMC4wMDBaIiwiaWQiOjE4MzZ9&per_page=25" } } }, "total_count": { "type": "integer", "example": 128 } } } } } }, "400": { "description": "Invalid cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid cursor" } } } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Company not found" } } } } } } } }, "422": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Required" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } }, "post": { "operationId": "createCompanyNote", "summary": "Create a company note", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "companyId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "attachments": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly reachable URL. The file is fetched server-side and re-hosted; the caller never uploads bytes. A URL already pointing at SparrowDesk storage is recognised and kept rather than fetched again, so a note can be edited by sending back what a GET returned.\n", "example": "https://example.com/master-services-agreement.pdf" }, "file_name": { "type": "string", "example": "master-services-agreement.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "example": 88214 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Sent when fetching the URL. Never returned.\n" } } } } } } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1902 }, "contact_id": { "type": "integer", "nullable": true, "example": null }, "company_id": { "type": "integer", "nullable": true, "example": 4410 }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1120 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/master-services-agreement.pdf" }, "file_name": { "type": "string", "example": "master-services-agreement.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 88214 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 61 }, "name": { "type": "string", "nullable": true, "example": "Richard Roe" }, "email": { "type": "string", "nullable": true, "example": "richard.roe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 73 }, "name": { "type": "string", "nullable": true, "example": "Jane Roe" }, "email": { "type": "string", "nullable": true, "example": "jane.roe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } } } } } }, "400": { "description": "Validation failed, or the API key has no member attached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Description must not exceed 10000 characters" } } } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Company not found" } } } } } } } }, "422": { "description": "Invalid body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Required" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } } }, "/companies/notes/{id}": { "get": { "operationId": "retrieveCompanyNote", "summary": "Retrieve a company note", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the note", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The note", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1902 }, "contact_id": { "type": "integer", "nullable": true, "example": null }, "company_id": { "type": "integer", "nullable": true, "example": 4410 }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1120 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/master-services-agreement.pdf" }, "file_name": { "type": "string", "example": "master-services-agreement.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 88214 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 61 }, "name": { "type": "string", "nullable": true, "example": "Richard Roe" }, "email": { "type": "string", "nullable": true, "example": "richard.roe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 73 }, "name": { "type": "string", "nullable": true, "example": "Jane Roe" }, "email": { "type": "string", "nullable": true, "example": "jane.roe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } } } } } }, "404": { "description": "Company or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Note not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } }, "patch": { "operationId": "updateCompanyNote", "summary": "Update a company note", "description": "Only the fields sent are changed. Sending `attachments` replaces the whole set — include the SparrowDesk urls of the attachments to keep.\n", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the note", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "attachments": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly reachable URL. The file is fetched server-side and re-hosted; the caller never uploads bytes. A URL already pointing at SparrowDesk storage is recognised and kept rather than fetched again, so a note can be edited by sending back what a GET returned.\n", "example": "https://example.com/master-services-agreement.pdf" }, "file_name": { "type": "string", "example": "master-services-agreement.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "example": 88214 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Sent when fetching the URL. Never returned.\n" } } } } } } } } }, "responses": { "200": { "description": "Note updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1902 }, "contact_id": { "type": "integer", "nullable": true, "example": null }, "company_id": { "type": "integer", "nullable": true, "example": 4410 }, "title": { "type": "string", "nullable": true, "description": "Markdown. Not length limited.", "example": "Renewal call" }, "description": { "type": "string", "description": "Markdown. Limited to 10000 characters of prose; inline attachment references do not count towards that limit.\n", "example": "Wants the annual plan. Sending the contract." }, "source": { "type": "string", "enum": [ "manual", "api" ], "example": "api" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1120 }, "url": { "type": "string", "example": "https://attachments.sparrowdesk.com/helpdesk-application/production/6f1c/note-attachments/master-services-agreement.pdf" }, "file_name": { "type": "string", "example": "master-services-agreement.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Size in bytes", "example": 88214 }, "status": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY", "FAILED", "MARKED_FOR_DELETION" ], "example": "READY" } } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 61 }, "name": { "type": "string", "nullable": true, "example": "Richard Roe" }, "email": { "type": "string", "nullable": true, "example": "richard.roe@example.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 73 }, "name": { "type": "string", "nullable": true, "example": "Jane Roe" }, "email": { "type": "string", "nullable": true, "example": "jane.roe@example.com" } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1758537600 } } } } } } } }, "400": { "description": "Validation failed on the note or one of its attachments", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Attachment exceeds the maximum size allowed for its type" } } } } } } } }, "404": { "description": "Company or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Note not found" } } } } } } } }, "422": { "description": "Invalid body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Required" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } }, "delete": { "operationId": "deleteCompanyNote", "summary": "Delete a company note", "tags": [ "Notes" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the note", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Note deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } } }, "404": { "description": "Company or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Note not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Internal server error" } } } } } } } } } } }, "/members": { "get": { "operationId": "listMembers", "summary": "List all members", "tags": [ "Members" ], "parameters": [ { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true }, "examples": { "withCursor": { "value": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=", "summary": "With pagination cursor" }, "withoutCursor": { "summary": "First page (no cursor)" } } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved members list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000096 }, "email": { "type": "string", "example": "john.doe@example.com" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "phone": { "type": "string", "nullable": true, "example": "+1234567890" }, "profile_pic": { "type": "string", "nullable": true, "example": "https://public.cdn.sparrowdesk.com/example.jpeg" }, "is_copilot_seat_alloted": { "type": "boolean", "example": true }, "verified": { "type": "boolean", "example": true }, "role": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000153 }, "label": { "type": "string", "example": "Account Owner" } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000006 }, "label": { "type": "string", "example": "dev" } } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1672531200 } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=" }, "next_url": { "type": "string", "nullable": true, "example": "https://api.sparrowdesk.com/members?per_page=25&starting_after=eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=" } } }, "total_count": { "type": "integer", "example": 156 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid query parameters" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Resource not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "An error occurred while retrieving members" } } } } } } } } } } }, "/helpcenters": { "get": { "operationId": "listHelpCenters", "summary": "List all help centers", "tags": [ "Help Centers" ], "parameters": [ { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page (1-100, default 30)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30, "nullable": true } } ], "responses": { "200": { "description": "Paginated help centers for the authenticated account", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 994 }, "name": { "type": "string", "nullable": true, "example": "Product help" }, "status": { "type": "string", "nullable": true, "example": "ACTIVE" }, "access_type": { "type": "string", "nullable": true, "example": "PUBLIC" }, "favicon": { "type": "string", "nullable": true }, "seo_title": { "type": "string", "nullable": true }, "seo_description": { "type": "string", "nullable": true }, "seo_image": { "type": "string", "nullable": true }, "brand": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "nullable": true, "example": "Acme" } } }, "domain": { "type": "object", "nullable": true, "properties": { "url": { "type": "string", "nullable": true, "example": "support.acme.com" }, "https": { "type": "boolean", "nullable": true, "example": true }, "active": { "type": "boolean", "nullable": true, "example": true }, "verified": { "type": "boolean", "nullable": true, "example": true } } }, "created_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 30 }, "next_cursor": { "type": "string", "nullable": true }, "next_url": { "type": "string", "nullable": true } } }, "total_count": { "type": "integer", "example": 2 } } } } } }, "400": { "description": "Bad request (e.g. malformed starting_after cursor)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid cursor" } } } } } } } }, "403": { "description": "Forbidden – missing scope or feature", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Missing required scope or product feature is not enabled for this account." } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred while loading help centers." } } } } } } } } } } }, "/conversations": { "get": { "operationId": "listConversations", "summary": "List all conversations", "tags": [ "Conversations" ], "parameters": [ { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true }, "examples": { "withCursor": { "value": "eyJpZCI6MTIzNDUsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9", "summary": "With pagination cursor" }, "withoutCursor": { "summary": "First page (no cursor)" } } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true } }, { "in": "query", "name": "status", "required": false, "description": "Filter by conversation status", "schema": { "type": "array", "items": { "type": "string", "enum": [ "Open", "Pending", "Resolved", "Closed" ] }, "nullable": true } }, { "in": "query", "name": "priority", "required": false, "description": "Filter by priority level", "schema": { "type": "array", "items": { "type": "string", "enum": [ "Low", "Medium", "High", "Urgent" ] }, "nullable": true } }, { "in": "query", "name": "assigned_to_member_id", "required": false, "description": "Filter by assigned agent IDs", "schema": { "type": "array", "items": { "type": "integer" }, "nullable": true } }, { "in": "query", "name": "assigned_to_team_id", "required": false, "description": "Filter by assigned team IDs", "schema": { "type": "array", "items": { "type": "integer" }, "nullable": true } }, { "in": "query", "name": "brand_id", "required": false, "description": "Filter by brand IDs", "schema": { "type": "array", "items": { "type": "integer" }, "nullable": true } }, { "in": "query", "name": "requested_by_id", "required": false, "description": "Filter by requester contact id(s). Omit (with no requested_by_company) to list all conversations. With requested_by_company, only requesters in both filters are returned (intersection).", "schema": { "type": "integer", "nullable": true } }, { "in": "query", "name": "requested_by_company", "required": false, "description": "Filter by requester contact company id. Omit (with no requested_by_id) to list all conversations. With requested_by_id, only requesters matching both filters are returned (intersection).", "schema": { "type": "integer", "nullable": true } }, { "in": "query", "name": "handled_by_ai_agent", "required": false, "description": "When omitted, no filter by AI handling. `true` — only conversations assigned to an AI agent. `false` — conversations handed off for human help,\nor where the assignee is not an AI agent.\n", "schema": { "type": "string", "enum": [ true, false ], "nullable": true } }, { "in": "query", "name": "search", "required": false, "description": "Search by subject, description, replies, or conversation ID. Use quotes for exact phrases.\n", "schema": { "type": "string", "maxLength": 250, "nullable": true } }, { "in": "query", "name": "sort_by", "required": false, "description": "Field to sort by (default created_at)", "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "nullable": true } }, { "in": "query", "name": "sort_order", "required": false, "description": "Sort order (default desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ], "nullable": true } } ], "responses": { "200": { "description": "Conversations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "brand": { "type": "string", "example": "Support Brand" }, "brand_id": { "type": "integer", "example": 12345 }, "source": { "type": "string", "example": "Mail" }, "status": { "type": "string", "example": "Open" }, "priority": { "type": "string", "example": "High" }, "created_at": { "type": "integer", "example": 1672531200 }, "first_response_time": { "type": "integer", "nullable": true, "example": 1672534800 }, "resolution_time": { "type": "integer", "nullable": true, "example": null }, "due": { "type": "integer", "nullable": true, "example": 1672617600 }, "first_response_due": { "type": "integer", "nullable": true, "example": 1672538400 }, "requested_by_email": { "type": "string", "format": "email", "example": "customer@example.com" }, "requested_by_phone": { "type": "string", "example": "+1415555267" }, "requested_by_id": { "type": "integer", "example": 67890 }, "assigned_to_member_id": { "type": "integer", "nullable": true, "example": 123 }, "assigned_to_team_id": { "type": "integer", "nullable": true, "example": 456 }, "last_updated_at": { "type": "integer", "example": 1672535400 }, "subject": { "type": "string", "example": "Payment issue with order #12345" }, "description_html": { "type": "string", "example": "

I'm having trouble with my payment...

" }, "description_text": { "type": "string", "example": "I'm having trouble with my payment..." }, "attachments": { "type": "array", "description": "URLs of attachments sent on the opening message", "items": { "type": "string" }, "example": [ "https://cdn.example.com/receipt.pdf" ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "label": { "type": "string", "example": "billing" } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 9250 }, "value": { "description": "Field value. A multi_select field reads back as its selected option names joined with \", \" in option order; its ordered option ids are in option_ids. A boolean field reads back as true or false.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "example": "ORD-12345" }, "option_ids": { "type": "array", "nullable": true, "description": "Ordered option ids of a multi_select selection; null for every other field type", "items": { "type": "integer" }, "example": [ 7790, 7791 ] } } } }, "csat": { "type": "object", "properties": { "score": { "type": "integer", "nullable": true, "example": 4, "description": "Numeric CSAT score submitted by the customer" }, "sentiment": { "type": "string", "nullable": true, "example": "positive", "description": "Sentiment derived from the score: positive, neutral, or negative" }, "feedback": { "type": "string", "nullable": true, "example": "Great support experience!", "description": "Free-text feedback submitted by the customer" }, "scale": { "type": "integer", "nullable": true, "example": 5, "description": "The scale used for the CSAT survey (e.g. 5 or 10)" } } }, "properties": { "type": "object", "properties": { "request_language": { "type": "string", "example": "English" }, "browser_timezone": { "type": "string", "example": "Asia/Calcutta" }, "browser": { "type": "string", "example": "Chrome" }, "device": { "type": "string", "example": "mac OS 10.15.7" }, "ip_address": { "type": "string", "example": "192.168.1.1" }, "country": { "type": "string", "example": "India" }, "region": { "type": "string", "example": "Tamil Nadu > Chennai" } } } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 20 }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJpZCI6MTIzNDUsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9" }, "next_url": { "type": "string", "nullable": true, "example": "https://app.sparrowdesk.com/conversations?per_page=20&starting_after=eyJpZCI6MTIzNDUsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9" } } }, "total_count": { "type": "integer", "example": 100 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid query parameters" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error retrieving conversations" } } } } } } } } } }, "post": { "operationId": "createConversation", "summary": "Create a conversation", "tags": [ "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description", "subject", "requested_by" ], "properties": { "description": { "type": "string", "description": "Opening message body (HTML). Inline images hosted on supported source platforms are fetched and re-hosted automatically, with their links rewritten." }, "subject": { "type": "string" }, "priority": { "type": "string", "enum": [ "Low", "Medium", "High", "Urgent" ], "description": "Priority level (defaults to Medium if not provided)" }, "source": { "type": "string", "enum": [ "Mail", "Call", "API" ], "description": "Conversation source (defaults to Call if not provided)" }, "brand_id": { "type": "number", "description": "Brand ID (defaults to account's default brand if not provided)" }, "status": { "type": "string", "enum": [ "Open", "Pending", "Resolved", "Closed" ], "description": "Status (defaults to Open if not provided)" }, "requested_by": { "type": "string", "description": "Requested by email or phone number" }, "requested_by_firstname": { "type": "string", "description": "First name applied to the requester contact only when it is created. If a contact with this email/phone already exists, it is reused and its name is not changed." }, "requested_by_lastname": { "type": "string", "description": "Last name applied to the requester contact only when it is created (same create-only behaviour as requested_by_firstname)." }, "assignee": { "type": "string", "format": "email" }, "team_id": { "type": "number" }, "created_at": { "type": "integer", "description": "The time the conversation was created (epoch seconds). If not provided, the current time is used.", "example": 1672531200 }, "resolved_at": { "type": "integer", "description": "The time the conversation was resolved (epoch seconds). Only allowed when status is Resolved or Closed, and must be >= created_at.", "example": 1672617600 }, "skip_notifications": { "type": "boolean", "description": "Option to disable notifications when a Conversation is created. Defaults to false." }, "custom_fields": { "type": "array", "items": { "type": "object", "required": [ "internal_name", "value" ], "properties": { "internal_name": { "type": "string" }, "value": { "description": "Field value. For multi_select fields, an array of option ids or option names (a single id/name is treated as a one-element array). For url fields, an http or https URL (max 2000 characters; a bare domain is saved with https://). For boolean fields, JSON true or false.", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ] } } } }, "tags": { "type": "array", "description": "Tag labels to attach to the conversation. Tags that don't exist are created. Also useful for recording the channel/origin (e.g. \"chat\", \"email\").", "items": { "type": "string" } }, "attachments": { "type": "array", "description": "Files fetched from these URLs and attached to the conversation's opening message. If a file can't be fetched, the conversation is still created and that file is skipped.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public URL the file is fetched from and re-hosted." }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "description": "Size in bytes." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional headers sent when fetching the URL (e.g. auth)." } } } } } } } } }, "responses": { "201": { "description": "Conversation created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "brand": { "type": "string", "example": "Support Brand" }, "brand_id": { "type": "integer", "example": 1 }, "source": { "type": "string", "example": "Mail" }, "status": { "type": "string", "example": "Open" }, "priority": { "type": "string", "example": "High" }, "created_at": { "type": "integer", "example": 1672531200 }, "first_response_time": { "type": "integer", "nullable": true, "example": null }, "resolution_time": { "type": "integer", "nullable": true, "example": null }, "due": { "type": "integer", "nullable": true, "example": 1672617600 }, "first_response_due": { "type": "integer", "nullable": true, "example": 1672538400 }, "requested_by_email": { "type": "string", "format": "email", "example": "customer@example.com" }, "requested_by_id": { "type": "integer", "example": 67890 }, "assigned_to_member_id": { "type": "integer", "nullable": true, "example": 123 }, "assigned_to_team_id": { "type": "integer", "nullable": true, "example": 456 }, "last_updated_at": { "type": "integer", "example": 1672535400 }, "subject": { "type": "string", "example": "Payment issue with order #12345" }, "description_html": { "type": "string", "example": "

I'm having trouble with my payment...

" }, "description_text": { "type": "string", "example": "I'm having trouble with my payment..." }, "attachments": { "type": "array", "description": "URLs of attachments sent on the opening message", "items": { "type": "string" }, "example": [ "https://cdn.example.com/receipt.pdf" ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "label": { "type": "string", "example": "billing" } } }, "example": [ { "id": 1, "label": "billing" }, { "id": 2, "label": "urgent" } ] }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 9250 }, "value": { "description": "Field value. A multi_select field reads back as its selected option names joined with \", \" in option order; its ordered option ids are in option_ids. A boolean field reads back as true or false.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "example": "ORD-12345" }, "option_ids": { "type": "array", "nullable": true, "description": "Ordered option ids of a multi_select selection; null for every other field type", "items": { "type": "integer" }, "example": [ 7790, 7791 ] } } }, "example": [ { "id": 9250, "value": "ORD-12345", "option_ids": null }, { "id": 9260, "value": "premium", "option_ids": null }, { "id": 9270, "value": "Bug, Billing", "option_ids": [ 7790, 7791 ] } ] }, "properties": { "type": "object", "properties": { "request_language": { "type": "string", "example": "English" }, "browser_timezone": { "type": "string", "example": "Asia/Calcutta" }, "browser": { "type": "string", "example": "Chrome" }, "device": { "type": "string", "example": "mac OS 10.15.7" }, "ip_address": { "type": "string", "example": "192.168.1.1" }, "country": { "type": "string", "example": "India" }, "region": { "type": "string", "example": "Tamil Nadu > Chennai" }, "referral_url": { "type": "string", "example": "http://localhost:9091/" }, "utm_source": { "type": "string", "example": "" }, "utm_medium": { "type": "string", "example": "" }, "utm_campaign": { "type": "string", "example": "" }, "utm_content": { "type": "string", "example": "" }, "utm_term": { "type": "string", "example": "" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid field values" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while creating conversation" } } } } } } } } } } }, "/conversations/with-replies": { "get": { "operationId": "listConversationsWithReplies", "summary": "List all conversations with replies", "description": "Conversation list uses the same filters and `starting_after` cursor as GET /conversations (`per_page` max 20).\nRoot `pages` / `total_count` apply to conversations only. Each row includes `replies` with the same shape as\nGET /conversations/{id}/replies (`data`, `pages`, `total_count`). Use `replies_per_page` (max 50),\n`replies_sort_order`, and `type` for the embedded reply page. For more replies on a row, call\nGET /conversations/{id}/replies with `starting_after` = `replies.pages.next_cursor`, or follow\n`replies.pages.next_url` when returned.\n", "tags": [ "Conversations" ], "parameters": [ { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for conversation list pagination", "schema": { "type": "string", "nullable": true } }, { "in": "query", "name": "per_page", "required": false, "description": "Conversations per page (1–20, default 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } }, { "in": "query", "name": "replies_per_page", "required": false, "description": "Replies per conversation (1–50, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "in": "query", "name": "replies_sort_order", "required": false, "description": "Reply list sort by sent_at (default desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "in": "query", "name": "type", "required": false, "description": "Filter replies by type", "schema": { "type": "string", "enum": [ "INTERNAL_NOTE", "REPLY" ] } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "priority", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "assigned_to_member_id", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "in": "query", "name": "assigned_to_team_id", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "in": "query", "name": "brand_id", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "in": "query", "name": "requested_by_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "handled_by_ai_agent", "required": false, "description": "Same as GET /conversations `handled_by_ai_agent`. Omitted — no filter by AI handling. `true` — only conversations assigned to an AI agent.\n`false` — conversations handed off for human help, or where the assignee is not an AI agent.\n", "schema": { "type": "string", "enum": [ true, false ] } }, { "in": "query", "name": "search", "required": false, "description": "Search by subject, description, replies, or conversation ID. Use quotes for exact phrases.\n", "schema": { "type": "string", "maxLength": 250 } }, { "in": "query", "name": "sort_by", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ] } }, { "in": "query", "name": "sort_order", "required": false, "description": "Sort order for the conversation list", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Conversations with nested replies" }, "400": { "description": "Bad request" }, "404": { "description": "Conversation not found (while loading replies)" }, "500": { "description": "Internal server error" } } } }, "/conversations/{id}": { "get": { "operationId": "retrieveConversation", "summary": "Retrieve a conversation", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Conversation id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversation retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "brand": { "type": "string", "example": "Support Brand" }, "brand_id": { "type": "integer", "example": 12345 }, "source": { "type": "string", "example": "Mail" }, "status": { "type": "string", "example": "Open" }, "priority": { "type": "string", "example": "High" }, "created_at": { "type": "integer", "example": 1672531200 }, "first_response_time": { "type": "integer", "nullable": true, "example": 1672534800 }, "resolution_time": { "type": "integer", "nullable": true, "example": null }, "due": { "type": "integer", "nullable": true, "example": 1672617600 }, "first_response_due": { "type": "integer", "nullable": true, "example": 1672538400 }, "requested_by_email": { "type": "string", "format": "email", "example": "customer@example.com" }, "requested_by_id": { "type": "integer", "example": 67890 }, "assigned_to_member_id": { "type": "integer", "nullable": true, "example": 123 }, "assigned_to_team_id": { "type": "integer", "nullable": true, "example": 456 }, "last_updated_at": { "type": "integer", "example": 1672535400 }, "subject": { "type": "string", "example": "Payment issue with order #12345" }, "description_html": { "type": "string", "example": "

I'm having trouble with my payment...

" }, "description_text": { "type": "string", "example": "I'm having trouble with my payment..." }, "attachments": { "type": "array", "description": "URLs of attachments sent on the opening message", "items": { "type": "string" }, "example": [ "https://cdn.example.com/receipt.pdf" ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "label": { "type": "string", "example": "billing" } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 9250 }, "value": { "description": "Field value. A multi_select field reads back as its selected option names joined with \", \" in option order; its ordered option ids are in option_ids. A boolean field reads back as true or false.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "example": "ORD-12345" }, "conversation_field_id": { "type": "integer", "example": 2771 }, "option_id": { "type": "integer", "example": 1817 }, "option_ids": { "type": "array", "nullable": true, "description": "Ordered option ids of a multi_select selection; null for every other field type", "items": { "type": "integer" }, "example": [ 7790, 7791 ] } } } }, "csat": { "type": "object", "properties": { "score": { "type": "integer", "nullable": true, "example": 4, "description": "Numeric CSAT score submitted by the customer" }, "sentiment": { "type": "string", "nullable": true, "example": "positive", "description": "Sentiment derived from the score: positive, neutral, or negative" }, "feedback": { "type": "string", "nullable": true, "example": "Great support experience!", "description": "Free-text feedback submitted by the customer" }, "scale": { "type": "integer", "nullable": true, "example": 5, "description": "The scale used for the CSAT survey (e.g. 5 or 10)" } } }, "properties": { "type": "object", "properties": { "request_language": { "type": "string", "example": "English" }, "browser_timezone": { "type": "string", "example": "Asia/Calcutta" }, "browser": { "type": "string", "example": "Chrome" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid conversation ID" } } } } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error retrieving conversation" } } } } } } } } } }, "patch": { "operationId": "updateConversation", "summary": "Update a conversation", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Conversation id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string" }, "priority": { "type": "string" }, "status": { "type": "string" }, "assignee": { "type": "string", "format": "email" }, "team": { "type": "string" }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "internal_name": { "type": "string" }, "value": { "description": "Field value. For multi_select fields, an array of option ids or option names (a single id/name is treated as a one-element array). For url fields, an http or https URL (max 2000 characters; a bare domain is saved with https://). For boolean fields, JSON true or false.", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ] } } } } } } } } }, "responses": { "200": { "description": "Conversation updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "brand": { "type": "string", "example": "Support Brand" }, "brand_id": { "type": "integer", "example": 12345 }, "source": { "type": "string", "example": "Mail" }, "status": { "type": "string", "example": "Open" }, "priority": { "type": "string", "example": "High" }, "created_at": { "type": "integer", "example": 1672531200 }, "first_response_time": { "type": "integer", "nullable": true, "example": 1672534800 }, "resolution_time": { "type": "integer", "nullable": true, "example": null }, "due": { "type": "integer", "nullable": true, "example": 1672617600 }, "first_response_due": { "type": "integer", "nullable": true, "example": 1672538400 }, "requested_by_email": { "type": "string", "format": "email", "example": "customer@example.com" }, "requested_by_id": { "type": "integer", "example": 67890 }, "assigned_to_member_id": { "type": "integer", "nullable": true, "example": 123 }, "assigned_to_team_id": { "type": "integer", "nullable": true, "example": 456 }, "last_updated_at": { "type": "integer", "example": 1672535400 }, "subject": { "type": "string", "example": "Payment issue with order #12345" }, "description_html": { "type": "string", "example": "

I'm having trouble with my payment...

" }, "description_text": { "type": "string", "example": "I'm having trouble with my payment..." }, "attachments": { "type": "array", "description": "URLs of attachments sent on the opening message", "items": { "type": "string" }, "example": [ "https://cdn.example.com/receipt.pdf" ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "label": { "type": "string", "example": "billing" } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 9250 }, "value": { "description": "Field value. A multi_select field reads back as its selected option names joined with \", \" in option order; its ordered option ids are in option_ids. A boolean field reads back as true or false.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "example": "ORD-12345" }, "option_ids": { "type": "array", "nullable": true, "description": "Ordered option ids of a multi_select selection; null for every other field type", "items": { "type": "integer" }, "example": [ 7790, 7791 ] } } } }, "properties": { "type": "object", "properties": { "request_language": { "type": "string", "example": "English" }, "browser_timezone": { "type": "string", "example": "Asia/Calcutta" }, "browser": { "type": "string", "example": "Chrome" }, "device": { "type": "string", "example": "mac OS 10.15.7" }, "ip_address": { "type": "string", "example": "192.168.1.1" }, "country": { "type": "string", "example": "India" }, "region": { "type": "string", "example": "Tamil Nadu > Chennai" }, "referral_url": { "type": "string", "example": "http://localhost:9091/" }, "utm_source": { "type": "string", "example": "" }, "utm_medium": { "type": "string", "example": "" }, "utm_campaign": { "type": "string", "example": "" }, "utm_content": { "type": "string", "example": "" }, "utm_term": { "type": "string", "example": "" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid field values" } } } } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error updating conversation" } } } } } } } } } }, "delete": { "operationId": "deleteConversation", "summary": "Delete a conversation", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Conversation id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversation deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid conversation ID" } } } } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error deleting conversation" } } } } } } } } } } }, "/conversations/{id}/reply": { "post": { "operationId": "addConversationReply", "summary": "Create a conversation reply", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Conversation id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reply_text", "type" ], "properties": { "reply_text": { "type": "string" }, "type": { "type": "string", "enum": [ "INTERNAL_NOTE", "REPLY" ] } } } } } }, "responses": { "201": { "description": "Reply added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid reply data" } } } } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error adding reply to conversation" } } } } } } } } } } }, "/conversations/{id}/replies": { "get": { "operationId": "listConversationReplies", "summary": "List all conversation replies", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "id of the conversation", "schema": { "type": "integer", "example": 123 } }, { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination", "schema": { "type": "string", "example": "eyJpZCI6Njc4OTIsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9" } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of replies per page (1–50, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "example": 50 } }, { "in": "query", "name": "type", "required": false, "description": "Filter by reply type (if not provided, returns all types)", "schema": { "type": "string", "enum": [ "INTERNAL_NOTE", "REPLY" ], "example": "REPLY" } }, { "in": "query", "name": "sort_order", "required": false, "description": "Sort order by sent_at (default desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } } ], "responses": { "200": { "description": "Replies retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "67890" }, "type": { "type": "string", "enum": [ "REPLY", "INTERNAL_NOTE" ], "example": "REPLY" }, "body_html": { "type": "string", "example": "

Thank you for contacting us.

" }, "body_text": { "type": "string", "example": "Thank you for contacting us." }, "attachments": { "type": "array", "items": { "type": "string" }, "example": [] }, "author": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Sarah Johnson" }, "email": { "type": "string", "example": "sarah.johnson@company.com" }, "phone": { "type": "string", "nullable": true, "example": null }, "type": { "type": "string", "enum": [ "agent", "requestor" ], "example": "agent" } } }, "sent_at": { "type": "integer", "example": 1672534800 }, "conversation_id": { "type": "integer", "example": 789 }, "brand_id": { "type": "integer", "example": 123 }, "account_id": { "type": "integer", "example": 456 } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 50 }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJpZCI6Njc4OTIsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9" }, "next_url": { "type": "string", "nullable": true, "example": "https://api.sparrowdesk.com/conversations/123/replies?per_page=50&starting_after=eyJpZCI6Njc4OTIsImNyZWF0ZWRfYXQiOjE2NzI1MzEyMDB9" } } }, "total_count": { "type": "integer", "example": 156 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid query parameters" } } } } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error retrieving conversation replies" } } } } } } } } } } }, "/imports/conversations/{id}/replies": { "post": { "operationId": "importConversationReply", "summary": "Import a conversation reply", "description": "Backdated, no notifications/workflows/SLA. [requires \"edit all tickets\" scope]", "tags": [ "Conversation Reply Imports" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The SparrowDesk conversation id" }, { "in": "header", "name": "x-import-source", "required": false, "schema": { "type": "string" }, "description": "Optional label identifying the system the reply was imported from" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reply" ], "properties": { "reply": { "$ref": "#/components/schemas/ReplyImport" } } } } } }, "responses": { "201": { "description": "Reply imported", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "404": { "description": "Conversation not found" }, "422": { "description": "Request body failed validation" } } } }, "/imports/conversations/{id}/replies/create_many": { "post": { "operationId": "bulkImportConversationReplies", "summary": "Bulk import conversation replies", "description": "Backdated, no notifications/workflows/SLA. Returns a job id to poll. [requires \"edit all tickets\" scope]", "tags": [ "Conversation Reply Imports" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The SparrowDesk conversation id" }, { "in": "header", "name": "x-import-source", "required": false, "schema": { "type": "string" }, "description": "Optional label identifying the system the replies were imported from" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "replies" ], "properties": { "replies": { "type": "array", "minItems": 1, "description": "Historical replies to import, oldest first", "items": { "$ref": "#/components/schemas/ReplyImport" } } } } } } }, "responses": { "202": { "description": "Import job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll GET /imports/status/{jobId} for progress" } } } } } } } }, "404": { "description": "Conversation not found" }, "422": { "description": "Request body failed validation" } } } }, "/imports/status/{jobId}": { "get": { "operationId": "getReplyImportJobStatus", "summary": "Retrieve a reply import job", "tags": [ "Conversation Reply Imports" ], "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "type": "string" }, "description": "The job id returned by the bulk-import endpoint" } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "404": { "description": "Job not found" } } } }, "/imports/conversations": { "post": { "operationId": "importConversation", "summary": "Import a conversation", "description": "Backdated, no notifications/workflows/SLA. [requires \"edit all tickets\" scope]", "tags": [ "Conversation Imports" ], "parameters": [ { "in": "header", "name": "x-import-source", "required": false, "description": "Optional label identifying the system the conversation was imported from", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conversation" ], "properties": { "conversation": { "type": "object", "required": [ "subject", "requester", "created_at", "description_html" ], "properties": { "external_id": { "type": "string", "maxLength": 255, "description": "Caller-supplied id used for idempotency/deduplication." }, "subject": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "Open", "Pending", "Resolved", "Closed" ], "default": "Open" }, "priority": { "type": "string", "enum": [ "Low", "Medium", "High", "Urgent" ], "default": "Medium" }, "requester": { "type": "object", "description": "Requester identity. At least one of external_id, email, or phone must be provided (name alone is not enough).", "properties": { "external_id": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "name": { "type": "string", "description": "Optional; sets the contact's name only when the contact is created." } } }, "assignee_email": { "type": "string", "format": "email", "description": "Email of the agent the conversation was assigned to." }, "team_id": { "type": "integer", "minimum": 1 }, "brand_id": { "type": "integer", "minimum": 1, "description": "Defaults to the account's default brand when omitted." }, "tags": { "type": "array", "description": "Tags to attach; also records channel/origin (e.g. \"chat\", \"email\").", "items": { "type": "string" } }, "created_at": { "type": "integer", "description": "Unix epoch seconds. Must not be in the future. Backdates the conversation." }, "resolved_at": { "type": "integer", "description": "Unix epoch seconds. Only allowed when status is Resolved or Closed. Must be >= created_at." }, "description_html": { "type": "string", "minLength": 1, "description": "The opening message body (HTML)." }, "attachments": { "type": "array", "description": "Files fetched from these URLs and attached to the opening message.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public URL the file is fetched from and re-hosted." }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional headers sent when fetching the URL (e.g. auth)." } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "required": [ "field_id", "value" ], "properties": { "field_id": { "type": "integer", "minimum": 1, "description": "Stable id of the conversation field (from GET /conversation-fields)." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "Encoded by field type: text/textarea/email/url -> string, number -> number, date -> epoch seconds, dropdown -> option id, boolean -> true/false." } } } } } } } } } } }, "responses": { "201": { "description": "Conversation imported", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "422": { "description": "Request body failed validation" } } } }, "/imports/conversations/create_many": { "post": { "operationId": "bulkImportConversations", "summary": "Bulk import conversations", "description": "Backdated, no notifications/workflows/SLA. Returns a job id to poll. [requires \"edit all tickets\" scope]", "tags": [ "Conversation Imports" ], "parameters": [ { "in": "header", "name": "x-import-source", "required": false, "description": "Optional label identifying the system the conversations were imported from", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conversations" ], "properties": { "conversations": { "type": "array", "minItems": 1, "description": "Historical conversations to import. Each item has the same shape as the single-import `conversation` object.", "items": { "type": "object", "required": [ "subject", "requester", "created_at", "description_html" ], "properties": { "external_id": { "type": "string", "maxLength": 255, "description": "Caller-supplied id used for idempotency/deduplication." }, "subject": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "Open", "Pending", "Resolved", "Closed" ], "default": "Open" }, "priority": { "type": "string", "enum": [ "Low", "Medium", "High", "Urgent" ], "default": "Medium" }, "requester": { "type": "object", "description": "Requester identity. At least one of external_id, email, or phone must be provided (name alone is not enough).", "properties": { "external_id": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "name": { "type": "string", "description": "Optional; sets the contact's name only when the contact is created." } } }, "assignee_email": { "type": "string", "format": "email", "description": "Email of the agent the conversation was assigned to." }, "team_id": { "type": "integer", "minimum": 1 }, "brand_id": { "type": "integer", "minimum": 1, "description": "Defaults to the account's default brand when omitted." }, "tags": { "type": "array", "description": "Tags to attach; also records channel/origin (e.g. \"chat\", \"email\").", "items": { "type": "string" } }, "created_at": { "type": "integer", "description": "Unix epoch seconds. Must not be in the future. Backdates the conversation." }, "resolved_at": { "type": "integer", "description": "Unix epoch seconds. Only allowed when status is Resolved or Closed. Must be >= created_at." }, "description_html": { "type": "string", "minLength": 1, "description": "The opening message body (HTML)." }, "attachments": { "type": "array", "description": "Files fetched from these URLs and attached to the opening message.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public URL the file is fetched from and re-hosted." }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional headers sent when fetching the URL (e.g. auth)." } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "required": [ "field_id", "value" ], "properties": { "field_id": { "type": "integer", "minimum": 1, "description": "Stable id of the conversation field (from GET /conversation-fields)." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "Encoded by field type: text/textarea/email/url -> string, number -> number, date -> epoch seconds, dropdown -> option id, boolean -> true/false." } } } } } } } } } } } }, "responses": { "202": { "description": "Import job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Poll GET /imports/status/{jobId} for progress" } } } } } } } }, "422": { "description": "Request body failed validation" } } } }, "/imports/conversations/status/{jobId}": { "get": { "operationId": "getConversationImportJobStatus", "summary": "Retrieve a conversation import job", "tags": [ "Conversation Imports" ], "parameters": [ { "in": "path", "name": "jobId", "required": true, "description": "The job id returned by the bulk-import endpoint", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "404": { "description": "Job not found" } } } }, "/conversations/fields": { "get": { "operationId": "listConversationFields", "summary": "List all conversation fields", "description": "Retrieve a list of all conversation fields. For nested (hierarchical) fields the options are returned per level in `nested_fields`: each level's options link to the previous level's option via `parent_option_id` (null for level-1 options). Multi select fields return their options in `field_options` like dropdown fields.\n", "tags": [ "Conversation Fields" ], "parameters": [ { "in": "query", "name": "starting_after", "schema": { "type": "string" }, "description": "Cursor for pagination" }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Number of fields to return" }, { "in": "query", "name": "is_active", "schema": { "type": "boolean" }, "description": "Filter by active status" }, { "in": "query", "name": "is_default", "schema": { "type": "boolean" }, "description": "Filter by default fields" } ], "responses": { "200": { "description": "Conversation fields retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 102 }, "name": { "type": "string", "example": "Priority Level" }, "internal_name": { "type": "string", "example": "priority_level" }, "type": { "type": "string", "example": "dropdown" }, "description": { "type": "string", "example": "Priority level for tickets" }, "is_active": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "is_mandatory_on_close": { "type": "boolean", "example": true }, "field_options": { "type": "array", "description": "Options of a dropdown or multi_select field (empty for nested fields — see `nested_fields`)", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Low" }, "position": { "type": "integer", "example": 1 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "nested_fields": { "type": "array", "description": "Only for nested fields — one entry per level with that level's options; `parent_option_id` links an option to the previous level's option (null on level 1)", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 205 }, "name": { "type": "string", "example": "Category" }, "internal_name": { "type": "string", "example": "nested_level_102_1" }, "level": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer", "description": "Previous level's id (the nested field's id for level 1)", "example": 102 }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 11 }, "name": { "type": "string", "example": "Hardware" }, "position": { "type": "integer", "example": 1 }, "parent_option_id": { "type": "integer", "nullable": true, "example": null } } } } } } }, "created_at": { "type": "integer", "example": 1672531200 }, "updated_at": { "type": "integer", "example": 1672535400 } } } } } } } } }, "500": { "description": "Error while fetching conversation field", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while fetching conversation field" } } } } } } } } } }, "post": { "operationId": "createConversationField", "summary": "Create a conversation field", "tags": [ "Conversation Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "example": "Product Version" }, "internal_name": { "type": "string", "example": "product_version" }, "type": { "type": "string", "enum": [ "single_line_text", "multi_line_text", "dropdown", "number", "date", "email", "nested", "multi_select", "url", "boolean" ], "example": "single_line_text" }, "description": { "type": "string", "example": "Version of the product the issue relates to" }, "is_mandatory_on_close": { "type": "boolean", "example": true, "default": false }, "field_options": { "type": "array", "description": "Required for dropdown and multi_select fields; not allowed for nested or boolean fields. An option name repeated within the list is skipped (case-insensitive), keeping the first spelling.", "items": { "type": "string" }, "example": [ "v1.0", "v2.0", "v3.0" ] }, "boolean_options": { "type": "object", "description": "Required for boolean fields, not allowed for other types — the labels shown for true and false (must differ, case-insensitive)", "properties": { "true_label": { "type": "string", "example": "Approved" }, "false_label": { "type": "string", "example": "Rejected" } } }, "levels": { "type": "array", "description": "Nested fields only — level names, top-down (max 3)", "items": { "type": "string" }, "example": [ "Category", "Sub category", "Item" ] }, "choices": { "type": "array", "description": "Nested fields only — the option tree; nest deeper levels under `children` (depth must not exceed the number of levels)", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Hardware" }, "children": { "type": "array", "description": "Child choices (same shape, recursive)", "items": { "type": "object" } } } }, "example": [ { "name": "Hardware", "children": [ { "name": "Laptop", "children": [ { "name": "Battery" } ] } ] } ] } } } } } }, "responses": { "201": { "description": "Conversation field created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 103 }, "name": { "type": "string", "example": "Product Version" }, "internal_name": { "type": "string", "example": "product_version" }, "type": { "type": "string", "example": "single_line_text" }, "description": { "type": "string", "example": "Version of the product the issue relates to" }, "is_active": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "is_mandatory_on_close": { "type": "boolean", "example": false }, "field_options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "v1.0" }, "position": { "type": "integer", "example": 1 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "created_at": { "type": "integer", "example": 1672531200 }, "updated_at": { "type": "integer", "example": 1672531200 } } } } } } } }, "400": { "description": "Bad request - field_options sent for a type that has no options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "field_options can only be provided for dropdown or multi_select type fields" } } } } } } } }, "409": { "description": "Conflict - a field with the same name or internal name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Field with internal name 'priority_level' already exists" } } } } } } } }, "422": { "description": "Unprocessable entity - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "field_options are required for dropdown type fields" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error creating conversation field" } } } } } } } } } } }, "/conversations/fields/{id}": { "get": { "operationId": "retrieveConversationField", "summary": "Retrieve a conversation field", "tags": [ "Conversation Fields" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "ID of the conversation field to retrieve", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversation field retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 102 }, "name": { "type": "string", "example": "Priority Level" }, "internal_name": { "type": "string", "example": "priority_level" }, "type": { "type": "string", "example": "dropdown" }, "description": { "type": "string", "example": "Priority level for tickets" }, "is_active": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "is_mandatory_on_close": { "type": "boolean", "example": true }, "field_options": { "type": "array", "description": "Options of a dropdown or multi_select field (empty for nested fields — see `nested_fields`)", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Low" }, "position": { "type": "integer", "example": 1 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "nested_fields": { "type": "array", "description": "Only for nested fields — one entry per level with that level's options; `parent_option_id` links an option to the previous level's option (null on level 1)", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 205 }, "name": { "type": "string", "example": "Category" }, "internal_name": { "type": "string", "example": "nested_level_102_1" }, "level": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer", "description": "Previous level's id (the nested field's id for level 1)", "example": 102 }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 11 }, "name": { "type": "string", "example": "Hardware" }, "position": { "type": "integer", "example": 1 }, "parent_option_id": { "type": "integer", "nullable": true, "example": null } } } } } } }, "created_at": { "type": "integer", "example": 1672531200 }, "updated_at": { "type": "integer", "example": 1672535400 } } } } } } } }, "404": { "description": "Conversation field not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation field with id 999 not found" } } } } } } } }, "500": { "description": "Error while fetching conversation field", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while fetching conversation field" } } } } } } } } } }, "patch": { "operationId": "updateConversationField", "summary": "Update a conversation field", "tags": [ "Conversation Fields" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "ID of the conversation field to update", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "is_mandatory_on_close": { "type": "boolean" }, "field_options": { "type": "array", "description": "New options to append (dropdown and multi_select fields only). An option name repeated within the list is skipped (case-insensitive); one that already exists on the field returns 409.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Conversation field updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 102 }, "name": { "type": "string", "example": "Priority Level (Updated)" }, "internal_name": { "type": "string", "example": "priority_level" }, "type": { "type": "string", "example": "dropdown" }, "description": { "type": "string", "example": "Updated description" }, "is_active": { "type": "boolean", "example": false }, "is_default": { "type": "boolean", "example": true }, "is_mandatory_on_close": { "type": "boolean", "example": false }, "field_options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Urgent" }, "position": { "type": "integer", "example": 4 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "created_at": { "type": "integer", "example": 1672531200 }, "updated_at": { "type": "integer", "example": 1672535400 } } } } } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "field_options can only be provided for dropdown or multi_select type fields" } } } } } } } }, "404": { "description": "Conversation field not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation field with id 102 not found" } } } } } } } }, "409": { "description": "Invalid operation (e.g., duplicate field_options)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Field options already exist: Urgent, Critical" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error updating conversation field" } } } } } } } } } } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "List all contacts", "description": "Returns contacts for the authenticated account. Optional filters apply in addition to first-name search. Requires the \"view contacts\" scope.", "tags": [ "Contacts" ], "parameters": [ { "in": "query", "name": "search", "required": false, "schema": { "type": "string" }, "description": "Case-sensitive partial match on first name" }, { "in": "query", "name": "requested_by_email", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Exact match on contact email" }, { "in": "query", "name": "requested_by_phone", "required": false, "schema": { "type": "string", "example": "+14155552671" }, "description": "Exact match on contact phone (E.164)" }, { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Contacts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string", "nullable": true }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "time_zone": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "unsubscribed": { "type": "boolean" }, "blocked": { "type": "boolean" }, "avatar": { "type": "string", "nullable": true }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } } } }, "custom_fields": { "type": "object" }, "properties": { "type": "object" }, "created_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "contact_note": { "$ref": "#/components/schemas/EmbeddedNotes" } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true }, "next_url": { "type": "string", "nullable": true } } }, "total_count": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } }, "post": { "operationId": "createContact", "summary": "Create a contact", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name" ], "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "description": "Required if phone not provided", "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "Required if email not provided", "example": "+1234567890" }, "company_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 123 ] }, "custom_fields": { "type": "object", "example": { "company_size": "51-200", "job_title": "Software Engineer", "lead_source": "website" } }, "contact_note": { "type": "array", "description": "Optional notes created under the new contact. Requires an API key bound to a member. A note that fails to create is skipped; the contact is still created and only the notes that succeeded are returned.", "items": { "type": "object", "required": [ "description" ], "properties": { "title": { "type": "string", "example": "Renewal call" }, "description": { "type": "string", "example": "Discussed the annual renewal." }, "attachments": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "file_name": { "type": "string" }, "content_type": { "type": "string" } } } } } } } } } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "nullable": true, "example": "Doe" }, "full_name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "john.doe@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+1234567890" }, "language": { "type": "string", "nullable": true, "example": null }, "time_zone": { "type": "string", "nullable": true, "example": null }, "country": { "type": "string", "nullable": true, "example": null }, "region": { "type": "string", "nullable": true, "example": null }, "city": { "type": "string", "nullable": true, "example": null }, "active": { "type": "boolean", "example": true }, "unsubscribed": { "type": "boolean", "example": false }, "blocked": { "type": "boolean", "example": false }, "avatar": { "type": "string", "nullable": true, "example": null }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } } } }, "custom_fields": { "type": "object", "example": { "company_size": "51-200", "job_title": "Software Engineer", "lead_source": "website" } }, "properties": { "type": "object", "example": { "initial_avatar_color": { "backgroundColor": "linear-gradient(...)", "textColor": "linear-gradient(...)" } } }, "created_at": { "type": "integer", "example": 1672531200 }, "updated_at": { "type": "integer", "example": 1672531200 }, "contact_note": { "$ref": "#/components/schemas/EmbeddedNotes" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid request data" } } } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Company not found" } } } } } } } }, "409": { "description": "Contact already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact with this email already exists" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error creating contact" } } } } } } } } } } }, "/contacts/{id}": { "get": { "operationId": "retrieveContact", "summary": "Retrieve a contact", "tags": [ "Contacts" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Contact retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "full_name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+1234567890" }, "language": { "type": "string", "example": "en" }, "time_zone": { "type": "string", "example": "UTC" }, "country": { "type": "string", "nullable": true, "example": "US" }, "region": { "type": "string", "nullable": true, "example": "California" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "active": { "type": "boolean", "example": true }, "unsubscribed": { "type": "boolean", "example": false }, "blocked": { "type": "boolean", "example": false }, "avatar": { "type": "string", "nullable": true, "example": null }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } } } }, "custom_fields": { "type": "object", "example": { "company_size": "51-200", "job_title": "Software Engineer", "lead_source": "website" } }, "properties": { "type": "object", "example": { "utm_term": "", "utm_medium": "landing", "utm_source": "test", "utm_content": "", "utm_campaign": "summer2025" } }, "created_at": { "type": "integer", "example": 1672531200 }, "updated_at": { "type": "integer", "example": 1672531200 }, "contact_note": { "$ref": "#/components/schemas/EmbeddedNotes" } } } } } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error retrieving contact" } } } } } } } } } }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "tags": [ "Contacts" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "email": { "type": "string", "format": "email", "example": "john.smith@example.com" }, "phone": { "type": "string", "example": "+1987654321" }, "company_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 456 ] }, "blocked": { "type": "boolean", "example": false }, "custom_fields": { "type": "object", "example": { "company_size": "200+", "job_title": "Senior Software Engineer" } } } } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "full_name": { "type": "string", "example": "John Smith" }, "email": { "type": "string", "format": "email", "example": "john.smith@example.com" }, "phone": { "type": "string", "example": "+1987654321" }, "language": { "type": "string", "nullable": true, "example": "en" }, "time_zone": { "type": "string", "nullable": true, "example": "UTC" }, "country": { "type": "string", "nullable": true, "example": "US" }, "region": { "type": "string", "nullable": true, "example": "California" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "active": { "type": "boolean", "example": true }, "unsubscribed": { "type": "boolean", "example": false }, "blocked": { "type": "boolean", "example": false }, "avatar": { "type": "string", "nullable": true, "example": null }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } } } }, "custom_fields": { "type": "object", "example": { "company_size": "200+", "job_title": "Senior Software Engineer" } }, "properties": { "type": "object", "example": { "utm_term": "", "utm_medium": "landing", "utm_source": "test", "utm_content": "", "utm_campaign": "summer2025" } }, "created_at": { "type": "integer", "example": 1672531200 }, "updated_at": { "type": "integer", "example": 1672531200 } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid request data" } } } } } } } }, "404": { "description": "Contact or Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact not found" } } } } } } } }, "409": { "description": "Email already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Email already exists" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error updating contact" } } } } } } } } } }, "delete": { "operationId": "deleteContact", "summary": "Delete a contact", "tags": [ "Contacts" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "example": 12345 } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error deleting contact" } } } } } } } } } } }, "/contacts/fields": { "get": { "operationId": "listContactFields", "summary": "List all contact fields", "description": "Returns contact fields along with the IDs of their field options. Requires \"view contacts\" scope.", "tags": [ "Contact Fields" ], "parameters": [ { "in": "query", "name": "starting_after", "schema": { "type": "string" }, "description": "Cursor from previous response" }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "is_active", "schema": { "type": "boolean" } }, { "in": "query", "name": "is_default", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Contact fields retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000144 }, "name": { "type": "string", "example": "Priority Level" }, "type": { "type": "string", "example": "dropdown" }, "internal_name": { "type": "string", "example": "priority_level" }, "description": { "type": "string", "nullable": true, "example": "Customer priority tier" }, "is_active": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "field_options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 24 }, "name": { "type": "string", "example": "Low" }, "position": { "type": "integer", "example": 1 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455256 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455256 } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=" }, "next_url": { "type": "string", "nullable": true, "example": "https://api.sparrowdesk.com/contacts/fields?per_page=25&starting_after=eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQwNjowMzowOS4zMThaIiwiaWQiOjEwMDAwMDA5Nn0=" } } }, "total_count": { "type": "integer", "example": 12 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid query parameters" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while fetching contact fields" } } } } } } } } } }, "post": { "summary": "Create a contact field", "description": "Creates a new contact field. For dropdown type, `field_options` is required and each option is returned with its ID. For boolean type, `boolean_options` is required and its two labels are returned as options with `boolean_value`. Requires \"manage contacts\" scope.", "tags": [ "Contact Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "example": "Priority Level" }, "type": { "type": "string", "enum": [ "text", "singleLineText", "multiLineText", "number", "multiselect", "date", "email", "dropdown", "url", "boolean" ], "example": "dropdown" }, "internal_name": { "type": "string", "description": "Auto-generated from name if not provided (snake_case)", "example": "priority_level" }, "description": { "type": "string", "example": "Customer priority tier" }, "field_options": { "type": "array", "items": { "type": "string" }, "description": "Required for dropdown type", "example": [ "Low", "Medium", "High" ] }, "boolean_options": { "type": "object", "description": "Required for boolean type, not allowed for other types — the labels shown for true and false (must differ, case-insensitive)", "properties": { "true_label": { "type": "string", "example": "Approved" }, "false_label": { "type": "string", "example": "Rejected" } } } } } } } }, "responses": { "201": { "description": "Contact field created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000144 }, "name": { "type": "string", "example": "Priority Level" }, "type": { "type": "string", "example": "dropdown" }, "internal_name": { "type": "string", "example": "priority_level" }, "description": { "type": "string", "nullable": true, "example": "Customer priority tier" }, "is_active": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "field_options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 24 }, "name": { "type": "string", "example": "Low" }, "position": { "type": "integer", "example": 1 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455256 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455256 } } } } } } } }, "400": { "description": "Bad request - field_options provided for a non-dropdown type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "field_options can only be provided for dropdown type fields" } } } } } } } }, "409": { "description": "Conflict - name and/or internal name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Field with internal name 'priority_level' already exists" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while creating contact field" } } } } } } } } }, "operationId": "createContactField" } }, "/contacts/fields/{id}": { "get": { "summary": "Get a contact field by ID", "description": "Retrieve a single contact field along with the IDs of its field options. Requires \"view contacts\" scope.", "tags": [ "Contact Fields" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "Contact field ID" } ], "responses": { "200": { "description": "Contact field retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000144 }, "name": { "type": "string", "example": "Priority Level" }, "type": { "type": "string", "example": "dropdown" }, "internal_name": { "type": "string", "example": "priority_level" }, "description": { "type": "string", "nullable": true, "example": "Customer priority tier" }, "is_active": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "field_options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 24 }, "name": { "type": "string", "example": "Low" }, "position": { "type": "integer", "example": 1 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455256 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455256 } } } } } } } }, "404": { "description": "Contact field not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact field with id 999 not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while fetching contact field" } } } } } } } } }, "operationId": "retrieveContactField" }, "patch": { "summary": "Update a contact field", "description": "Updates an existing contact field. Default fields cannot have their name changed or be deactivated.\n`field_options` is append-only — existing options cannot be removed or renamed, only new ones added (dropdown fields only).\nRequires \"manage contacts\" scope.\n", "tags": [ "Contact Fields" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "Contact field ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Priority Tier" }, "description": { "type": "string", "example": "Updated description" }, "is_active": { "type": "boolean", "example": true }, "field_options": { "type": "array", "items": { "type": "string" }, "description": "Appends new options to dropdown fields only", "example": [ "Urgent" ] } } } } } }, "responses": { "200": { "description": "Contact field updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 100000144 }, "name": { "type": "string", "example": "Priority Tier" }, "type": { "type": "string", "example": "dropdown" }, "internal_name": { "type": "string", "example": "priority_level" }, "description": { "type": "string", "nullable": true, "example": "Updated description" }, "is_active": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "field_options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 28 }, "name": { "type": "string", "example": "Urgent" }, "position": { "type": "integer", "example": 5 }, "boolean_value": { "type": "boolean", "description": "Boolean fields only — the value this label stands for", "example": true } } } }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455256 }, "updated_at": { "type": "integer", "description": "Unix timestamp", "example": 1781455263 } } } } } } } }, "400": { "description": "Bad request (e.g. updating name of default field, field_options on non-dropdown)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Cannot update name of a default contact field" } } } } } } } }, "404": { "description": "Contact field not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact field with id 999 not found" } } } } } } } }, "409": { "description": "Conflict - name already exists, or duplicate option name", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Field with name 'Priority Level' already exists" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while updating contact field" } } } } } } } } }, "operationId": "updateContactField" } }, "/bulk/contacts": { "post": { "operationId": "bulkCreateContacts", "summary": "Bulk create contacts", "description": "Create multiple contacts in a single request", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+1234567890" }, "company_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 123 ] }, "custom_fields": { "type": "object", "example": { "company_size": "51-200", "job_title": "Software Engineer", "lead_source": "website" } } } } } } } }, "responses": { "201": { "description": "Contacts created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "bulk-123456789" }, "status": { "type": "string", "example": "processing" }, "message": { "type": "string", "example": "Bulk contact creation job initiated" } } } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Company not found" } } } } } } } }, "409": { "description": "One or more contacts already exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "One or more contacts already exist" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error creating contacts" } } } } } } } } } } }, "/bulk/status/{jobId}": { "get": { "operationId": "getBulkJobStatus", "summary": "Retrieve a bulk job", "description": "Retrieve the processing status of a bulk contact creation job", "tags": [ "Contacts" ], "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "bulk-123456789" }, "status": { "type": "string", "enum": [ "processing", "completed", "failed" ], "example": "completed" }, "total": { "type": "integer", "example": 100 }, "processed": { "type": "integer", "example": 100 }, "successful": { "type": "integer", "example": 95 }, "failed": { "type": "integer", "example": 5 }, "created_at": { "type": "integer", "example": 1672531200 }, "completed_at": { "type": "integer", "nullable": true, "example": 1672531800 } } } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Job not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error retrieving job status" } } } } } } } } } } }, "/companies": { "get": { "operationId": "listCompanies", "summary": "List all companies", "tags": [ "Companies" ], "parameters": [ { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "nullable": true } }, { "in": "query", "name": "domain", "required": false, "description": "Filter companies by exact domain, matched against any of the company's domains", "schema": { "type": "string", "nullable": true } }, { "in": "query", "name": "name", "required": false, "description": "Filter companies by exact name", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Companies retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } }, "domain": { "type": "string", "nullable": true, "description": "First entry of domains." }, "logo": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "other_details": { "type": "object", "additionalProperties": true, "nullable": true }, "total_contacts_linked": { "type": "integer", "description": "Number of active contacts linked to the company" }, "created_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "company_note": { "$ref": "#/components/schemas/EmbeddedNotes" } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true }, "next_url": { "type": "string", "nullable": true } } }, "total_count": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid query parameters" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while retrieving companies" } } } } } } } } } }, "post": { "operationId": "createCompany", "summary": "Create a company", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "domains": { "type": "array", "description": "Domains owned by the company. The first entry is the primary and is what the favicon and the domain field resolve to. A domain may belong to only one company per account.", "items": { "type": "string" }, "example": [ "example.com", "example.io" ] }, "domain": { "type": "string", "description": "Single-domain shorthand, equivalent to sending a one-item domains array. Ignored when domains is supplied." }, "address": { "type": "string" }, "notes": { "type": "string" }, "company_note": { "type": "array", "description": "Optional notes created under the new company. Requires an API key bound to a member. A note that fails to create is skipped; the company is still created and only the notes that succeeded are returned.", "items": { "type": "object", "required": [ "description" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "attachments": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } } } } } } } }, "responses": { "201": { "description": "Company created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } }, "domain": { "type": "string", "nullable": true, "description": "First entry of domains." }, "logo": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "other_details": { "type": "object", "additionalProperties": true, "nullable": true }, "total_contacts_linked": { "type": "integer", "description": "Number of active contacts linked to the company" }, "created_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "company_note": { "$ref": "#/components/schemas/EmbeddedNotes" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid request data" } } } } } } } }, "409": { "description": "A company with the same name or domain already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Company with this name already exists", "Company with this domain already exists" ], "example": "Company with this name already exists" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while creating company" } } } } } } } } } } }, "/companies/{id}": { "get": { "operationId": "retrieveCompany", "summary": "Retrieve a company", "tags": [ "Companies" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the company", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Company retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } }, "domain": { "type": "string", "nullable": true, "description": "First entry of domains." }, "logo": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "other_details": { "type": "object", "additionalProperties": true, "nullable": true }, "total_contacts_linked": { "type": "integer", "description": "Number of active contacts linked to the company" }, "created_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "company_note": { "$ref": "#/components/schemas/EmbeddedNotes" } } } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Company not found" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while retrieving company" } } } } } } } } } }, "patch": { "operationId": "updateCompany", "summary": "Update a company", "description": "Domains are additive — any supplied are appended to the company's existing domains, leaving the primary domain unchanged. This endpoint cannot remove a domain.", "tags": [ "Companies" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Unique identifier of the company", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "description": "At least one field must be provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "domains": { "type": "array", "description": "Domains owned by the company. The first entry is the primary and is what the favicon and the domain field resolve to. A domain may belong to only one company per account.", "items": { "type": "string" }, "example": [ "example.com", "example.io" ] }, "domain": { "type": "string", "description": "Single-domain shorthand, equivalent to sending a one-item domains array. Ignored when domains is supplied." }, "phone": { "type": "string" }, "address": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Company updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } }, "domain": { "type": "string", "nullable": true, "description": "First entry of domains." }, "logo": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "other_details": { "type": "object", "additionalProperties": true, "nullable": true }, "total_contacts_linked": { "type": "integer", "description": "Number of active contacts linked to the company" }, "created_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "description": "Unix timestamp (seconds)" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "At least one field must be provided" } } } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Company not found" } } } } } } } }, "409": { "description": "A company with the same name or domain already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Company with this name already exists", "Company with this domain already exists" ], "example": "Company with this name already exists" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Error while updating company" } } } } } } } } } } }, "/collections": { "get": { "operationId": "listCollections", "summary": "List all collections", "tags": [ "Collections" ], "parameters": [ { "in": "query", "name": "help_center_id", "required": true, "description": "ID of the help center", "schema": { "type": "integer", "example": 994 } }, { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination of top-level collections (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of top-level collections per page (1-100, default 30)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30, "nullable": true } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "type": "integer" }, "description": "When provided, returns only the direct child collections under this parent collection (paginated).\nWhen omitted, returns collections based on the `is_root` parameter.\n" }, { "in": "query", "name": "is_root", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Controls which collections are returned when `collection_id` is not provided.\n`true` — returns only root-level collections (flat list, no sub-collections).\n`false` (default) — returns root collections each with their direct child collections nested inside a `sub_collections` array.\n" } ], "responses": { "200": { "description": "Collections for the given help center, wrapped in the standard data envelope.\n- **With `collection_id`**: direct child collections of that parent (flat). No `sub_collections` field.\n- **`is_root=true`**: only root-level collections. No `sub_collections` field.\n- **Default (`is_root=false`)**: root collections each with their direct `sub_collections` nested inside.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1201 }, "name": { "type": "string", "nullable": true, "example": "Getting started" }, "description": { "type": "string", "nullable": true, "example": "Everything you need to get up and running." }, "icon": { "type": "string", "nullable": true, "example": "📘" }, "slug": { "type": "string", "nullable": true, "example": "getting-started" }, "level": { "type": "integer", "nullable": true, "description": "Nesting depth — 1 for root collections.", "example": 1 }, "help_center_id": { "type": "integer", "nullable": true, "example": 994 }, "brand_id": { "type": "integer", "nullable": true, "example": 1 }, "parent_collection_id": { "type": "integer", "nullable": true, "example": null }, "root_collection_id": { "type": "integer", "nullable": true, "example": null }, "parent_collection": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 1200 }, "name": { "type": "string", "nullable": true, "example": "Support" }, "slug": { "type": "string", "nullable": true, "example": "support" } } }, "root_collection": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 1200 }, "name": { "type": "string", "nullable": true, "example": "Support" }, "slug": { "type": "string", "nullable": true, "example": "support" } } }, "position": { "type": "string", "nullable": true, "description": "Fractional-index position for ordering.", "example": "a4" }, "subcollections_count": { "type": "integer", "nullable": true, "example": 2 }, "articles_count": { "type": "integer", "nullable": true, "example": 10 }, "published_articles_count": { "type": "integer", "nullable": true, "example": 8 }, "is_last_level_sub_collection": { "type": "boolean", "nullable": true, "example": false }, "created_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" }, "sub_collections": { "type": "array", "description": "Direct child collections (same shape, without their own sub_collections). Present only in the default (is_root=false) mode.", "items": { "type": "object" } } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 30 }, "next_cursor": { "type": "string", "nullable": true }, "next_url": { "type": "string", "nullable": true } } }, "total_count": { "type": "integer", "description": "Total number of top-level collections.", "example": 3 } } } } } }, "400": { "description": "Bad request (e.g. malformed starting_after cursor)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid cursor" } } } } } } } }, "403": { "description": "Forbidden – missing scope or feature", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Missing required scope or product feature is not enabled for this account." } } } } } } } }, "422": { "description": "Validation error (e.g. invalid help_center_id)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid help_center_id" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred while loading collections." } } } } } } } } } }, "post": { "operationId": "createCollection", "summary": "Create a collection", "tags": [ "Collections" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "help_center_id", "brand_id" ], "properties": { "name": { "type": "string", "example": "Getting Started" }, "description": { "type": "string", "example": "Introduction articles for new users" }, "help_center_id": { "type": "integer", "example": 994 }, "brand_id": { "type": "integer", "example": 1 }, "parent_collection_id": { "type": "integer", "description": "Optional parent collection id — create a nested collection under this parent", "example": 1200 } } } } } }, "responses": { "201": { "description": "Collection created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1201 }, "name": { "type": "string", "nullable": true, "example": "Getting started" }, "slug": { "type": "string", "nullable": true, "example": "getting-started" }, "help_center_id": { "type": "integer", "nullable": true, "example": 994 }, "brand_id": { "type": "integer", "nullable": true, "example": 1 } } } } } } } }, "400": { "description": "Business rule violation. Possible messages:\n- `Collections can only be nested up to 2 levels deep.`\n- `Parent collection not found.`\n- `The parent collection does not belong to the specified help center.`\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Collections can only be nested up to 2 levels deep." } } } } } } } }, "403": { "description": "Forbidden – missing scope or feature", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Missing required scope or product feature is not enabled for this account." } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "name is required" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred while creating the collection." } } } } } } } } } } }, "/collections/{id}": { "get": { "operationId": "retrieveCollection", "summary": "Retrieve a collection", "description": "Returns the collection details along with its direct sub-collections and articles.", "tags": [ "Collections" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Collection id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The collection's details, with its direct sub_collections and articles inline.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Collection metadata plus nested sub_collections and articles.", "properties": { "id": { "type": "integer", "example": 1201 }, "name": { "type": "string", "nullable": true, "example": "Getting started" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "help_center_id": { "type": "integer", "nullable": true, "example": 994 }, "brand_id": { "type": "integer", "nullable": true, "example": 1 }, "parent_collection_id": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" }, "sub_collections": { "type": "array", "description": "Direct child collections (same shape as list items).", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1202 }, "name": { "type": "string", "nullable": true, "example": "Billing" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "level": { "type": "integer", "nullable": true, "example": 1 }, "help_center_id": { "type": "integer", "nullable": true, "example": 994 }, "brand_id": { "type": "integer", "nullable": true, "example": 1 }, "parent_collection_id": { "type": "integer", "nullable": true, "example": 1201 }, "root_collection_id": { "type": "integer", "nullable": true, "example": 1201 }, "position": { "type": "string", "nullable": true, "example": "a0" }, "subcollections_count": { "type": "integer", "nullable": true, "example": 0 }, "articles_count": { "type": "integer", "nullable": true, "example": 3 }, "published_articles_count": { "type": "integer", "nullable": true, "example": 2 }, "is_last_level_sub_collection": { "type": "boolean", "nullable": true, "example": true }, "created_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" }, "updated_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)" } } } }, "articles": { "type": "array", "description": "Articles in this collection (lightweight summary, no body).", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1001 }, "title": { "type": "string", "nullable": true, "example": "Getting started" }, "slug": { "type": "string", "nullable": true }, "help_center_id": { "type": "integer", "nullable": true }, "brand_id": { "type": "integer", "nullable": true }, "position": { "type": "string", "nullable": true }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "created_at": { "type": "integer", "nullable": true }, "updated_at": { "type": "integer", "nullable": true } } } } } } } } } } }, "403": { "description": "Forbidden – missing scope or feature", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Missing required scope or feature is not enabled" } } } } } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Collection not found." } } } } } } } }, "422": { "description": "Validation error (e.g. invalid collection id)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid collection id" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "An error occurred while retrieving the collection" } } } } } } } } } } }, "/articles": { "get": { "operationId": "listArticles", "summary": "List all articles", "tags": [ "Articles" ], "parameters": [ { "in": "query", "name": "help_center_id", "required": true, "description": "Help center id (from GET /helpcenters)", "schema": { "type": "integer", "example": 994 } }, { "in": "query", "name": "published", "required": false, "schema": { "type": "boolean" }, "description": "Include published articles. Omit all three status flags to include every lifecycle bucket." }, { "in": "query", "name": "draft", "required": false, "schema": { "type": "boolean" }, "description": "Include draft and under-review articles." }, { "in": "query", "name": "archived", "required": false, "schema": { "type": "boolean" }, "description": "Include archived articles." }, { "in": "query", "name": "starting_after", "required": false, "description": "Cursor for pagination (only needed for subsequent pages)", "schema": { "type": "string", "nullable": true } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page (1-100, default 30)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30, "nullable": true } }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string" }, "description": "Search title and body." }, { "in": "query", "name": "collection_id", "required": false, "schema": { "type": "integer" }, "description": "Restrict to a specific collection." } ], "responses": { "200": { "description": "Article list with pagination", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1001 }, "title": { "type": "string", "nullable": true, "example": "Getting started with SparrowDesk" }, "slug": { "type": "string", "nullable": true, "example": "getting-started-with-sparrowdesk" }, "status": { "type": "string", "nullable": true, "description": "Article lifecycle status", "example": "PUBLISHED" }, "draft_html_content": { "type": "string", "nullable": true, "description": "Draft version body as HTML; null when there is no draft version.", "example": "

Work in progress…

" }, "published_html_content": { "type": "string", "nullable": true, "description": "Published version body as HTML; null when the article has never been published.", "example": "

Welcome to SparrowDesk.

" }, "is_public": { "type": "boolean", "nullable": true, "example": true }, "is_archived": { "type": "boolean", "example": false }, "help_center": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 994 }, "name": { "type": "string", "nullable": true, "example": "Support" } } }, "collection": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 1021 }, "name": { "type": "string", "nullable": true, "example": "Basics" } } }, "brand": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "nullable": true, "example": "Acme" } } }, "created_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "nullable": true, "example": "Jane Doe" }, "email": { "type": "string", "nullable": true, "example": "jane@acme.com" } } }, "last_updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 6 }, "name": { "type": "string", "nullable": true, "example": "John Roe" }, "email": { "type": "string", "nullable": true, "example": "john@acme.com" } } }, "published_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds), null when not published", "example": 1717236000 }, "created_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)", "example": 1714557600 }, "updated_at": { "type": "integer", "nullable": true, "description": "Unix timestamp (seconds)", "example": 1717236000 } } } }, "pages": { "type": "object", "properties": { "per_page": { "type": "integer", "example": 30 }, "next_cursor": { "type": "string", "nullable": true }, "next_url": { "type": "string", "nullable": true } } }, "total_count": { "type": "integer", "example": 42 } } } } } }, "400": { "description": "Bad request (e.g. malformed starting_after cursor)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid cursor" } } } } } } } }, "403": { "description": "Forbidden – missing scope or feature", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Missing required scope or feature is not enabled" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Help center not found" } } } } } } } }, "422": { "description": "Validation error (e.g. missing help_center_id, or all status flags set to false)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "Select at least one of published, draft, or archived (they cannot all be false)" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "example": "An error occurred while retrieving articles" } } } } } } } } } }, "post": { "operationId": "createArticle", "summary": "Create an article", "tags": [ "Articles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "help_center_id", "brand_id" ], "properties": { "help_center_id": { "type": "integer", "example": 994 }, "brand_id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Getting started with SparrowDesk" }, "content": { "type": "string", "description": "HTML content of the article, passed as a plain JSON string.\n\n**Supported tags:** `

`, `

`–`

`, `