{ "openapi": "3.0.3", "info": { "title": "DigiCalls SMS API", "version": "1.0.0", "description": "Current SMS API v1, templates, signed Webhooks and automation controls. Early access; each account requires approved access and setup. Account-scoped Bearer credentials. No sandbox sending endpoint is provided by this specification." }, "servers": [ { "url": "https://digicalls.com/api/v1", "description": "Live API — send/event/schedule requests can create real SMS." } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Account" }, { "name": "SMS" }, { "name": "Templates" }, { "name": "Webhooks" }, { "name": "Automations" } ], "paths": { "/account": { "get": { "operationId": "get_account", "tags": [ "Account" ], "summary": "Read your account", "description": "Required key permission: account:read. ", "x-required-scopes": [ "account:read" ], "responses": { "200": { "description": "Read your account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/senders": { "get": { "operationId": "get_sms_senders", "tags": [ "SMS" ], "summary": "List SMS senders", "description": "Required key permission: sms:read. Check sendingReady, then recipient consent and quota separately.", "x-required-scopes": [ "sms:read" ], "responses": { "200": { "description": "Check sendingReady, then recipient consent and quota separately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendersResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/messages": { "get": { "operationId": "get_sms_messages", "tags": [ "SMS" ], "summary": "List message history", "description": "Required key permission: sms:read. Newest first. limit 1–100 (default 50); use pagination.nextCursor as cursor.", "x-required-scopes": [ "sms:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination.nextCursor from the previous response." } } ], "responses": { "200": { "description": "Newest first. limit 1–100 (default 50); use pagination.nextCursor as cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_sms_messages", "tags": [ "SMS" ], "summary": "Send one SMS", "description": "Required key permission: sms:send. 202 is acceptance, not delivery. A matching retry returns 200 and duplicate:true. Requires approved sender, enabled sending, consent and allowance.", "x-required-scopes": [ "sms:send" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" }, "description": "Stable business event key. Retry an uncertain request using the same key and identical payload." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessage" } } } }, "responses": { "200": { "description": "Existing accepted operation; duplicate:true. No duplicate send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "202": { "description": "202 is acceptance, not delivery. A matching retry returns 200 and duplicate:true. Requires approved sender, enabled sending, consent and allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/messages/{id}": { "get": { "operationId": "get_sms_messages_id", "tags": [ "SMS" ], "summary": "Read a message and its status", "description": "Required key permission: sms:read. ", "x-required-scopes": [ "sms:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read a message and its status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/templates": { "get": { "operationId": "get_sms_templates", "tags": [ "Templates" ], "summary": "List published templates", "description": "Required key permission: sms:templates:read. data is an array of {id,version,name,category,language,body,variables,source}. Includes DigiCalls starters and published company templates; drafts are excluded.", "x-required-scopes": [ "sms:templates:read" ], "responses": { "200": { "description": "data is an array of {id,version,name,category,language,body,variables,source}. Includes DigiCalls starters and published company templates; drafts are excluded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/templates/preview": { "post": { "operationId": "post_sms_templates_preview", "tags": [ "Templates" ], "summary": "Preview template text", "description": "Required key permission: sms:templates:read. No message is queued or sent.", "x-required-scopes": [ "sms:templates:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "responses": { "200": { "description": "No message is queued or sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "operationId": "get_webhooks", "tags": [ "Webhooks" ], "summary": "List endpoints", "description": "Required key permission: webhooks:read. Returns data (endpoints), available and eventTypes. Signing secrets are never returned by a read.", "x-required-scopes": [ "webhooks:read" ], "responses": { "200": { "description": "Returns data (endpoints), available and eventTypes. Signing secrets are never returned by a read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_webhooks", "tags": [ "Webhooks" ], "summary": "Create a paused endpoint", "description": "Required key permission: webhooks:write. Returns data (including id, revision, enabled) and secret shown once. Store secret on your receiver.", "x-required-scopes": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "Returns data (including id, revision, enabled) and secret shown once. Store secret on your receiver.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "put": { "operationId": "put_webhooks_id", "tags": [ "Webhooks" ], "summary": "Update endpoint", "description": "Required key permission: webhooks:write. URL or events changes pause delivery, clear verification and cancel old pending work.", "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "URL or events changes pause delivery, clear verification and cancel old pending work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "post_webhooks_id_test", "tags": [ "Webhooks" ], "summary": "Send a synthetic test", "description": "Required key permission: webhooks:write. Returns id (delivery UUID) and status. Sends webhook.test, never an SMS. Check deliveries for an actual successful 2xx before enabling.", "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } }, "responses": { "202": { "description": "Returns id (delivery UUID) and status. Sends webhook.test, never an SMS. Check deliveries for an actual successful 2xx before enabling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/enabled": { "post": { "operationId": "post_webhooks_id_enabled", "tags": [ "Webhooks" ], "summary": "Enable or pause", "description": "Required key permission: webhooks:write. Enable only after a successful test of the current configuration. Does not enable SMS sending.", "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Toggle" } } } }, "responses": { "200": { "description": "Enable only after a successful test of the current configuration. Does not enable SMS sending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "post_webhooks_id_rotate_secret", "tags": [ "Webhooks" ], "summary": "Rotate the signing secret", "description": "Required key permission: webhooks:write. Returns data and one-time secret. Pauses delivery and requires another test.", "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } }, "responses": { "200": { "description": "Returns data and one-time secret. Pauses delivery and requires another test.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/remove": { "post": { "operationId": "post_webhooks_id_remove", "tags": [ "Webhooks" ], "summary": "Remove endpoint", "description": "Required key permission: webhooks:write. Cancels pending delivery; retained history remains.", "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } }, "responses": { "200": { "description": "Cancels pending delivery; retained history remains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "get_webhooks_id_deliveries", "tags": [ "Webhooks" ], "summary": "Inspect delivery attempts", "description": "Required key permission: webhooks:read. data contains id,eventId,type,status,attempts,httpStatus,error,canRetry,nextAttemptAt,createdAt. Up to 50 items; pass nextCursor as before.", "x-required-scopes": [ "webhooks:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "nextCursor returned by the previous page." } ], "responses": { "200": { "description": "data contains id,eventId,type,status,attempts,httpStatus,error,canRetry,nextAttemptAt,createdAt. Up to 50 items; pass nextCursor as before.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/deliveries/{deliveryId}/retry": { "post": { "operationId": "post_webhooks_id_deliveries_deliveryId_retry", "tags": [ "Webhooks" ], "summary": "Retry an eligible delivery", "description": "Required key permission: webhooks:write. Does not reset the eight-attempt or 24-hour limits.", "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } }, "responses": { "202": { "description": "Does not reset the eight-attempt or 24-hour limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/rules": { "get": { "operationId": "get_sms_automations_rules", "tags": [ "Automations" ], "summary": "List automation rules", "description": "Required key permission: automations:read. ", "x-required-scopes": [ "automations:read" ], "responses": { "200": { "description": "List automation rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_sms_automations_rules", "tags": [ "Automations" ], "summary": "Create a paused rule", "description": "Required key permission: automations:write. Returns data with rule id, revision and enabled:false. Enable separately after checking sender readiness.", "x-required-scopes": [ "automations:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleCreate" } } } }, "responses": { "201": { "description": "Returns data with rule id, revision and enabled:false. Enable separately after checking sender readiness.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/rules/{id}": { "put": { "operationId": "put_sms_automations_rules_id", "tags": [ "Automations" ], "summary": "Update a rule", "description": "Required key permission: automations:write. Pauses the rule and cancels work that has not been claimed for dispatch.", "x-required-scopes": [ "automations:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleUpdate" } } } }, "responses": { "200": { "description": "Pauses the rule and cancels work that has not been claimed for dispatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/rules/{id}/enabled": { "post": { "operationId": "post_sms_automations_rules_id_enabled", "tags": [ "Automations" ], "summary": "Enable or pause a rule", "description": "Required key permission: automations:write. ", "x-required-scopes": [ "automations:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Toggle" } } } }, "responses": { "200": { "description": "Enable or pause a rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/rules/{id}/remove": { "post": { "operationId": "post_sms_automations_rules_id_remove", "tags": [ "Automations" ], "summary": "Remove a rule", "description": "Required key permission: automations:write. ", "x-required-scopes": [ "automations:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } }, "responses": { "200": { "description": "Remove a rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/preview": { "post": { "operationId": "post_sms_automations_preview", "tags": [ "Automations" ], "summary": "Preview text and timing", "description": "Required key permissions: automations:read, sms:templates:read. Supply rule or template plus values. Returns body,encoding,segments,scheduledFor,previewOnly:true. No run is created.", "x-required-scopes": [ "automations:read", "sms:templates:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationPreview" } } } }, "responses": { "200": { "description": "Supply rule or template plus values. Returns body,encoding,segments,scheduledFor,previewOnly:true. No run is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/events": { "post": { "operationId": "post_sms_automations_events", "tags": [ "Automations" ], "summary": "Submit one business event", "description": "Required key permissions: automations:write, sms:send. Returns id,duplicate,runs and optional notice. Matching retries return 200. Read every run: blocked/skipped runs or no matching rules do not send SMS.", "x-required-scopes": [ "automations:write", "sms:send" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" }, "description": "Stable business event key. Retry an uncertain request using the same key and identical payload." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessEvent" } } } }, "responses": { "200": { "description": "Existing accepted operation; duplicate:true. No duplicate send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "202": { "description": "Returns id,duplicate,runs and optional notice. Matching retries return 200. Read every run: blocked/skipped runs or no matching rules do not send SMS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/schedules": { "post": { "operationId": "post_sms_automations_schedules", "tags": [ "Automations" ], "summary": "Schedule one template SMS", "description": "Required key permissions: automations:write, sms:send. Returns data (run) and duplicate. Matching retry returns 200. No quota reservation or guaranteed delivery time.", "x-required-scopes": [ "automations:write", "sms:send" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[!-~]{8,128}$" }, "description": "Stable business event key. Retry an uncertain request using the same key and identical payload." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "responses": { "200": { "description": "Existing accepted operation; duplicate:true. No duplicate send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "202": { "description": "Returns data (run) and duplicate. Matching retry returns 200. No quota reservation or guaranteed delivery time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/runs": { "get": { "operationId": "get_sms_automations_runs", "tags": [ "Automations" ], "summary": "List automation runs", "description": "Required key permission: automations:read. Newest 50 runs. Pass nextCursor as before; public responses omit recipient and rendered text.", "x-required-scopes": [ "automations:read" ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "nextCursor returned by the previous page." } ], "responses": { "200": { "description": "Newest 50 runs. Pass nextCursor as before; public responses omit recipient and rendered text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/runs/{id}": { "get": { "operationId": "get_sms_automations_runs_id", "tags": [ "Automations" ], "summary": "Read a run", "description": "Required key permission: automations:read. Returns data with status,scheduledFor,expiresAt,error,canCancel,template,messageId and messageStatus. Fetch content via SMS API with sms:read.", "x-required-scopes": [ "automations:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns data with status,scheduledFor,expiresAt,error,canCancel,template,messageId and messageStatus. Fetch content via SMS API with sms:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sms/automations/runs/{id}/cancel": { "post": { "operationId": "post_sms_automations_runs_id_cancel", "tags": [ "Automations" ], "summary": "Cancel before dispatch claim", "description": "Required key permission: automations:write. 409 if already claimed/submitted, delivery unknown or otherwise no longer cancelable.", "x-required-scopes": [ "automations:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "responses": { "200": { "description": "409 if already claimed/submitted, delivery unknown or otherwise no longer cancelable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonResult" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID." } } }, "default": { "description": "Request rejected. See error, optional code and requestId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Server-side DigiCalls API key with explicit permissions. Not a browser session token." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable explanation." }, "code": { "type": "string", "description": "Category, when supplied." }, "requestId": { "type": "string", "description": "Support correlation ID." } }, "required": [ "error", "requestId" ], "additionalProperties": true }, "JsonResult": { "type": "object", "description": "Operation-specific result; see the integration guide. All public responses include requestId.", "additionalProperties": true }, "AccountResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Public Customer ID." }, "object": { "type": "string", "enum": [ "account" ] }, "businessName": { "type": "string" } }, "required": [ "id", "object", "businessName" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": false }, "TemplateReference": { "type": "object", "properties": { "id": { "type": "string", "description": "Published template ID from GET /sms/templates." }, "version": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": [ "id", "version" ], "additionalProperties": false }, "TemplateInput": { "type": "object", "properties": { "id": { "type": "string", "description": "Published template ID from GET /sms/templates." }, "version": { "type": "integer", "minimum": 1, "maximum": 100000 }, "values": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Named strings matching the published template variables." } }, "required": [ "id", "version", "values" ], "additionalProperties": false }, "SendMessage": { "oneOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "to": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "body": { "type": "string", "minLength": 1, "maxLength": 1600 } }, "required": [ "from", "to", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "to": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "template": { "$ref": "#/components/schemas/TemplateInput" } }, "required": [ "from", "to", "template" ], "additionalProperties": false } ] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": [ "sms_message" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "to": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "body": { "type": "string" }, "status": { "type": "string", "description": "Examples: accepted, submitting, queued, sending, sent, delivered, undelivered, failed, canceled, received, delivery_unknown." }, "segments": { "type": "integer", "nullable": true }, "encoding": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time", "nullable": true }, "nextAction": { "type": "string" } }, "required": [ "id", "object", "direction", "from", "to", "body", "status" ], "additionalProperties": true }, "MessageResult": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": false }, "SendResult": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" }, "duplicate": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "data", "duplicate", "requestId" ], "additionalProperties": false }, "MessagesResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "data", "pagination", "requestId" ], "additionalProperties": false }, "SendersResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "sms_sender" ] }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "label": { "type": "string", "nullable": true }, "sendingReady": { "type": "boolean", "description": "Does not check consent for a particular recipient or reserve quota." } }, "required": [ "object", "phoneNumber", "label", "sendingReady" ], "additionalProperties": false } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": false }, "PreviewResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "body": { "type": "string" }, "encoding": { "type": "string" }, "segments": { "type": "integer" }, "template": { "type": "object", "additionalProperties": true } }, "required": [ "body", "encoding", "segments" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": false }, "WebhookCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS on port 443. No redirects, embedded credentials, fragments or local/private targets." }, "events": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "sms.message.received", "sms.message.status_updated" ] } } }, "required": [ "name", "url", "events" ], "additionalProperties": false }, "WebhookUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS on port 443. No redirects, embedded credentials, fragments or local/private targets." }, "events": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "sms.message.received", "sms.message.status_updated" ] } }, "expectedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "name", "url", "events", "expectedRevision" ], "additionalProperties": false }, "Revision": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "expectedRevision" ], "additionalProperties": false }, "Toggle": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "enabled", "expectedRevision" ], "additionalProperties": false }, "RuleCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "eventName": { "type": "string", "pattern": "^[a-z][a-z0-9_.]{2,79}$" }, "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "template": { "$ref": "#/components/schemas/TemplateReference" }, "timing": { "type": "string", "enum": [ "immediate", "after_event", "relative_to_time" ] }, "offsetMinutes": { "type": "integer", "minimum": -43200, "maximum": 43200, "default": 0, "description": "immediate: 0; after_event: 0–43200; relative_to_time: -43200–43200." }, "maxLatenessMinutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60 } }, "required": [ "name", "eventName", "from", "template", "timing" ], "additionalProperties": false }, "RuleUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "eventName": { "type": "string", "pattern": "^[a-z][a-z0-9_.]{2,79}$" }, "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "template": { "$ref": "#/components/schemas/TemplateReference" }, "timing": { "type": "string", "enum": [ "immediate", "after_event", "relative_to_time" ] }, "offsetMinutes": { "type": "integer", "minimum": -43200, "maximum": 43200, "default": 0, "description": "immediate: 0; after_event: 0–43200; relative_to_time: -43200–43200." }, "maxLatenessMinutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60 }, "expectedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "name", "eventName", "from", "template", "timing", "expectedRevision" ], "additionalProperties": false }, "AutomationPreview": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/RuleCreate" }, "template": { "$ref": "#/components/schemas/TemplateReference" }, "values": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Named strings matching the published template variables." }, "eventTime": { "type": "string", "format": "date-time" }, "sendAt": { "type": "string", "format": "date-time" } }, "required": [ "values" ], "additionalProperties": false, "anyOf": [ { "required": [ "rule" ] }, { "required": [ "template" ] } ] }, "BusinessEvent": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_.]{2,79}$" }, "to": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "eventTime": { "type": "string", "format": "date-time", "description": "Required by relative_to_time rules; must include Z or a UTC offset." }, "values": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Named strings matching the published template variables." } }, "required": [ "name", "to", "values" ], "additionalProperties": false }, "Schedule": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "to": { "type": "string", "pattern": "^\\+[1-9][0-9]{1,14}$", "description": "International E.164 format. Example numbers are not provisioned senders." }, "template": { "$ref": "#/components/schemas/TemplateInput" }, "sendAt": { "type": "string", "format": "date-time", "description": "1 minute–90 days in the future. Must include Z or a UTC offset." }, "maxLatenessMinutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60 } }, "required": [ "from", "to", "template", "sendAt" ], "additionalProperties": false }, "Empty": { "type": "object", "properties": {}, "additionalProperties": false }, "SmsEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "sms.message.received", "sms.message.status_updated" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accountId": { "type": "string", "description": "Your public Customer ID." }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": [ "sms_message" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "status": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "resource": { "type": "string", "description": "Relative GET /api/v1/sms/messages/{id} path. Use your fixed DigiCalls origin." } }, "required": [ "id", "object", "direction", "status", "updatedAt", "resource" ], "additionalProperties": false } }, "required": [ "id", "object", "type", "createdAt", "accountId", "data" ], "additionalProperties": false } } } }