{ "x-generator": "NSwag v14.7.1.0 (NJsonSchema v11.6.1.0 (Newtonsoft.Json v13.0.0.0))", "openapi": "3.0.0", "info": { "title": "Sent API - v3", "description": "The Sent API enables programmatic SMS and WhatsApp messaging with contact management,\ntemplate-based messaging, compliance (10DLC brand/campaign registration), and webhook delivery tracking.\n\n## Authentication\nAll requests require the `x-api-key` header with your API key\n(e.g. `sk_live_...` for production, `sk_test_...` for sandbox).\nYour account is identified automatically from the key.\n\n## Profile Scoping\nOrganization API keys can act on behalf of a child profile by passing the optional\n`x-profile-id` header with the profile's UUID. When present, all operations are scoped to\nthat profile — contacts, messages, templates, and other resources are read and written as\nif the profile's own API key were used.\n\n- Only **organization** API keys may use this header. Profile API keys will receive `403`.\n- The profile must belong to the calling organization, otherwise `404` is returned.\n- When profile-scoped, the `X-Profile-Id` response header echoes the profile UUID.\n- Rate limits remain on the organization's pool regardless of profile scoping.\n\n## Idempotency\nPOST, PUT, and PATCH requests accept an optional `Idempotency-Key` header.\nWhen provided, the API guarantees at-most-once execution: duplicate requests with the same key\nreturn the original response. Keys are scoped per customer and expire after 24 hours.\n\n## Sandbox Mode\nAll mutation endpoints (POST, PUT, DELETE) accept an optional `sandbox` field in the request body.\nWhen set to `true`, the API validates the request and returns a realistic fake response **without\nexecuting any side effects** — no database writes, no messages sent, no external API calls.\n\nSandbox mode is useful for:\n- **Integration testing** — verify your request payloads and response parsing without affecting real data\n- **CI/CD pipelines** — run end-to-end tests against the live API without consuming resources\n- **Client development** — build and test your integration before going live\n\n```json\n{\n \"sandbox\": true,\n \"phone_number\": \"+1234567890\"\n}\n```\n\nSandbox mode responses include the `X-Sandbox: true` header and return the same schema as real\nresponses with sample data. Authentication and validation still run normally — only the\nservice-layer execution is skipped.\n\n## Rate Limiting\nAPI requests are rate-limited per customer. Standard endpoints allow **10,000 requests/minute**;\nsensitive endpoints (e.g. secret rotation) allow **10 requests/minute**.\nWhen limits are exceeded, the API returns `429 Too Many Requests`.\n\nRate limit headers on `429` responses:\n| Header | Description |\n|--------|-------------|\n| `Retry-After` | Seconds until you can retry |\n| `X-RateLimit-Limit` | Maximum requests allowed in the window |\n| `X-RateLimit-Remaining` | Requests remaining (always `0` on 429) |\n| `X-RateLimit-Reset` | Unix timestamp when the window resets |\n\n## Common Response Headers\nAll responses include these headers:\n| Header | Description |\n|--------|-------------|\n| `X-Request-Id` | Unique request identifier for support and debugging |\n| `X-Response-Time` | Server processing time (e.g. `12ms`) |\n| `X-API-Version` | API version (always `v3`) |\n| `X-Profile-Id` | Echoed profile UUID when the request is profile-scoped via `x-profile-id` |\n\nIdempotent replay responses also include:\n| Header | Description |\n|--------|-------------|\n| `Idempotent-Replayed` | `true` if this is a cached replay |\n| `X-Original-Request-Id` | Request ID of the original request |\n\n## Errors\nAll errors follow a consistent JSON envelope:\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"RESOURCE_001\",\n \"message\": \"Contact not found\",\n \"doc_url\": \"https://docs.sent.dm/errors/RESOURCE_001\"\n },\n \"meta\": { \"request_id\": \"req_...\", \"timestamp\": \"...\", \"version\": \"v3\" }\n}\n```\n\n### Error Code Reference\n| Code | Description |\n|------|-------------|\n| **Authentication** | |\n| `AUTH_001` | User is not authenticated |\n| `AUTH_002` | Invalid or expired API key |\n| `AUTH_004` | Insufficient permissions for this operation |\n| **Validation** | |\n| `VALIDATION_001` | Request validation failed |\n| `VALIDATION_002` | Invalid phone number format |\n| `VALIDATION_003` | Invalid GUID format |\n| `VALIDATION_004` | Required field is missing |\n| `VALIDATION_005` | Field value out of valid range |\n| `VALIDATION_006` | Invalid enum value |\n| `VALIDATION_007` | Invalid Idempotency-Key format |\n| **Resource** | |\n| `RESOURCE_001` | Contact not found |\n| `RESOURCE_002` | Template not found |\n| `RESOURCE_003` | Message not found |\n| `RESOURCE_004` | Customer not found |\n| `RESOURCE_005` | Organization not found |\n| `RESOURCE_006` | User not found |\n| `RESOURCE_007` | Resource already exists (duplicate) |\n| `RESOURCE_008` | Webhook not found |\n| `RESOURCE_013` | Resource not found |\n| **Business Logic** | |\n| `BUSINESS_002` | Rate limit exceeded |\n| `BUSINESS_003` | Insufficient account balance |\n| `BUSINESS_004` | Contact has opted out of messaging |\n| `BUSINESS_005` | Template not approved for sending |\n| `BUSINESS_006` | Message cannot be modified in current state |\n| `BUSINESS_007` | Channel not available for this contact |\n| `BUSINESS_008` | Operation would exceed quota |\n| `BUSINESS_011` | Calls and messages to the destination country are not allowed |\n| **Voice** | |\n| `VALIDATION_011` | Voice identity is invalid |\n| `RESOURCE_015` | Call not found |\n| `RESOURCE_017` | Participant not found |\n| `BUSINESS_022` | Phone number is not owned by this account |\n| `BUSINESS_023` | Phone calls are not enabled for this account |\n| `BUSINESS_024` | Phone number is not voice-enabled for this account |\n| `BUSINESS_025` | The participant could not be added to the call |\n| `BUSINESS_026` | Call recording is not available |\n| `BUSINESS_027` | The number could not be set up to receive calls; try again shortly |\n| `BUSINESS_028` | No phone number is available for the requested area; try another area code |\n| `CONFLICT_007` | The default line for app calls cannot be turned off while other voice numbers are active |\n| `CONFLICT_008` | Call is no longer active |\n| `CONFLICT_009` | Call is not in a conference |\n| `CONFLICT_011` | Call has no phone leg |\n| **Conflict** | |\n| `CONFLICT_001` | Concurrent idempotent request in progress |\n| `CONFLICT_005` | Idempotency-Key already used for a different request |\n| `CONFLICT_006` | Template is in review — its definition, category and language are frozen |\n| **Service** | |\n| `SERVICE_001` | Cache service temporarily unavailable |\n| **Internal** | |\n| `INTERNAL_001` | Unexpected internal server error |\n| `INTERNAL_002` | Database operation failed |\n| `INTERNAL_003` | External service error (SMS/WhatsApp provider) |\n| `INTERNAL_004` | Timeout waiting for operation |\n| `INTERNAL_005` | Service temporarily unavailable |", "termsOfService": "https://sent.dm/terms", "contact": { "name": "Sent API Support", "url": "https://docs.sent.dm", "email": "support@sent.dm" }, "license": { "name": "Proprietary", "url": "https://sent.dm/terms" }, "version": "v3" }, "servers": [ { "url": "https://api.sent.dm" } ], "paths": { "/v3/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Creates a new webhook endpoint for the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksCreateWebhookEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CreateWebhookV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsCreateWebhookV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Webhook created successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookV3Response" }, "example": { "success": true, "data": { "id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8", "customer_id": "00000000-0000-0000-0000-000000000000", "display_name": "Order Notifications", "endpoint_url": "https://example.com/webhooks/orders", "signing_secret": "whsec_a1b2c3d4e5f6g7h8i9j0", "is_active": true, "event_types": [ "contact", "message", "templates" ], "event_filters": { "message": [ "delivered", "failed" ] }, "retry_count": 3, "timeout_seconds": 30, "last_delivery_attempt_at": null, "last_successful_delivery_at": null, "consecutive_failures": 0, "created_at": "2026-01-15T10:30:00+00:00", "updated_at": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.3913014+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Endpoint URL must be a valid HTTP or HTTPS URL", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.3915726+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while creating the webhook", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.3915733+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Webhooks" ], "summary": "Get webhooks list", "description": "Retrieves a paginated list of webhooks for the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksGetWebhooksEndpoint", "parameters": [ { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 20 }, { "name": "search", "in": "query", "schema": { "type": "string", "nullable": true }, "example": null }, { "name": "is_active", "in": "query", "schema": { "type": "boolean", "nullable": true }, "example": true }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhooks retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhooksListV3Response" }, "example": { "success": true, "data": { "webhooks": [ { "id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8", "customer_id": "00000000-0000-0000-0000-000000000000", "display_name": "Order Notifications", "endpoint_url": "https://example.com/webhooks/orders", "signing_secret": null, "is_active": true, "event_types": [ "contact", "message", "templates" ], "event_filters": null, "retry_count": 3, "timeout_seconds": 30, "last_delivery_attempt_at": null, "last_successful_delivery_at": null, "consecutive_failures": 0, "created_at": "2026-01-15T10:30:00+00:00", "updated_at": null } ], "pagination": { "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1, "has_more": false, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4579543+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Page size must be between 1 and 100", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4579562+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving webhooks", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4579566+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Deletes a webhook for the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksDeleteWebhookEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Webhook deleted successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid webhook ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid webhook ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4023853+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_008", "message": "Webhook not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4023867+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while deleting the webhook", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4023871+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook", "description": "Retrieves a single webhook by ID for the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksGetWebhookEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookV3Response" }, "example": { "success": true, "data": { "id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8", "customer_id": "00000000-0000-0000-0000-000000000000", "display_name": "Order Notifications", "endpoint_url": "https://example.com/webhooks/orders", "signing_secret": null, "is_active": true, "event_types": [ "contact", "message", "templates" ], "event_filters": null, "retry_count": 3, "timeout_seconds": 30, "last_delivery_attempt_at": null, "last_successful_delivery_at": null, "consecutive_failures": 0, "created_at": "2026-01-15T10:30:00+00:00", "updated_at": "2026-01-20T14:15:00+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4522047+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid webhook ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid webhook ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4522095+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_008", "message": "Webhook not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4522098+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving the webhook", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4522103+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Updates an existing webhook for the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksUpdateWebhookEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "UpdateWebhookV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsUpdateWebhookV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Webhook updated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookV3Response" }, "example": { "success": true, "data": { "id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8", "customer_id": "00000000-0000-0000-0000-000000000000", "display_name": "Updated Order Notifications", "endpoint_url": "https://example.com/webhooks/orders-v2", "signing_secret": null, "is_active": true, "event_types": [ "contact", "message", "templates" ], "event_filters": { "message": [ "delivered", "failed" ] }, "retry_count": 5, "timeout_seconds": 60, "last_delivery_attempt_at": null, "last_successful_delivery_at": null, "consecutive_failures": 0, "created_at": "2026-01-15T10:30:00+00:00", "updated_at": "2026-02-05T16:45:00+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4640498+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Endpoint URL must be a valid HTTP or HTTPS URL", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4640514+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_008", "message": "Webhook not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4640801+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while updating the webhook", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4640806+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/webhooks/{id}/events": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook events", "description": "Retrieves a paginated list of delivery events for the specified webhook. If the webhook is cloned onto your sender profiles, the list includes what those clones received; read payload.account_id to tell whose event it is.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksGetWebhookEventsEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 20 }, { "name": "search", "in": "query", "schema": { "type": "string", "nullable": true }, "example": null }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook events retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookEventsListV3Response" }, "example": { "success": true, "data": { "events": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "event_type": "message.delivered", "event_data": { "valueKind": "Undefined" }, "delivery_status": "delivered", "http_status_code": 200, "response_body": null, "delivery_attempts": 1, "error_message": null, "created_at": "2026-01-20T14:30:00+00:00", "processing_started_at": "2026-01-20T14:30:01+00:00", "processing_completed_at": "2026-01-20T14:30:02+00:00" } ], "pagination": { "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1, "has_more": false, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4549316+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid webhook ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4549337+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_008", "message": "Webhook not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.454934+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving webhook events", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4549345+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/webhooks/event-types": { "get": { "tags": [ "Webhooks" ], "summary": "Get available webhook event types", "description": "Retrieves all available webhook event types that can be subscribed to.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksGetWebhookEventTypesEndpoint", "parameters": [ { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event types retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookEventTypesListV3Response" }, "example": { "success": true, "data": { "event_types": [ { "name": "message", "display_name": "Messages", "description": "Webhook events for message status changes", "is_active": true, "event_type": null, "sub_types": [ { "name": "message.delivered", "display_name": "Message Delivered", "description": "Triggered when a message is confirmed delivered", "is_active": true, "event_type": "message", "sub_types": null }, { "name": "message.failed", "display_name": "Message Failed", "description": "Triggered when a message delivery fails", "is_active": true, "event_type": "message", "sub_types": null } ] }, { "name": "templates", "display_name": "Templates", "description": "Webhook events for template status changes", "is_active": true, "event_type": null, "sub_types": [ { "name": "templates.approved", "display_name": "Template Approved", "description": "Triggered when a template is approved and can be sent", "is_active": true, "event_type": "templates", "sub_types": null }, { "name": "templates.rejected", "display_name": "Template Rejected", "description": "Triggered when a template is rejected", "is_active": true, "event_type": "templates", "sub_types": null } ] }, { "name": "contact", "display_name": "Contacts", "description": "Signals raised by a contact — opting out, opting back in, asking for help, or sending one of your own auto-reply keywords", "is_active": true, "event_type": null, "sub_types": [ { "name": "contact.opt_in", "display_name": "Contact Opted In", "description": "Triggered when a contact opts back in to receiving messages, for example by texting START", "is_active": true, "event_type": "contact", "sub_types": null }, { "name": "contact.opt_out", "display_name": "Contact Opted Out", "description": "Triggered when a contact opts out of receiving messages, for example by texting STOP", "is_active": true, "event_type": "contact", "sub_types": null }, { "name": "contact.help", "display_name": "Contact Requested Help", "description": "Triggered when a contact asks for help, for example by texting HELP. Carries no consent change", "is_active": true, "event_type": "contact", "sub_types": null }, { "name": "contact.custom_keyword", "display_name": "Contact Custom Keyword", "description": "Triggered when a contact sends one of your own auto-reply keywords, for example BOOKING. Read template_id to see which of your templates matched. Carries no consent change", "is_active": true, "event_type": "contact", "sub_types": null } ] } ], "pagination": { "page": 1, "page_size": 3, "total_count": 3, "total_pages": 1, "has_more": false, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4566783+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving event types", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4566805+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate webhook signing secret", "description": "Generates a new signing secret for the specified webhook. The old secret is immediately invalidated.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksRotateWebhookSecretEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "RotateWebhookSecretV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsRotateWebhookSecretV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Secret rotated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfRotateSecretV3Response" }, "example": { "success": true, "data": { "signing_secret": "whsec_n3wS3cr3tK3yG3n3r4t3d" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4594998+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid webhook ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid webhook ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4595018+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_008", "message": "Webhook not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4595022+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while rotating the webhook secret", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4595027+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test a webhook", "description": "Sends a test event to the specified webhook endpoint to verify connectivity.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksTestWebhookEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "TestWebhookV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsTestWebhookV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Test completed", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTestWebhookV3Response" }, "example": { "success": true, "data": { "success": true, "message": "Test event delivered successfully" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4609082+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Event type is required", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4609097+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_008", "message": "Webhook not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4609101+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while testing the webhook", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4609106+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/webhooks/{id}/toggle-status": { "patch": { "tags": [ "Webhooks" ], "summary": "Toggle webhook status", "description": "Activates or deactivates a webhook for the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3WebhooksToggleWebhookStatusEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "ToggleWebhookStatusV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsToggleWebhookStatusV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Webhook status updated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookV3Response" }, "example": { "success": true, "data": { "id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8", "customer_id": "00000000-0000-0000-0000-000000000000", "display_name": "Order Notifications", "endpoint_url": "https://example.com/webhooks/orders", "signing_secret": null, "is_active": false, "event_types": [ "contact", "message", "templates" ], "event_filters": null, "retry_count": 3, "timeout_seconds": 30, "last_delivery_attempt_at": null, "last_successful_delivery_at": null, "consecutive_failures": 0, "created_at": "2026-01-15T10:30:00+00:00", "updated_at": "2026-02-01T09:00:00+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4623501+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid webhook ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid webhook ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4623518+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_008", "message": "Webhook not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4623521+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while toggling the webhook status", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4623574+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/users/{userId}": { "get": { "tags": [ "Users" ], "summary": "Get user by ID", "description": "Retrieves detailed information about a specific user in an organization or profile. Requires developer role or higher.", "operationId": "SentDmServicesEndpointsCustomerAPIv3UsersGetUserEndpoint", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "User ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "880e8400-e29b-41d4-a716-446655440003" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "User retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfUserResponse" }, "example": { "success": true, "data": { "id": "880e8400-e29b-41d4-a716-446655440003", "customer_id": "00000000-0000-0000-0000-000000000000", "email": "admin@acme.com", "name": "John Admin", "role": "admin", "status": "active", "invited_at": "2026-04-06T14:45:18.4680511+00:00", "last_login_at": "2026-10-06T12:45:18.4681009+00:00", "created_at": "2026-04-06T14:45:18.4681115+00:00", "updated_at": "2026-10-05T14:45:18.4681198+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.468129+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have access to this organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "AUTH_004", "message": "You do not have access to this organization or profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/authentication" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4681311+00:00", "version": "v3" } } } } }, "404": { "description": "User not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_006", "message": "User not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4681316+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4681321+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Remove user", "description": "Removes a user's access to an organization or profile. Requires admin role. You cannot remove yourself or remove the last admin.", "operationId": "SentDmServicesEndpointsCustomerAPIv3UsersRemoveUserEndpoint", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "User ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "aa0e8400-e29b-41d4-a716-446655440005" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "RemoveUserRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersRequestsRemoveUserRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "User removed successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid request - Cannot remove yourself or last admin", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "You cannot remove yourself from the organization", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.474684+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have admin access to this organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "AUTH_004", "message": "You do not have admin access to this organization or profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/authentication" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4746852+00:00", "version": "v3" } } } } }, "404": { "description": "User not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_006", "message": "User not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4746855+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.474686+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "patch": { "tags": [ "Users" ], "summary": "Update user role", "description": "Updates a user's role in the organization or profile. Requires admin role. You cannot change your own role or demote the last admin.", "operationId": "SentDmServicesEndpointsCustomerAPIv3UsersUpdateUserEndpoint", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "User ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "aa0e8400-e29b-41d4-a716-446655440005" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "UpdateUserRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersRequestsUpdateUserRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "User role updated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfUserResponse" }, "example": { "success": true, "data": { "id": "aa0e8400-e29b-41d4-a716-446655440005", "customer_id": "00000000-0000-0000-0000-000000000000", "email": "user@example.com", "name": "User Name", "role": "billing", "status": "active", "invited_at": "2026-09-06T14:45:18.476262+00:00", "last_login_at": "2026-10-06T09:45:18.4762629+00:00", "created_at": "2026-09-06T14:45:18.476263+00:00", "updated_at": "2026-10-06T14:45:18.4762631+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4762634+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters or cannot modify own role", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "role": [ "Role must be one of: admin, billing, developer" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.476267+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have admin access to this organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "AUTH_004", "message": "You do not have admin access to this organization or profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/authentication" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4762674+00:00", "version": "v3" } } } } }, "404": { "description": "User not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_006", "message": "User not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4762677+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4762687+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/users": { "get": { "tags": [ "Users" ], "summary": "List users", "description": "Retrieves all users who have access to the organization or profile identified by the API key, including their roles and status. Shows invited users (pending acceptance) and active users. Requires developer role or higher.", "operationId": "SentDmServicesEndpointsCustomerAPIv3UsersGetUsersEndpoint", "parameters": [ { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Users retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfUsersListResponse" }, "example": { "success": true, "data": { "users": [ { "id": "880e8400-e29b-41d4-a716-446655440003", "customer_id": "00000000-0000-0000-0000-000000000000", "email": "admin@acme.com", "name": "John Admin", "role": "admin", "status": "active", "invited_at": "2026-04-06T14:45:18.469778+00:00", "last_login_at": "2026-10-06T12:45:18.4697787+00:00", "created_at": "2026-04-06T14:45:18.4697788+00:00", "updated_at": "2026-10-05T14:45:18.4697789+00:00" }, { "id": "990e8400-e29b-41d4-a716-446655440004", "customer_id": "00000000-0000-0000-0000-000000000000", "email": "developer@acme.com", "name": "Jane Developer", "role": "developer", "status": "invited", "invited_at": "2026-10-04T14:45:18.4697793+00:00", "last_login_at": null, "created_at": "2026-10-04T14:45:18.4697794+00:00", "updated_at": "2026-10-04T14:45:18.4697794+00:00" } ], "pagination": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4698051+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have access to this organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "AUTH_004", "message": "You do not have access to this organization or profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/authentication" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4698073+00:00", "version": "v3" } } } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_005", "message": "Organization not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4698079+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4698083+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Invite a user", "description": "Sends an invitation to a user to join the organization or profile with a specific role. Requires admin role. The user will receive an invitation email with a token to accept. Invitation tokens expire after 7 days.", "operationId": "SentDmServicesEndpointsCustomerAPIv3UsersInviteUserEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "InviteUserRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersRequestsInviteUserRequest" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "User invited successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfUserResponse" }, "example": { "success": true, "data": { "id": "aa0e8400-e29b-41d4-a716-446655440005", "customer_id": "00000000-0000-0000-0000-000000000000", "email": "newuser@example.com", "name": "New User", "role": "developer", "status": "invited", "invited_at": "2026-10-06T14:45:18.4732056+00:00", "last_login_at": null, "created_at": "2026-10-06T14:45:18.4732059+00:00", "updated_at": "2026-10-06T14:45:18.473206+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4732062+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "email": [ "Email must be a valid email address" ], "role": [ "Role must be one of: admin, billing, developer" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4732387+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have admin access to this organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "AUTH_004", "message": "You do not have admin access to this organization or profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/authentication" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4732393+00:00", "version": "v3" } } } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_005", "message": "Organization not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4732397+00:00", "version": "v3" } } } } }, "409": { "description": "User already exists in organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_007", "message": "User already exists in this organization", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4732447+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4732451+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/templates": { "post": { "tags": [ "Templates" ], "summary": "Create a new template", "description": "Creates a new message template with header, body, footer, and buttons. The template can be submitted for review immediately or saved as draft for later submission. There is no `name` field on create — the display name is derived from the template's content and can be changed afterwards with `PUT /v3/templates/{id}`.", "operationId": "SentDmServicesEndpointsCustomerAPIv3TemplatesCreateTemplateEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CreateTemplateRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsCreateTemplateRequest" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Template created successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTemplateResponse" }, "example": { "success": true, "data": { "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Welcome Message", "category": "MARKETING", "auto_reply_action": null, "language": "en_US", "status": "DRAFT", "channels": [ "sms", "whatsapp", "rcs" ], "variables": [ "name", "company" ], "created_at": "2026-10-06T14:45:18.4851516+00:00", "updated_at": "2026-10-06T14:45:18.4851592+00:00", "is_published": false }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4851769+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_004", "message": "A required field is missing", "details": { "definition": [ "Template definition is required" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4851808+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to create template", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4851814+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Templates" ], "summary": "Get templates list", "description": "Retrieves a paginated list of message templates for the authenticated customer. Supports filtering by status, category, and search term.", "operationId": "SentDmServicesEndpointsCustomerAPIv3TemplatesGetTemplatesEndpoint", "parameters": [ { "name": "page", "in": "query", "required": true, "description": "Page number (1-indexed)", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "description": "Number of items per page", "schema": { "type": "integer", "format": "int32" }, "example": 20 }, { "name": "search", "in": "query", "description": "Optional search term for filtering templates", "schema": { "type": "string", "nullable": true }, "example": "welcome" }, { "name": "status", "in": "query", "description": "Optional status filter: APPROVED, PENDING, REJECTED", "schema": { "type": "string", "nullable": true }, "example": "APPROVED" }, { "name": "category", "in": "query", "description": "Optional category filter: MARKETING, UTILITY, AUTHENTICATION", "schema": { "type": "string", "nullable": true }, "example": null }, { "name": "is_welcome_playground", "in": "query", "description": "Accepted and ignored. It used to filter on the welcome-playground marker inside a template's LOB\ndetails; that filter is gone and nothing reads this value, so sending it neither narrows nor\nwidens the result. Retained only so a client still passing is_welcome_playground keeps\nbinding instead of the request shape changing under it.", "schema": { "type": "boolean", "nullable": true }, "example": null }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Templates retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTemplatesListResponse" }, "example": { "success": true, "data": { "templates": [ { "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Welcome Message", "category": "MARKETING", "auto_reply_action": null, "language": "en_US", "status": "APPROVED", "channels": [ "sms", "whatsapp", "rcs" ], "variables": [ "name", "company" ], "created_at": "2026-09-06T14:45:18.4903135+00:00", "updated_at": "2026-09-21T14:45:18.490314+00:00", "is_published": true } ], "pagination": { "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1, "has_more": false, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4903315+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "page_size": [ "Page size must be between 1 and 100" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4903353+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4903357+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/templates/{id}": { "delete": { "tags": [ "Templates" ], "summary": "Delete a template", "description": "Deletes a template by ID. Optionally, you can also delete the template from WhatsApp/Meta by setting delete_from_meta=true.", "operationId": "SentDmServicesEndpointsCustomerAPIv3TemplatesDeleteTemplateEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "7ba7b820-9dad-11d1-80b4-00c04fd430c8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "DeleteTemplateRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsDeleteTemplateRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "Template deleted successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid template ID format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_003", "message": "Invalid identifier format", "details": { "id": [ "Invalid template ID format." ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4867003+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_002", "message": "Template not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4867054+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to delete template", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4867058+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Templates" ], "summary": "Get template by ID", "description": "Retrieves a specific template by its ID. Returns template details including name, category, language, status, and definition.", "operationId": "SentDmServicesEndpointsCustomerAPIv3TemplatesGetTemplateEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "7ba7b820-9dad-11d1-80b4-00c04fd430c8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTemplateResponse" }, "example": { "success": true, "data": { "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Welcome Message", "category": "MARKETING", "auto_reply_action": null, "language": "en_US", "status": "APPROVED", "channels": [ "sms", "whatsapp", "rcs" ], "variables": [ "name", "company" ], "created_at": "2026-09-06T14:45:18.4888775+00:00", "updated_at": "2026-09-21T14:45:18.4888783+00:00", "is_published": true }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4888787+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid template ID format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_003", "message": "Invalid identifier format", "details": { "id": [ "Invalid template ID format." ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4888823+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_002", "message": "Template not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4888828+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4888832+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "put": { "tags": [ "Templates" ], "summary": "Update a template", "description": "Updates an existing template's name, category, language, definition, or submits it for review. While the template is in review (status PENDING, or any channel awaiting a verdict) its definition, category and language are frozen and a resubmission is refused — those requests answer 409 CONFLICT_006. The display name stays editable throughout.\n\n`definition`, `category` and `language` are editable only from status DRAFT, REJECTED or APPROVED. An edit to any of them on a template in another state (PAUSED, DISABLED or REVOKED) is refused with 400 VALIDATION_001 and the detail \"Template (except display name) cannot be updated unless it is in draft or rejected status\"; `name` stays editable in every state. `submit_for_review` on a PAUSED, DISABLED or REVOKED template is accepted and answers 200, but opens no review and does not move the status — only the reviewer can reinstate it.\n\nEditing an APPROVED template is a live edit: the new content is stored immediately, and sending `submit_for_review: true` re-opens review, which returns the affected channels to PENDING so they stop sending until they are approved again. The previously approved content is never sent during re-review. Watch the per-channel `templates` webhook events rather than assuming the template-level status.\n\nTemplates provisioned by Sent (light-onboarding templates, whose names carry the reserved `sent_` prefix) are read-only: every field is refused with 400 VALIDATION_001 and the detail \"This template is read-only. Only 'submit for review' is allowed.\", and only `submit_for_review` is accepted. A `name` starting with `sent_` is refused for the same reason — the prefix is reserved.", "operationId": "SentDmServicesEndpointsCustomerAPIv3TemplatesUpdateTemplateEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "7ba7b820-9dad-11d1-80b4-00c04fd430c8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "UpdateTemplateRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsUpdateTemplateRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Template updated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTemplateResponse" }, "example": { "success": true, "data": { "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Updated Welcome Message", "category": "MARKETING", "auto_reply_action": null, "language": "en_US", "status": "DRAFT", "channels": [ "sms", "whatsapp", "rcs" ], "variables": [ "name", "company" ], "created_at": "2026-09-06T14:45:18.4918744+00:00", "updated_at": "2026-10-06T14:45:18.491875+00:00", "is_published": false }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4918753+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "category": [ "Category must be one of: MARKETING, UTILITY, AUTHENTICATION" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.491879+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_002", "message": "Template not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4918795+00:00", "version": "v3" } } } } }, "409": { "description": "Template is in review — definition, category, language and resubmission are frozen", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_006", "message": "This template is in review; its definition, category and language are frozen until the review completes", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4918799+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to update template", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.4918809+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/sender-profiles": { "post": { "tags": [ "Sender Profiles" ], "summary": "Create a sender profile", "description": "Creates a sender profile under your organization. A profile is a customer of yours: it sends under its own or your identity, and your customers never see Sent.\n\n## The minimum\n\n`{ \"name\": \"Example Retail\", \"short_name\": \"Example\" }`. `short_name` is the SMS sender id and is required. Inbox and opt-out list come from your organization. Its brand and campaign are your organization's only where `compliance` says `{ \"inherit\": true }` — omitted, the profile has neither. Billing defaults to the profile's own balance, with your organization covering what it cannot.\n\n**A sender is not one of them.** The brand and the campaign can be inherited; a number cannot. A profile either has a sender of its own — `channels.sms` — or it has none and terminates through the shared routes for that country.\n\n## Saying what a profile owns\n\nEvery capability is one of three things, and there is no flag per state:\n\n- **Its own** — supply the capability's fields. Data is what owning looks like.\n- **The organization's** — `{ \"inherit\": true }`, with nothing else.\n- **None** — omit the block.\n\nThere is no `\"inherit\": false` that also carries no data. A second way to say the same thing would let a request contradict itself.\n\nInheriting needs no id. A customer has exactly one brand, so `brand` resolves without one.\n\n**The campaign has no block of its own.** It is only ever a registration, and every field of one is something a specific market demands — so it lives in `compliance`, alongside the rest of what that market asks for, and it says whose it is there too: `\"compliance\": { \"campaign\": { \"inherit\": true } }` runs the profile on your organization's campaign and brand, and stops this call asking for any campaign field. `\"brand\": { \"inherit\": true }` alone inherits the brand only: the campaign is then the profile's own. Inheriting takes *all* of your organization's, because inheritance resolves an owner rather than a single row.\n\nA profile with a `brand` of its own **cannot** inherit the campaign, and asking is refused with `400`: a campaign is filed against a brand registration, and your organization's campaign is filed against your organization's brand rather than this profile's. Inherit both, own both, or inherit the brand and own the campaign.\n\n`channels.sms` is the market the profile starts in — one `country` and `number_type`. It decides what else this call asks for: the compliance catalog is keyed on that pair, and it determines which fields `brand` accepts and what `compliance` answers for.\n\n**Several numbers in that market**: `channels.sms.numbers` lists them, one entry per area code, e.g. `[{\"area_code\": \"212\", \"quantity\": 2}, {\"quantity\": 1}]` for two in 212 and one in any area code. `quantity` defaults to 1, an entry without `area_code` means any area code, and the total is at most 10. The market is created with **one campaign**, the one in `compliance.campaign`, and a US `TEN_DLC` market's numbers are stored on it and assigned when it is approved. A profile inheriting your organization's campaign keeps one number. Every number is listed in `channels.sms[].numbers` with its area code and status.\n\nA profile is a tenant, not a market, so it can go on to send in several — but through `POST /v3/channels/sms` with the `x-profile-id` header, one market and its compliance at a time. Reads return every market as `channels.sms[]`, so the read shape is a list even where this one is not.\n\n`brand` is required when `number_type` is `TEN_DLC` — inherited or its own. A 10DLC registration has nothing to attach to without one, and no later call can supply it, so omitting it is refused with `400` rather than reported as outstanding.\n\n## Use cases and volume\n\nA TCR campaign declares one to five `use_cases`, each with its own `sample_messages` — TCR attributes samples to the use case they illustrate, so they travel together.\n\nHow that set registers is derived from `volume` and never declared. Below the low-volume threshold the campaign registers as `LOW_VOLUME` with every entry as a sub-use-case; above it, one entry registers as that use case outright and several register as `MIXED` with sub-use-cases. `MIXED` and `LOW_VOLUME` are therefore refused as `use_case` values: they describe the shape of a set, which is ours to work out.\n\n**Leaving `volume` out is accepted and costs more.** An absent value registers the campaign at the standard tier, which carries the higher fee — so say so when a campaign is low volume. Sole proprietor brands are the exception: their fee is fixed by entity type, and volume only decides the use case.\n\n## Compliance\n\n`brand` is captured identically in every country. Everything a specific market demands on top of it — including every field of the campaign — goes in `compliance`, as key/value entries whose keys depend on the sender's country and type. US `TEN_DLC` registers with The Campaign Registry and asks for a substantial set; an alphanumeric sender may pre-register with documents, or need nothing at all.\n\nYou do not have to know any of it. Omit `compliance` and the response lists exactly what is outstanding, with types and accepted values — or call `GET /v3/compliance/requirements` first. Anything Sent supplies on your behalf is never asked for, and is rejected if sent.\n\nRequirements can be conditional, and the condition is published as `required_when` so you can render a form from it rather than discover the rule by being rejected. Every US `TEN_DLC` campaign field carries `compliance.inherit != true` — send `\"inherit\": true` and none of them is asked for or accepted, because the profile is running on your organization's campaign.\n\n## Uploading documents\n\nSend `application/json` for everything except a market that pre-registers a sender with supporting documents. For those, send `multipart/form-data` instead: put this entire document — unchanged — in a single field named `profile`, and attach each file under a field named after the compliance key it satisfies. Individual form fields per property are not read; the payload is always the one `profile` field.\n\nA pre-registration market has no `brand` and no `campaign` — those are asked for only where a regime registers one — so its `compliance` carries nothing at all, and the documents are the request:\n\n```bash\ncurl -X POST https://api.sent.dm/v3/sender-profiles \\\n -H 'x-api-key: YOUR_SECRET_TOKEN' \\\n -F 'profile={\n \"name\": \"Example Retail\",\n \"short_name\": \"EXAMPLE\",\n \"channels\": {\n \"sms\": {\n \"country\": \"XK\",\n \"number_type\": \"ALPHANUMERIC\",\n \"sender_value\": \"EXAMPLE\"\n }\n }\n }' \\\n -F 'business_registration=@registration.pdf' \\\n -F 'letter_of_authorization=@loa.pdf'\n```\n\n`business_registration` and `letter_of_authorization` are illustrative. The real field names are whatever that market configures, so read them from `GET /v3/compliance/requirements`, which lists documents separately from the values — under `attachments`, each with the `field_name` to put the file under.\n\nA document has no JSON form, so naming one in `compliance` is refused with `400` rather than ignored: accepting it would report the requirement as satisfied while no file was ever stored.\n\n## WhatsApp and RCS\n\nNeither can be inherited, so neither takes an `inherit`: the profile's WhatsApp account and RCS agent are its own or it has none. Sharing your organization's would share its inbox and its throughput, which makes the two indistinguishable to a recipient.\n\n`channels.whatsapp` names one of the accounts shared into your organization, and takes the two identifiers nothing else can supply: `waba_id`, because your organization holds one account per client, and `phone_number_id`, because naming the account's number is what assigns it to the profile as the number it sends from.\n\nEverything else is resolved from your organization — the Multi-Partner Solution the account arrived through, the client business portfolio that owns it, the access token and that token's expiry. None of them is accepted here: the first two are Meta's answer about provenance, so a value you sent could assert a partnership Meta disagrees with, and the token is minted per client business and rotates roughly every sixty days.\n\n`phone_number_id` is optional. Omit it to connect the account now and settle the number later — the channel reads as `ACTION_NEEDED` with `reason_code` `CHANNEL_007`, and the profile's WhatsApp messages fail until a number is named. They do not fall back to your organization's account. `POST /v3/channels/whatsapp` connects an account to an existing profile and resolves the same fields the same way.\n\nAn account of its own needs a sender of its own, so `channels.whatsapp` requires `channels.sms`. A profile sending SMS on your organization's sender shares that inbox and opt-out list, and is not a separate tenant to give an account to — asking is refused with `400`, before your organization is asked to resolve anything.\n\n`channels.rcs` records the RCS agent. RCS (Rich Communication Services) is the next-generation SMS standard built into Android — it lets you send branded messages with images, buttons and read receipts over the carrier network, with no app install required. Learn more in the [Google RCS documentation](https://developers.google.com/business-communications/rcs-business-messaging).\n\nAll fields on the agent form are required except `opt_in_screenshot_url`. The full form must be submitted in one go so the carrier review has everything it needs. A carrier approval no API call can trigger is arranged offline, so the status reports `PROVISIONING` until it is.\n\n## Responses\n\n`201` when the profile is complete on return — the fully-inherited case, where nothing needs registering. `202` when something is still provisioning, with per-capability status and outstanding requirements. `409` when the WhatsApp account supplied is already recorded. `400` covers a wrong value as well as a missing one: a missing brand under `TEN_DLC`, a brand or campaign inherited under `TEN_DLC` that your organization does not have yet, an unknown compliance key, a bad type, a sender id the market does not allow, a `waba_id` that is not one of the accounts shared into your organization, or a WhatsApp account Meta rejects. `502` when Meta could not be reached to verify the WhatsApp account; nothing was created, so retry.", "operationId": "SentDmServicesEndpointsCustomerAPIv3SenderProfilesCreateSenderProfileEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" } ], "requestBody": { "x-name": "CreateSenderProfileRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsCreateSenderProfileRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsCreateSenderProfileRequest" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Profile created and complete — nothing needed registering", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfileResponse" }, "example": { "success": true, "data": { "id": "990e8400-e29b-41d4-a716-446655440004", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Demo Brand", "short_name": "DEMO", "description": null, "api_key": "sntdm_live_yyyyyyyyyyyy", "billing": { "inherit": true }, "notifications": "ORGANIZATION", "channels": { "sms": [], "whatsapp": null, "rcs": null, "mms": [], "voice": [] }, "created_at": "2025-06-01T12:00:00+00:00" }, "meta": { "request_id": "req_8Y0aLq3kEx", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "202": { "description": "Profile accepted; capabilities are provisioning", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfileResponse" }, "example": { "success": true, "data": { "id": "770e8400-e29b-41d4-a716-446655440002", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example Retail", "short_name": "Example", "description": null, "api_key": "sntdm_live_xxxxxxxxxxxx", "billing": { "inherit": false }, "notifications": "ORGANIZATION", "channels": { "sms": [ { "country": "US", "number_type": "TEN_DLC", "sender_value": null, "numbers": [], "status": "PENDING_REVIEW", "reason_code": "CHANNEL_009", "reason": "Registration is awaiting submission to or review by a regulator or carrier." } ], "whatsapp": null, "rcs": null, "mms": [], "voice": [] }, "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "business_name": "Example Retail", "tax_id": "12-3456789", "tax_id_type": "us_ein", "ein_issuing_country": "US", "entity_type": "PRIVATE_PROFIT", "street": "123 Main Street", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US", "website": "https://example.com", "contact_name": "John Smith", "contact_email": "john@example.com", "contact_phone": "+12125550123" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who have bought from Example Retail, plus occasional offers.", "message_flow": "Customers opt in at checkout on https://example.com by ticking a box that is unchecked by default, and again in the account settings page. Consent is not a condition of purchase.", "use_cases": [ { "use_case": "DELIVERY_NOTIFICATION", "sample_messages": [ "Example Retail: order 10432 is out for delivery and arrives today. Track it at https://example.com/t/10432. Reply STOP to opt out.", "Example Retail: order 10432 was delivered. Reply STOP to opt out." ] }, { "use_case": "MARKETING", "sample_messages": [ "Example Retail: 20% off everything this weekend with code SAVE20 at https://example.com/sale. Reply STOP to opt out." ] } ], "opt_in_message": "Example Retail: you are subscribed to order updates and offers. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to cancel.", "opt_out_message": "Example Retail: you are unsubscribed and will receive no further messages. Reply START to resubscribe.", "help_message": "Example Retail: email support@example.com or call +1 212 555 0123. Msg & data rates may apply. Reply STOP to unsubscribe.", "opt_in_keywords": "START,YES", "opt_out_keywords": "STOP,END,CANCEL,UNSUBSCRIBE,QUIT", "help_keywords": "HELP,INFO", "privacy_policy_link": "https://example.com/privacy", "terms_and_conditions_link": "https://example.com/terms", "volume": "1500" }, "documents": [] }, "created_at": "2025-06-01T12:00:00+00:00" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "One or more compliance values were rejected", "details": { "compliance.phone": [ "'phone' must be a valid e164." ], "compliance.mock": [ "'mock' is set by Sent and cannot be supplied." ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "A profile API key cannot create profiles", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "409": { "description": "The WhatsApp account supplied is already recorded", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_007", "message": "This WhatsApp account is already recorded", "details": { "channels.whatsapp": [ "Meta registers a number to exactly one business account, so this one cannot be added twice. Supply an account no other profile or organization is using." ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "422": { "description": "The number type or market asked for cannot be used, or a required compliance document is missing or was rejected", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "502": { "description": "Meta could not be reached to verify the WhatsApp account; nothing was created", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Sender Profiles" ], "summary": "List sender profiles", "description": "Lists the sender profiles under your organization, newest first, paginated with `page` and `page_size`.\n\nEach entry is the same document `GET /v3/sender-profiles/{id}` returns, with one difference: **`compliance.documents` at the profile root is absent**. Working out which documents a market holds means a catalog lookup and a document read per market, and doing that for every profile on a page would turn one request into dozens to answer a question you did not ask. Read a single profile for that. Brand and campaign are still included when they exist.\n\n`compliance.documents` being **absent** is not the same as it being an **empty list**. Absent means the documents were not fetched here; an empty list means the profile holds none.\n\n`api_key` is never returned. It is shown once, by create.", "operationId": "SentDmServicesEndpointsCustomerAPIv3SenderProfilesGetSenderProfilesEndpoint", "parameters": [ { "name": "page", "in": "query", "required": true, "description": "Page number, 1-indexed.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "description": "Profiles per page. Between 1 and 100.", "schema": { "type": "integer", "format": "int32" }, "example": 20 } ], "responses": { "200": { "description": "A page of sender profiles", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfilesListResponse" }, "example": { "success": true, "data": { "sender_profiles": [ { "id": "770e8400-e29b-41d4-a716-446655440002", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example Retail", "short_name": "EXAMPLE", "description": null, "billing": { "inherit": false }, "notifications": "ORGANIZATION", "channels": { "sms": [ { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550100", "numbers": [], "status": "ACTIVE" } ], "whatsapp": null, "rcs": null, "mms": [], "voice": [] }, "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout." } }, "created_at": "2025-01-15T00:00:00+00:00" }, { "id": "880e8400-e29b-41d4-a716-446655440003", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Demo Brand", "short_name": "DEMO", "description": null, "billing": { "inherit": true }, "notifications": "ORGANIZATION_AND_SENDER_PROFILE", "channels": { "sms": [ { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550101", "numbers": [], "status": "ACTIVE" } ], "whatsapp": null, "rcs": null, "mms": [], "voice": [] }, "created_at": "2025-03-10T00:00:00+00:00" } ], "pagination": { "page": 1, "page_size": 20, "total_count": 2, "total_pages": 1, "has_more": false, "cursors": null } }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "page or page_size out of range", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "page_size must be between 1 and 100", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/sender-profiles/{id}": { "delete": { "tags": [ "Sender Profiles" ], "summary": "Delete a sender profile", "description": "Deletes one of your sender profiles and returns `204`.\n\nThe delete is **soft**: the profile stops being usable and stops appearing in reads, and its message history is kept, because deleting a profile must not delete the record of what it sent.\n\n## What it releases\n\nAnything the profile still held goes with it. A **phone number** returns to our inventory and can be given to whoever asks next — it does not stay reserved for you, and getting the same number back afterwards is not something we can promise. A **WhatsApp account of its own** is deregistered from Meta. Its routing rules stop being used, so nothing sends through the profile after this call.\n\nA profile that only inherits from its organization holds nothing of its own and releases nothing.", "operationId": "SentDmServicesEndpointsCustomerAPIv3SenderProfilesDeleteSenderProfileEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the profile.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted, and anything it held released", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No such profile under your organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Sender Profiles" ], "summary": "Get a sender profile", "description": "Reads one of your sender profiles.\n\nThe document mirrors `POST /v3/sender-profiles`, with three differences that follow from this being a read rather than a request.\n\n`channels.sms` is a **list**. Create takes the one market a profile starts in; a profile can go on to send in several, and this reports all of them, each with its own `status`.\n\n`compliance.brand` comes back **in full, with `inherit` saying whose it is**. On a request `{ \"inherit\": true }` carries no data because there is nothing to send; here it carries the data, because the point of a read is to say what the profile actually sends under.\n\n**There is no `campaigns` array.** Brand, campaign, and compliance documents are reported at the profile root in `compliance`. A profile running on your organization's campaign is asked for none of the campaign fields, so `compliance.campaign` carries `{ \"inherit\": true }` with no campaign data.\n\n`api_key` is **never** returned here. It is shown once, by create.\n\nA profile belonging to another organization reads as `404`, not `403`: saying which of the two it is would confirm the id exists.", "operationId": "SentDmServicesEndpointsCustomerAPIv3SenderProfilesGetSenderProfileEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the profile, as returned by POST /v3/sender-profiles.", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" } ], "responses": { "200": { "description": "The sender profile", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfileResponse" }, "example": { "success": true, "data": { "id": "770e8400-e29b-41d4-a716-446655440002", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example Retail", "short_name": "EXAMPLE", "description": null, "billing": { "inherit": false }, "notifications": "ORGANIZATION", "channels": { "sms": [ { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550100", "numbers": [], "status": "ACTIVE" } ], "whatsapp": null, "rcs": null, "mms": [], "voice": [] }, "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US", "website": "https://example.com" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout." }, "documents": [ { "key": "senderid_registration_requirements", "file_name": "sender-id-registration.pdf", "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6" } ] }, "created_at": "2025-01-15T00:00:00+00:00" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No such profile under your organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_014", "message": "Sender profile not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "patch": { "tags": [ "Sender Profiles" ], "summary": "Update a sender profile", "description": "Changes a profile's own attributes: `name`, `short_name`, `description` and `notifications` (who is emailed about the profile's events — `ORGANIZATION`, `SENDER_PROFILE`, or `ORGANIZATION_AND_SENDER_PROFILE`).\n\n**Only those.** A profile's identity, its markets and its compliance each have a sub-resource of their own, because each has its own validation and its own external consequences — a brand change may need re-registering, a market change provisions a sender. Folding them in here would give those fields two writers and no way to say which one wins.\n\nOmitting a field leaves it alone; sending `null` clears it. Those are different requests, so `{}` changes nothing and is refused rather than silently accepted — a caller who misspelt every field would otherwise get a `200` and an unchanged profile.\n\n`name` and `short_name` cannot be cleared: `short_name` is the SMS sender id, so a supplied value must be 3–11 characters of letters, numbers and spaces with at least one letter.\n\nReturns the profile as `GET /v3/sender-profiles/{id}` would, so the result of the change needs no second call to see.", "operationId": "SentDmServicesEndpointsCustomerAPIv3SenderProfilesPatchSenderProfileEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" } ], "requestBody": { "x-name": "PatchSenderProfileRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsPatchSenderProfileRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The updated sender profile", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfileResponse" }, "example": { "success": true, "data": { "id": "770e8400-e29b-41d4-a716-446655440002", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example Retail Renamed", "short_name": "EXMPL", "description": null, "billing": { "inherit": false }, "notifications": "ORGANIZATION", "channels": { "sms": [ { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550100", "numbers": [], "status": "ACTIVE" } ], "whatsapp": null, "rcs": null, "mms": [], "voice": [] }, "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US", "website": "https://example.com" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout." }, "documents": [ { "key": "senderid_registration_requirements", "file_name": "sender-id-registration.pdf", "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6" } ] }, "created_at": "2025-01-15T00:00:00+00:00" }, "meta": { "request_id": "req_9Z1bMq4kFy", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "Nothing to change, or a value that is not allowed", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Supply at least one field to change", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_9Z1bMq4kFy", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No such profile under your organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_014", "message": "Sender profile not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_9Z1bMq4kFy", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/profiles/{profileId}/complete": { "post": { "tags": [ "Profiles" ], "summary": "Complete profile setup", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nFinal step in the profile compliance workflow. Validates all prerequisites (KYC, brand, campaigns, required documents), connects the profile to the SMS and WhatsApp channels, and marks it onboarded. Prerequisites are always validated first: if any fail the call returns 400 naming every unmet one, and nothing is started. If they pass and the profile is already onboarded, the call returns 200 and does nothing. Otherwise it returns 202 and calls the provided webhook URL when background processing finishes.\n\nCallable with the organization's API key or the profile's own key. The key's user must be an admin or owner of the profile, or of the organization it belongs to.\n\nPrerequisites (all but the last are checked before the already-onboarded short-circuit,\nmatching the previous contract; the last is checked after it, so a profile that is already\nonboarded is never rejected by it):\n- Profile must have a name, short name, and description (short name max 50 characters, description max 5000)\n- webHookUrl must be supplied on the request\n- A KYC form submission is required\n- A brand is required, either on the profile or inherited from the parent organization\n- TCR applications must have at least one campaign, own or inherited\n- Destination countries marked as main must have their required compliance documents uploaded\n- TCR applications must state whether they inherit the organization's TCR brand and campaign\n\nOutcome:\n- Once the prerequisites pass and background processing succeeds, the profile's conversionFlowStatus becomes ONBOARDED and its public status reads `approved`\n- A profile with no WhatsApp channel, or one still awaiting TCR registration or country documents, is onboarded like any other. Those are answered by the brand and campaign records, not by a status on the profile\n- If background processing fails, the profile keeps the status it already had and the webhook reports the reason", "operationId": "SentDmServicesEndpointsCustomerAPIv3ProfilesCompleteProfileEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route", "schema": { "type": "string", "format": "uuid" }, "example": "660e8400-e29b-41d4-a716-446655440000" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CompleteProfileRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsCompleteProfileRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Profile is already onboarded - returns current status", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileCompletionResultResponse" }, "example": { "success": true, "data": { "status": "approved", "message": "Profile is already completed" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.7982412+00:00", "version": "v3" } } } } }, "202": { "description": "Profile completion started successfully - webhook will be called when finished", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileCompletionAcceptedResponse" }, "example": { "success": true, "data": { "message": "Profile completion in progress" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.7982596+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request - validation errors, or prerequisites not met (the response names every unmet one)", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "401": { "description": "Unauthorized - Valid API key required", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - the key's user is not an admin of the profile or of the organization it belongs to", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Internal server error occurred during validation", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/profiles": { "post": { "tags": [ "Profiles" ], "summary": "Create a new profile", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nCreates a new sender profile within an organization. Profiles represent different brands, departments, or use cases, each with their own messaging configuration and settings. Requires admin role in the organization.\n\n## WhatsApp Business Account\n\nEvery profile owns its own WhatsApp Business Account — accounts are never shared between profiles or inherited from the organization. Provide a `whatsapp_business_account` object with `waba_id`, `phone_number_id`, and `access_token`. Obtain these from Meta Business Manager by creating a System User with `whatsapp_business_messaging` and `whatsapp_business_management` permissions.\n\nOmit the field and the profile is created without WhatsApp, staying incomplete until it has an account of its own.\n\n## Brand\n\nInclude the optional `brand` field to create the brand for this profile at the same time. Cannot be used when `inherit_tcr_brand` is `true`.\n\n## Payment Details\n\nWhen `billing_model` is `\"profile\"` or `\"profile_and_organization\"` you may include a `payment_details` object containing the card number, expiry (MM/YY), CVC, and billing ZIP code. Payment details are **never stored** on our servers and are forwarded directly to the payment processor. Providing `payment_details` when `billing_model` is `\"organization\"` is not allowed.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ProfilesCreateProfileEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CreateProfileRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsCreateProfileRequest" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Profile created successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileDetailResponse" }, "example": { "success": true, "data": { "id": "770e8400-e29b-41d4-a716-446655440002", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Sales Team", "email": "team@acme.com", "icon": "https://example.com/sales-icon.png", "description": "Sales department sender profile", "short_name": "SALES", "status": "incomplete", "created_at": "2026-10-06T14:45:18.8011266+00:00", "updated_at": "2026-10-06T14:45:18.8011348+00:00", "allow_contact_sharing": false, "allow_template_sharing": false, "inherit_contacts": false, "inherit_templates": false, "inherit_tcr_brand": false, "inherit_tcr_campaign": false, "billing_model": "profile", "sending_phone_number_profile_id": null, "sending_whatsapp_number_profile_id": null, "sending_phone_number": null, "whatsapp_phone_number": null, "allow_number_change_during_onboarding": null, "waba_id": "123456789012345", "billing_contact": { "name": "Acme Corp", "email": "billing@acmecorp.com", "phone": "+12025551234", "address": "123 Main Street, New York, NY 10001, US" }, "brand": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tcr_brand_id": null, "status": null, "identity_status": null, "universal_ein": null, "csp_id": null, "submitted_to_tcr": false, "submitted_at": null, "is_inherited": false, "created_at": "2026-10-06T14:45:18.8012488+00:00", "updated_at": null, "contact": { "name": "John Smith", "business_name": "Acme Corp", "role": null, "phone": null, "email": "john@acmecorp.com", "phone_country_code": null }, "business": { "legal_name": "Acme Corporation LLC", "tax_id": null, "tax_id_type": null, "entity_type": null, "street": null, "city": null, "state": null, "postal_code": null, "country": "US", "url": null, "country_of_registration": null }, "compliance": { "vertical": "PROFESSIONAL", "brand_relationship": "SMALL_ACCOUNT", "is_tcr_application": true, "phone_number_prefix": null, "destination_countries": [ { "id": "US", "isMain": false } ], "notes": null, "primary_use_case": null } } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8014081+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters, or the organization has no WhatsApp Business Account configured and none was supplied in whatsapp_business_account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "name": [ "Profile name is required" ], "short_name": [ "short_name must be 3–11 characters, contain only letters, numbers, and spaces, and include at least one letter" ], "payment_details.expiry": [ "payment_details.expiry must be in MM/YY format (e.g. '09/27')" ], "whatsapp_business_account": [ "Organization does not have a WhatsApp Business Account configured. Complete WhatsApp Embedded Signup for your organization first, or provide direct credentials in the 'whatsapp_business_account' field." ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8014161+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have admin access to this organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_005", "message": "Organization not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8014167+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to create profile. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8014171+00:00", "version": "v3" } } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Profiles" ], "summary": "List profiles in organization", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nRetrieves all sender profiles within an organization, including brand information for each profile. Profiles represent different brands, departments, or use cases within an organization, each with their own messaging configuration.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ProfilesGetProfilesEndpoint", "parameters": [ { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Profiles retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfilesListResponse" }, "example": { "success": true, "data": { "profiles": [ { "id": "660e8400-e29b-41d4-a716-446655440001", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Marketing Team", "email": "team@acme.com", "icon": "https://example.com/marketing-icon.png", "description": "Marketing department sender profile", "short_name": "MKT", "status": "approved", "created_at": "2026-07-06T14:45:18.85359+00:00", "updated_at": "2026-10-01T14:45:18.8535914+00:00", "allow_contact_sharing": false, "allow_template_sharing": false, "inherit_contacts": false, "inherit_templates": false, "inherit_tcr_brand": false, "inherit_tcr_campaign": false, "billing_model": "profile", "sending_phone_number_profile_id": null, "sending_whatsapp_number_profile_id": null, "sending_phone_number": null, "whatsapp_phone_number": null, "allow_number_change_during_onboarding": null, "waba_id": null, "billing_contact": null, "brand": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tcr_brand_id": null, "status": null, "identity_status": null, "universal_ein": null, "csp_id": null, "submitted_to_tcr": false, "submitted_at": null, "is_inherited": false, "created_at": "2026-07-06T14:45:18.8535925+00:00", "updated_at": null, "contact": { "name": "John Smith", "business_name": "Acme Corp", "role": null, "phone": null, "email": "john@acmecorp.com", "phone_country_code": null }, "business": { "legal_name": "Acme Corporation LLC", "tax_id": null, "tax_id_type": null, "entity_type": null, "street": null, "city": null, "state": null, "postal_code": null, "country": "US", "url": null, "country_of_registration": null }, "compliance": { "vertical": "PROFESSIONAL", "brand_relationship": "SMALL_ACCOUNT", "is_tcr_application": true, "phone_number_prefix": null, "destination_countries": [], "notes": null, "primary_use_case": null } } } ], "pagination": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8536086+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have access to this organization", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_005", "message": "Organization not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8536117+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to retrieve profiles. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8536123+00:00", "version": "v3" } } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/profiles/{profileId}": { "delete": { "tags": [ "Profiles" ], "summary": "Delete a profile", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nSoft deletes a sender profile. The profile will be marked as deleted but data is retained. Anything it still held is released first: phone numbers return to our inventory and can go to whoever asks next, its own WhatsApp account is deregistered, and its routing rules stop being used. Requires admin role in the organization.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ProfilesDeleteProfileEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "DeleteProfileRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsDeleteProfileRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "Profile deleted successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have admin access to this profile", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_014", "message": "Profile not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8028407+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to delete profile. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8028422+00:00", "version": "v3" } } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Profiles" ], "summary": "Get profile by ID", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nRetrieves detailed information about a specific sender profile within an organization, including brand and KYC information if a brand has been configured.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ProfilesGetProfileEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Profile retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileDetailResponse" }, "example": { "success": true, "data": { "id": "770e8400-e29b-41d4-a716-446655440002", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Sales Team", "email": "team@acme.com", "icon": "https://example.com/sales-icon.png", "description": "Sales department sender profile", "short_name": "SALES", "status": "approved", "created_at": "2026-07-06T14:45:18.8058987+00:00", "updated_at": "2026-10-01T14:45:18.8059003+00:00", "allow_contact_sharing": false, "allow_template_sharing": false, "inherit_contacts": false, "inherit_templates": false, "inherit_tcr_brand": false, "inherit_tcr_campaign": false, "billing_model": "profile", "sending_phone_number_profile_id": null, "sending_whatsapp_number_profile_id": null, "sending_phone_number": null, "whatsapp_phone_number": null, "allow_number_change_during_onboarding": null, "waba_id": null, "billing_contact": null, "brand": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tcr_brand_id": null, "status": null, "identity_status": null, "universal_ein": null, "csp_id": null, "submitted_to_tcr": false, "submitted_at": null, "is_inherited": false, "created_at": "2026-07-06T14:45:18.805901+00:00", "updated_at": null, "contact": { "name": "John Smith", "business_name": "Acme Corp", "role": null, "phone": null, "email": "john@acmecorp.com", "phone_country_code": null }, "business": { "legal_name": "Acme Corporation LLC", "tax_id": null, "tax_id_type": null, "entity_type": null, "street": null, "city": null, "state": null, "postal_code": null, "country": "US", "url": null, "country_of_registration": null }, "compliance": { "vertical": "PROFESSIONAL", "brand_relationship": "SMALL_ACCOUNT", "is_tcr_application": true, "phone_number_prefix": null, "destination_countries": [ { "id": "US", "isMain": false } ], "notes": null, "primary_use_case": null } } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8059028+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have access to this profile", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_014", "message": "Profile not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8059045+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to retrieve profile. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8059055+00:00", "version": "v3" } } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] }, "patch": { "tags": [ "Profiles" ], "summary": "Update profile settings", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nUpdates a profile's configuration and settings. Requires admin role in the organization. Only provided fields will be updated (partial update).\n\n## Brand Management\n\nInclude the optional `brand` field to create or update the brand associated with this profile. The brand holds KYC and TCR compliance data (legal business info, contact details, messaging vertical). Once a brand has been submitted to TCR it cannot be modified. Setting `inherit_tcr_brand: true` and providing `brand` in the same request is not allowed.\n\n## Payment Details\n\nWhen `billing_model` is `\"profile\"` or `\"profile_and_organization\"` you may include a `payment_details` object containing the card number, expiry (MM/YY), CVC, and billing ZIP code. Payment details are **never stored** on our servers and are forwarded directly to the payment processor. Providing `payment_details` when `billing_model` is `\"organization\"` is not allowed.\n\n## Deprecated fields\n\n`sending_phone_number_profile_id` and `sending_whatsapp_number_profile_id` are **accepted and ignored**. Sender borrowing is gone: a profile cannot send from another profile's number, because two profiles behind one sender makes an inbound reply and a delivery receipt ambiguous about whose they are.\n\nSending either **changes nothing and still returns `200`** — they are kept on the contract so an existing integration keeps working. Reads carry both keys too and always answer `null`, which is how you can confirm the value did not take.\n\nGive the profile a sender of its own instead — `POST /v3/channels/sms` or `POST /v3/channels/whatsapp`, sent with the `x-profile-id` header naming it.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ProfilesUpdateProfileEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "UpdateProfileRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsUpdateProfileRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Profile updated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileDetailResponse" }, "example": { "success": true, "data": { "id": "770e8400-e29b-41d4-a716-446655440002", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Sales Team - Updated", "email": "team@acme.com", "icon": "https://example.com/sales-icon.png", "description": "Updated sales department sender profile", "short_name": "SALES", "status": "approved", "created_at": "2026-07-06T14:45:18.8558249+00:00", "updated_at": "2026-10-06T14:45:18.8558255+00:00", "allow_contact_sharing": false, "allow_template_sharing": false, "inherit_contacts": false, "inherit_templates": false, "inherit_tcr_brand": false, "inherit_tcr_campaign": false, "billing_model": "organization", "sending_phone_number_profile_id": null, "sending_whatsapp_number_profile_id": null, "sending_phone_number": null, "whatsapp_phone_number": null, "allow_number_change_during_onboarding": null, "waba_id": null, "billing_contact": null, "brand": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tcr_brand_id": null, "status": null, "identity_status": null, "universal_ein": null, "csp_id": null, "submitted_to_tcr": false, "submitted_at": null, "is_inherited": false, "created_at": "2026-10-06T14:45:18.8558259+00:00", "updated_at": null, "contact": { "name": "John Smith", "business_name": "Acme Corp", "role": null, "phone": null, "email": "john@acmecorp.com", "phone_country_code": null }, "business": { "legal_name": "Acme Corporation LLC", "tax_id": null, "tax_id_type": null, "entity_type": null, "street": null, "city": null, "state": null, "postal_code": null, "country": "US", "url": null, "country_of_registration": null }, "compliance": { "vertical": "PROFESSIONAL", "brand_relationship": "SMALL_ACCOUNT", "is_tcr_application": true, "phone_number_prefix": null, "destination_countries": [ { "id": "US", "isMain": false } ], "notes": null, "primary_use_case": null } } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8558272+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "brand": [ "Cannot provide brand data when inherit_tcr_brand is true." ], "payment_details.expiry": [ "payment_details.expiry must be in MM/YY format (e.g. '09/27')" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8558322+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Forbidden - User does not have admin access to this profile", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_014", "message": "Profile not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8558325+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to update profile. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8558329+00:00", "version": "v3" } } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/numbers/lookup/{phoneNumber}": { "get": { "tags": [ "Numbers" ], "summary": "Get phone number details", "description": "Retrieves detailed information about a phone number including carrier, line type, porting status, and VoIP detection. Uses the customer's messaging provider for rich data, with fallback to the internal index.", "operationId": "SentDmServicesEndpointsCustomerAPIv3NumbersGetNumberEndpoint", "parameters": [ { "name": "phoneNumber", "in": "path", "required": true, "schema": { "type": "string" }, "example": "+12025551234" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Phone number details returned successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfNumberLookupResultResponse" }, "example": { "success": true, "data": { "phone_number": "+12025551234", "is_valid": true, "carrier_name": "T-Mobile", "line_type": "mobile", "country_code": "US", "mobile_country_code": "310", "mobile_network_code": "260", "is_ported": false, "is_voip": false }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8583444+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request - Phone number is missing or invalid", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Phone number is required", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8583467+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Phone number not found in provider or internal index", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_013", "message": "Phone number not found or invalid", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8583474+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error - Contact support with request ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8583477+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/messages/{id}/cancel": { "post": { "tags": [ "Messages" ], "summary": "Cancel a scheduled message", "description": "Calls off a message you scheduled with `scheduled_at`, before it is released for sending. The message moves to `CANCELLED`, which is terminal, and it is never sent.\n\n**Only a SCHEDULED message can be cancelled.** A message that has already been released — queued, in flight, or finished — returns 409. The release sweeper runs continuously, so a cancellation sent within about a minute of the scheduled instant can lose that race and be refused; cancel with time to spare.\n\n**One message per call.** A send to many recipients, or on several channels, becomes one message per recipient × channel, each with its own id; cancel the ones you want stopped. There is no bulk cancellation.\n\n**Cancelling is free**, and nothing was charged for the hold in the first place — a scheduled message is only priced and billed at release.\n\n**A cancellation fires `message.cancelled`** on your webhook, exactly once, carrying the `scheduled_at` that was called off so a consumer can un-record the send it was expecting. Cancelling the same message again returns this same response and fires no second event. `Idempotency-Key` is honoured.\n\nA cancelled message cannot be resent — send a new one.\n\nThe response is the message itself, in the same shape `GET /v3/messages/{id}` returns, so the `status` you read back is the one now stored on the row, and `scheduled_at` is the time it would have gone out. `GET /v3/messages/{id}` keeps reporting both afterwards.\n\n`events` is the message lifecycle as it stood immediately before the cancellation: the CANCELLED entry is written asynchronously and lands a moment later, so read `status` for the outcome. If you need the entry itself, re-fetch the message after a few seconds — `GET /v3/messages/{id}` is cached briefly, so an immediate re-fetch can still show the pre-cancellation state.", "operationId": "SentDmServicesEndpointsCustomerAPIv3MessagesCancelMessageV3Endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string", "format": "uuid" }, "example": "8ba7b830-9dad-11d1-80b4-00c04fd430c8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CancelMessageV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesRequestsCancelMessageV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The message is cancelled and will not be sent", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCancelMessageV3Response" }, "example": { "success": true, "data": { "scheduled_at": "2026-10-01T07:00:00+00:00", "id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8", "customer_id": "00000000-0000-0000-0000-000000000000", "contact_id": "00000000-0000-0000-0000-000000000000", "phone": "+14155551234", "phone_international": "+1 415-555-1234", "region_code": "US", "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "template_name": "order_confirmation", "template_category": null, "channel": "sms", "message_body": null, "status": "CANCELLED", "direction": "OUTBOUND", "created_at": "2026-09-30T11:59:00+00:00", "price": null, "active_contact_price": null, "events": null, "reason_code": null, "reason": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8613045+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid message ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "id": [ "Invalid message ID format." ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8613082+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Message not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_003", "message": "Message not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8613454+00:00", "version": "v3" } } } } }, "409": { "description": "Message is not scheduled, so there is nothing to cancel (already released, in flight, or finished)", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_006", "message": "Only a scheduled message can be cancelled. This message has already been released for sending, is in flight, or has finished.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8613457+00:00", "version": "v3" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while cancelling the message.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.861347+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/messages/{id}/activities": { "get": { "tags": [ "Messages" ], "summary": "Get message activities", "description": "Retrieves the activity log for a specific message. Activities track the message lifecycle including acceptance, processing, sending, delivery, and any errors. A SCHEDULED entry carries scheduled_at, the release instant in UTC as it stood at that moment. Other entries have no scheduled_at key.", "operationId": "SentDmServicesEndpointsCustomerAPIv3MessagesGetMessageActivitiesEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "8ba7b830-9dad-11d1-80b4-00c04fd430c8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Message activities retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfMessageActivitiesResponse" }, "example": { "success": true, "data": { "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8", "activities": [ { "status": "DELIVERED", "description": "Message delivered to recipient", "from": "+15551234567", "timestamp": "2026-10-06T14:20:18.8632661+00:00", "scheduled_at": null, "reason_code": null, "reason": null, "price": "0.0450", "active_contact_price": "0.0050" }, { "status": "SENT", "description": "Message sent via SMS", "from": "+15551234567", "timestamp": "2026-10-06T14:15:18.8632909+00:00", "scheduled_at": null, "reason_code": null, "reason": null, "price": "0.0450", "active_contact_price": "0.0050" }, { "status": "PROCESSED", "description": "Message processed and queued for sending", "from": null, "timestamp": "2026-10-06T14:14:18.863291+00:00", "scheduled_at": null, "reason_code": null, "reason": null, "price": "0.0450", "active_contact_price": "0.0050" }, { "status": "QUEUED", "description": "Message accepted and queued for processing", "from": null, "timestamp": "2026-10-06T14:13:18.8632912+00:00", "scheduled_at": null, "reason_code": null, "reason": null, "price": null, "active_contact_price": null } ], "pagination": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8632987+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid message ID format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Message not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_003", "message": "Message not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8633011+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving message activities.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8633015+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/messages/{id}": { "get": { "tags": [ "Messages" ], "summary": "Get message status", "description": "Retrieves the current status and details of a message by ID. Includes delivery status, timestamps, and error information if applicable. A message that is or was held for a later time (a send you scheduled with scheduled_at, a quiet-hours hold, or a message you cancelled while it was held) is returned as a ScheduledMessageResponse: the same fields plus scheduled_at, the instant it is held for in UTC — or, on a CANCELLED message, the instant that was called off. A message sent immediately has no scheduled_at key.", "operationId": "SentDmServicesEndpointsCustomerAPIv3MessagesGetMessageEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string", "format": "uuid" }, "example": "8ba7b830-9dad-11d1-80b4-00c04fd430c8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Message retrieved successfully. data is a MessageResponse, or for a message that is or was held for a later time a ScheduledMessageResponse: the same fields plus scheduled_at", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfMessageResponse" }, "example": { "success": true, "data": { "id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8", "customer_id": "550e8400-e29b-41d4-a716-446655440000", "contact_id": "550e8400-e29b-41d4-a716-446655440002", "phone": "+14155551234", "phone_international": "+1 415-555-1234", "region_code": "US", "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "template_name": "Welcome Message", "template_category": "UTILITY", "channel": "sms", "message_body": { "header": null, "content": "Welcome to our service, John! We're excited to have you.", "footer": null, "buttons": null, "subject": null, "media": null, "headerMedia": null }, "status": "DELIVERED", "direction": "OUTBOUND", "created_at": "2026-10-06T12:45:18.8664106+00:00", "price": 0.0055, "active_contact_price": 0.015, "events": [ { "status": "QUEUED", "timestamp": "2026-10-06T12:45:18.8664663+00:00", "description": "Message queued for sending", "reason_code": null, "reason": null }, { "status": "SENT", "timestamp": "2026-10-06T12:45:23.8664929+00:00", "description": "Message sent via SMS", "reason_code": null, "reason": null }, { "status": "DELIVERED", "timestamp": "2026-10-06T12:45:28.8664951+00:00", "description": "Message delivered to recipient", "reason_code": null, "reason": null } ], "reason_code": null, "reason": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.866503+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid message ID format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid message ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8665055+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Message not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_003", "message": "Message not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.866506+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving the message.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8665064+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/messages/{id}/resend": { "post": { "tags": [ "Messages" ], "summary": "Resend a message", "description": "Resends a message you already sent, on the same message id, without rebuilding the request. The typical use is recovering a BLOCKED message — for example one refused for insufficient balance — after the account has been topped up.\n\n**A resend bills again.** Each accepted resend is a new delivery attempt and records a new charge against the same message id; a client that resends on every failure is charged on every loop.\n\n**Every policy runs again.** The resend goes back through the full send pipeline — consent, balance, KYC and channel quota, template approval, quiet hours and channel health — so it can land on BLOCKED, FILTERED or SCHEDULED again rather than being sent, exactly as a fresh send would. Status webhooks (message.sent, message.blocked, message.filtered, message.failed) fire again for the same message id, so consumers keyed on the id will see repeated transitions.\n\n**What can be resent.** A message in a terminal state — DELIVERED, FAILED, READ or BLOCKED — or one stuck at SENT for more than 15 minutes. A FILTERED message can never be resent: the recipient opted out or a routing rule refused the send. A message still in flight (QUEUED, PROCESSED, ROUTED), held for quiet hours (SCHEDULED), or SENT less than 15 minutes ago returns 409. Two concurrent resends of one id are serialised: one is accepted, the other gets 409.\n\nThe resend keeps the channel the message was originally requested on; the channel cannot be changed on a resend — send a new message instead. `Idempotency-Key` is honoured, so a retried request replays the first accepted response instead of resending twice.\n\nThe response has the same shape as `POST /v3/messages`: `recipients` has a single entry whose `message_id` is the id you resent.", "operationId": "SentDmServicesEndpointsCustomerAPIv3MessagesResendMessageV3Endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string", "format": "uuid" }, "example": "8ba7b830-9dad-11d1-80b4-00c04fd430c8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "ResendMessageV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesRequestsResendMessageV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "202": { "description": "Resend accepted; the message is QUEUED again and will be billed as a new attempt", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfResendMessageV3Response" }, "example": { "success": true, "data": { "status": "QUEUED", "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "template_name": "order_confirmation", "recipients": [ { "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8", "to": "+14155551234", "channel": "sms", "body": "Hi John Doe, your order #12345 has been confirmed." } ] }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8684331+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid message ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "id": [ "Invalid message ID format." ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8684369+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Message not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_003", "message": "Message not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8684373+00:00", "version": "v3" } } } } }, "409": { "description": "Message is not resendable in its current state (in flight, scheduled, recently sent, or filtered)", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_006", "message": "Message is not resendable in its current state: it is still in flight, held for quiet hours, or was sent less than 15 minutes ago.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8684376+00:00", "version": "v3" } } } } }, "429": { "description": "Rate limit exceeded - resends are limited per customer because each one bills", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Internal server error, or the message's stored data could not be rebuilt for a resend (the message is marked FAILED and was not resent)", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while resending the message.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8684385+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/messages": { "post": { "tags": [ "Messages" ], "summary": "Send a message", "description": "Sends a message to one or more recipients using a template. Supports multi-channel broadcast — when multiple channels are specified (e.g. [\"sms\", \"whatsapp\"]), a separate message is created for each (recipient, channel) pair. Returns immediately with per-recipient message IDs for async tracking via webhooks or the GET /messages/{id} endpoint. Sends gated before any delivery attempt do not reject the request — an account-level precondition such as insufficient balance, a template not approved for sending, or free-form content with no open conversation with the contact. The send is accepted with 202 and the affected messages are reported as BLOCKED on GET /messages/{id} and the message.blocked webhook. To send later, set scheduled_at (ISO-8601 with an explicit UTC offset; a value without one is rejected) between 1 minute and 30 days ahead: the response is a ScheduledSendMessageResponse (the same fields plus scheduled_at; status is still QUEUED), each message then moves to SCHEDULED, is held and released at that time (within a few minutes), and a message.scheduled webhook fires once it is held. Balance and template approval are evaluated at release, not at acceptance. Quiet hours are not checked when the request is accepted: if the time falls inside a legally protected quiet-hours window for a recipient, that message is moved to the next allowed time at release and a second message.scheduled webhook reports the new scheduled_at. An account may hold at most 1,000,000 scheduled messages at once (429 LIMIT_001).", "operationId": "SentDmServicesEndpointsCustomerAPIv3MessagesSendMessageV3Endpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "SendMessageV3Request", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesRequestsSendMessageV3Request" } } }, "required": true, "x-position": 1 }, "responses": { "202": { "description": "Message accepted for processing (QUEUED). data is a SendMessageResponse, or for a request that carried scheduled_at a ScheduledSendMessageResponse: the same fields plus scheduled_at. Status is QUEUED in both, and each scheduled message moves to SCHEDULED once it is held", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSendMessageResponse" }, "example": { "success": true, "data": { "status": "QUEUED", "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "template_name": "order_confirmation", "recipients": [ { "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8", "to": "+14155551234", "channel": "sms", "body": "Hi John Doe, your order #12345 has been confirmed." }, { "message_id": "8ba7b831-9dad-11d1-80b4-00c04fd430c8", "to": "+14155551234", "channel": "whatsapp", "body": "Hi John Doe, your order #12345 has been confirmed." }, { "message_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8", "to": "+14155555678", "channel": "sms", "body": "Hi John Doe, your order #12345 has been confirmed." }, { "message_id": "9ba7b841-9dad-11d1-80b4-00c04fd430c8", "to": "+14155555678", "channel": "whatsapp", "body": "Hi John Doe, your order #12345 has been confirmed." } ] }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8705847+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_004", "message": "Request validation failed", "details": { "to": [ "'to' must contain at least one recipient" ], "template": [ "'template' is required" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8705874+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_002", "message": "Template not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.870588+00:00", "version": "v3" } } } } }, "429": { "description": "Rate limit exceeded, or too many outstanding scheduled messages", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "LIMIT_001", "message": "Too many outstanding scheduled messages", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8705883+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to queue message for processing.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8705895+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "List messages for a conversation", "description": "Retrieves a paginated list of the messages in a single conversation (scoped to the authenticated customer), ordered by created date (most recent first).", "operationId": "SentDmServicesEndpointsCustomerAPIv3ConversationsGetConversationByIdEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id from the route.", "schema": { "type": "string", "format": "uuid" }, "example": "08fab313-c9e2-502c-975e-08b0356c432e" }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 20 }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Messages retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfConversationMessagesListResponse" }, "example": { "success": true, "data": { "messages": [ { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "customer_id": "41681f0a-15b4-45ab-afca-d9af35b4d3a1", "contact_id": "14b278db-6db8-448f-a5db-8d6ce46a3451", "phone": "+1234567890", "phone_international": "+1 234-567-890", "region_code": "US", "template_id": null, "template_name": null, "template_category": null, "channel": "sms", "message_body": null, "status": "DELIVERED", "direction": "OUTBOUND", "created_at": "2026-10-06T14:40:18.8719655+00:00", "price": 0.0075, "active_contact_price": 0.0, "events": null, "reason_code": null, "reason": null } ], "pagination": { "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1, "has_more": false, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8719834+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_005", "message": "Page must be greater than 0", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8719856+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.871986+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversation messages", "description": "Retrieves a paginated list of the authenticated customer's messages across all conversations, ordered by created date (most recent first).", "operationId": "SentDmServicesEndpointsCustomerAPIv3ConversationsGetConversationsEndpoint", "parameters": [ { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 20 }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Messages retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfConversationMessagesListResponse" }, "example": { "success": true, "data": { "messages": [ { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "customer_id": "41681f0a-15b4-45ab-afca-d9af35b4d3a1", "contact_id": "14b278db-6db8-448f-a5db-8d6ce46a3451", "phone": "+1234567890", "phone_international": "+1 234-567-890", "region_code": "US", "template_id": null, "template_name": null, "template_category": null, "channel": "sms", "message_body": null, "status": "DELIVERED", "direction": "OUTBOUND", "created_at": "2026-10-06T14:40:18.8737194+00:00", "price": 0.0075, "active_contact_price": 0.0, "events": null, "reason_code": null, "reason": null } ], "pagination": { "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1, "has_more": false, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8737209+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_005", "message": "Page must be greater than 0", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8737281+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8737285+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/contacts": { "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Creates a new contact by phone number and associates it with the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ContactsCreateContactEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CreateContactRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsRequestsCreateContactRequest" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Contact created successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactResponse" }, "example": { "success": true, "data": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "customer_id": "00000000-0000-0000-0000-000000000000", "phone_number": "+1234567890", "format_e164": "+1234567890", "format_international": "+1 234-567-890", "format_national": "(234) 567-890", "format_rfc": "tel:+1-234-567-890", "country_code": "1", "region_code": "US", "available_channels": "sms", "default_channel": "sms", "opt_out": false, "is_inherited": false, "created_at": "2026-10-06T14:45:18.8752273+00:00", "updated_at": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8752459+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request - phone number missing or invalid", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Phone number is required", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8752527+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "description": "Contact already exists for this customer", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_007", "message": "Contact with this phone number already exists for this customer", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8752532+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8752536+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Contacts" ], "summary": "Get contacts list", "description": "Retrieves a paginated list of contacts for the authenticated customer. Supports filtering by search term, channel, or phone number.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ContactsGetContactsEndpoint", "parameters": [ { "name": "page", "in": "query", "required": true, "description": "Page number (1-indexed)", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "description": "Number of items per page", "schema": { "type": "integer", "format": "int32" }, "example": 20 }, { "name": "search", "in": "query", "description": "Optional search term for filtering contacts", "schema": { "type": "string", "nullable": true }, "example": null }, { "name": "channel", "in": "query", "description": "Optional channel filter (sms, whatsapp)", "schema": { "type": "string", "nullable": true }, "example": null }, { "name": "phone", "in": "query", "description": "Optional phone number filter (alternative to list view)", "schema": { "type": "string", "nullable": true }, "example": null }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contacts retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactsListResponse" }, "example": { "success": true, "data": { "contacts": [ { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "customer_id": "00000000-0000-0000-0000-000000000000", "phone_number": "+1234567890", "format_e164": "+1234567890", "format_international": "+1 234-567-890", "format_national": "(234) 567-890", "format_rfc": "tel:+1-234-567-890", "country_code": "1", "region_code": "US", "available_channels": "sms,whatsapp", "default_channel": "sms", "opt_out": false, "is_inherited": false, "created_at": "2026-10-06T14:45:18.8892809+00:00", "updated_at": null } ], "pagination": { "page": 1, "page_size": 20, "total_count": 150, "total_pages": 8, "has_more": true, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8893052+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_005", "message": "Page must be greater than 0", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8893072+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Contact not found (when filtering by phone)", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_001", "message": "Contact not found with the specified phone number", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8893078+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8893081+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/contacts/{id}": { "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "description": "**Deprecated.** Use `PATCH /v3/contacts/{id}` with `{\"opt_out\": true}` instead, and expect this to be removed in a future release. It still behaves exactly as before, so nothing needs to change today.\n\nOpting a contact out stops every send to them, which is what deleting one was mostly used for — and it keeps the record of who they were and that they asked. A delete discards the consent history along with the contact, which is the part you need if anyone ever asks why you stopped, or why you started again.\n\nDissociates a contact from the authenticated customer.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ContactsDeleteContactEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "DeleteContactRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsRequestsDeleteContactRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "Contact deleted successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid contact ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid contact ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8840914+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Contact not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_001", "message": "Contact not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8840934+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8840938+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Contacts" ], "summary": "Get contact by ID", "description": "Retrieves a specific contact by their unique identifier. Returns detailed contact information including phone formats, available channels, and opt-out status.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ContactsGetContactByIdEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contact found and returned successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactResponse" }, "example": { "success": true, "data": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "customer_id": "00000000-0000-0000-0000-000000000000", "phone_number": "+1234567890", "format_e164": "+1234567890", "format_international": "+1 234-567-890", "format_national": "(234) 567-890", "format_rfc": "tel:+1-234-567-890", "country_code": "1", "region_code": "US", "available_channels": "sms,whatsapp", "default_channel": "sms", "opt_out": false, "is_inherited": false, "created_at": "2026-10-06T14:45:18.8861955+00:00", "updated_at": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8861958+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request - ContactId is empty or invalid format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_003", "message": "Invalid ID format.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8861977+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Contact not found for the authenticated customer", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_001", "message": "Contact not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8861981+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error - Contact support with request ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8861985+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Updates a contact's default channel and/or opt-out status.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ContactsUpdateContactEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "UpdateContactRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsRequestsUpdateContactRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Contact updated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactResponse" }, "example": { "success": true, "data": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "customer_id": "00000000-0000-0000-0000-000000000000", "phone_number": "+1234567890", "format_e164": "+1234567890", "format_international": "+1 234-567-890", "format_national": "(234) 567-890", "format_rfc": "tel:+1-234-567-890", "country_code": "1", "region_code": "US", "available_channels": "sms,whatsapp", "default_channel": "whatsapp", "opt_out": false, "is_inherited": false, "created_at": "2026-09-06T14:45:18.8908917+00:00", "updated_at": "2026-10-06T14:45:18.8908923+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8908926+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid channel value", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_006", "message": "Invalid channel. Must be 'sms' or 'whatsapp'.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8908942+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Contact not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_001", "message": "Contact not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8908947+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.890895+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/contacts/{contactId}/message-summary": { "get": { "tags": [ "Contacts" ], "summary": "Get message summary for a contact", "description": "Returns aggregate message counts, time bounds, channels used, and per-channel success/fail scores (each as a percentage 0-100 of messages on that channel) for one of your contacts. Successful terminal states: SENT/DELIVERED/READ for outbound, RECEIVED for inbound. Fail: FAILED.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ContactsGetContactMessageSummaryEndpoint", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Summary returned successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactMessageSummaryResponse" }, "example": { "success": true, "data": { "contact_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "message_count": 42, "first_message_at": "2026-09-06T14:45:18.8878309+00:00", "last_message_at": "2026-10-06T11:45:18.8878437+00:00", "channels_used": [ "sms", "whatsapp" ], "channel_scores": [ { "channel": "sms", "success_score": 91, "fail_score": 9 }, { "channel": "whatsapp", "success_score": 90, "fail_score": 10 } ] }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8878975+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request - ContactId is empty or invalid format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Contact not found for the authenticated customer", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_001", "message": "Contact not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8878997+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error - Contact support with request ID", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/compliance/requirements": { "get": { "tags": [ "Compliance" ], "summary": "Get compliance requirements for a market", "description": "**Call this first.** It returns what a channel, country and sender type demand before you can send there — and `setup[]`, the calls that satisfy those demands, in order, each with a body you can copy and send as it stands. You never have to track forty countries' rules yourself.\n\n## Channel\n\n`channel` is `sms`, `whatsapp` or `rcs`, and **defaults to `sms`** — so a caller that omits it gets exactly what this endpoint has always returned.\n\n`sms` is the only one answered today; the other two are `501` until their requirements are declared. They are refused rather than answered with an empty requirement set, because empty would say the channel demands nothing, and both demand plenty — WhatsApp a business verification and a display name review, RCS a carrier approval. Saying \"not yet\" is the true answer and the same one `POST /v3/sender-profiles` gives for `channels.whatsapp`.\n\n`type` is an SMS sender type, and SMS is the only channel whose senders have one.\n\nRequirements vary enormously. US `TEN_DLC` registers a brand and a campaign with The Campaign Registry and asks for a substantial set of values. An alphanumeric sender in one country pre-registers with supporting documents; in another it needs nothing at all. This is the authoritative answer for whichever market you are asking about, and it is the same declaration used to validate the calls themselves — so it can never drift from what is actually enforced.\n\n## `setup[]` — what to do\n\n**One step.** `POST /v3/channels/sms` adds the market and records everything it registers with — the identity in `compliance.brand`, the programme in `compliance.campaign`. There were three, in a load-bearing order, while the identity and the campaign were resources of their own; they are members of this call's body now, so there is nothing to sequence.\n\nCorrect any of it afterwards with `PATCH /v3/channels/sms/{country}/{type}`, which takes the same `compliance` object one key at a time.\n\nEach step's `body` has every key that market wants already present, with the values left **blank**. Blank rather than filled with placeholders, because the body is meant to be sent: a null value counts as not supplied, so posting a step verbatim comes back naming every blank you left. `attachments[]` lists files to send as multipart on the channel call, each under the field name given — a file cannot be a JSON value, so documents are never listed in `compliance[]`.\n\nEvery step is a call for whoever holds the key. To set a **sender profile** up instead, send the same requests with the `x-profile-id` header naming it; there is no separate path.\n\n## `requirements[]` — what each value means\n\nEach entry names a key for the `compliance` array, its value type, and whether it is required. `required_when` marks values needed only in certain cases — evaluate it against your own payload, e.g. `brand.entity_type == PUBLIC_PROFIT`. `options` lists accepted values where the market constrains them, and `label` is suitable for rendering a form field.\n\nValues Sent supplies on your behalf are never listed: correlation ids, environment flags, carrier elections, and booleans derivable from what you already send.\n\n## When nothing is required\n\n`required` is `false` and `requirements` is empty, and the single `setup` step carries no `compliance` array at all. A `sender_id_pattern` may still be present — many markets constrain the sender string without registering anything.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ComplianceGetComplianceRequirementsEndpoint", "parameters": [ { "name": "channel", "in": "query", "description": "Channel the sender is for: sms, whatsapp or rcs. Defaults to sms, which is the only one answered today — the other two are 501 until their requirements are declared.", "schema": { "type": "string", "nullable": true } }, { "name": "country", "in": "query", "description": "ISO 3166-1 alpha-2 country code, e.g. US, XK, IN", "schema": { "type": "string", "nullable": true } }, { "name": "type", "in": "query", "description": "Sender type: LOCAL, MOBILE, TEN_DLC, TOLL_FREE, SHORT_CODE, ALPHANUMERIC. 10DLC is accepted as a synonym of TEN_DLC, the same as on POST /v3/sender-profiles. Applies to channel=sms, the only channel whose senders have a type.", "schema": { "type": "string", "nullable": true } }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Requirements for the requested market", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfComplianceRequirementsResponse" }, "example": { "success": true, "data": { "channel": "sms", "country": "US", "type": "TEN_DLC", "required": true, "sender_id_pattern": null, "requirements": [ { "key": "brand", "type": "object", "format": null, "required": false, "required_when": null, "options": null, "min_length": null, "max_items": null, "item_fields": [ { "key": "inherit", "type": "boolean", "format": null, "required": false, "required_when": null, "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Run on the organization's brand", "notes": "True to register under the parent organization's identity rather than one of this profile's own; every field below is then neither asked for nor accepted. Omitted, the brand is the organization's unless this block supplies identity fields, which says plainly enough that it wants one of its own." }, { "key": "legal_name", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Registered legal name", "notes": "TCR companyName — the name on the incorporation documents, which is often not the name recipients would recognise." }, { "key": "business_name", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Public-facing name", "notes": "TCR displayName — the name recipients would recognise. Named for what it holds rather than for TCR's field, which is why it is not `display_name`." }, { "key": "tax_id", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Tax identifier", "notes": "TCR ein. TcrBrandSubmissionValidator refuses a submission without one, so it is wanted here rather than discovered at filing time." }, { "key": "tax_id_type", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Kind of tax identifier", "notes": "Which kind of identifier `tax_id` is, e.g. us_ein. Derived onto the brand form, and not itself sent to TCR." }, { "key": "ein_issuing_country", "type": "string", "format": "iso3166_alpha2", "required": false, "required_when": null, "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Country that issued the tax id", "notes": "TCR einIssuingCountry — where the tax id was issued, which is not always where the business trades. Defaults to `country` when omitted, which is right for most. Takes the code or the country spelled out, as `country` does." }, { "key": "entity_type", "type": "enum", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": [ "PRIVATE_PROFIT", "PUBLIC_PROFIT", "NON_PROFIT", "SOLE_PROPRIETOR", "GOVERNMENT" ], "min_length": null, "max_items": null, "item_fields": null, "label": "Entity type", "notes": "TCR entityType. Decides which vetting TCR applies and, for SOLE_PROPRIETOR, fixes the campaign fee regardless of volume. Also refused at submission if absent." }, { "key": "street", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Street address", "notes": null }, { "key": "city", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "City", "notes": null }, { "key": "state", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "State or region", "notes": "TCR state. Two letters for a US registration." }, { "key": "postal_code", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Postal code", "notes": null }, { "key": "country", "type": "string", "format": "iso3166_alpha2", "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Country of registration", "notes": "Two letters — US. The country spelled out in full is accepted too and stored as its code, which is what a read answers with and what is filed." }, { "key": "website", "type": "string", "format": "url", "required": false, "required_when": null, "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Website", "notes": "TCR website. Optional, and worth sending: carriers weigh it when vetting, so a brand that has one and omits it is vetted on less than it could be." }, { "key": "contact_name", "type": "string", "format": null, "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Responsible contact", "notes": "Split into TCR's firstName/lastName on submission. BrandService refuses a blank one, so a missing name is reported here rather than thrown after the profile was written." }, { "key": "contact_email", "type": "string", "format": "email", "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Contact email", "notes": "TCR email." }, { "key": "contact_phone", "type": "string", "format": "e164", "required": false, "required_when": "compliance.brand.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Contact phone", "notes": "TCR sends it as both phone and mobilePhone, so it is asked for once. Named for the contact it belongs to rather than as a bare `phone` on a block that also carries an address." } ], "label": "Business identity", "notes": "The identity the registration is filed against. Omit to have none; { \"inherit\": true } to register under your organization's." }, { "key": "campaign", "type": "object", "format": null, "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": [ { "key": "inherit", "type": "boolean", "format": null, "required": false, "required_when": null, "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Run on the organization's campaign", "notes": "True to register under the parent organization's programme rather than one of this profile's own; every field below is then neither asked for nor accepted. Owning the identity and inheriting the campaign is refused — a campaign is filed against an identity registration, and chk_tcr_inheritance forbids that pairing outright." }, { "key": "description", "type": "string", "format": null, "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "What this programme sends", "notes": "TCR description: what recipients will get and why, in a sentence. The only one of these TCR takes verbatim as a description of the programme, which is why it is asked for rather than derived from the customer's name." }, { "key": "message_flow", "type": "string", "format": null, "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": 40, "max_items": null, "item_fields": null, "label": "Consent narrative", "notes": "TCR messageFlow: how recipients opt in, in prose. Under 40 characters is refused, and carriers reject vague descriptions — say where opt-in happens, that the box is unchecked by default, and that consent is not a condition of purchase." }, { "key": "use_cases", "type": "array", "format": null, "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": 5, "item_fields": [ { "key": "use_case", "type": "enum", "format": null, "required": true, "required_when": null, "options": [ "MARKETING", "ACCOUNT_NOTIFICATION", "CUSTOMER_CARE", "FRAUD_ALERT", "2FA", "DELIVERY_NOTIFICATION", "SECURITY_ALERT", "M2M", "HIGHER_EDUCATION", "POLLING_VOTING", "PUBLIC_SERVICE_ANNOUNCEMENT" ], "min_length": null, "max_items": null, "item_fields": null, "label": "Use case", "notes": "What this entry sends. MIXED and LOW_VOLUME are refused — volume decides those." }, { "key": "sample_messages", "type": "array", "format": null, "required": true, "required_when": null, "options": null, "min_length": null, "max_items": 5, "item_fields": null, "label": "Sample messages", "notes": "TCR sample1..sample5 for this use case. One to five, each carrying the brand name and an opt-out instruction." } ], "label": "Use cases", "notes": "What the campaign sends, and an example of each. One to five entries; how they register is decided by volume, never declared." }, { "key": "opt_in_message", "type": "string", "format": null, "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Opt-in confirmation", "notes": "TCR optinMessage. Should state message frequency and that rates may apply. Its presence is what sets subscriberOptin." }, { "key": "opt_out_message", "type": "string", "format": null, "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Opt-out confirmation", "notes": "TCR optoutMessage. Its presence is what sets subscriberOptout." }, { "key": "help_message", "type": "string", "format": null, "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Help reply", "notes": "TCR helpMessage. Its presence is what sets subscriberHelp." }, { "key": "opt_in_keywords", "type": "string", "format": "csv_keywords", "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Opt-in keywords", "notes": "TCR optinKeywords, comma separated, e.g. START,YES." }, { "key": "opt_out_keywords", "type": "string", "format": "csv_keywords", "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Opt-out keywords", "notes": "TCR optoutKeywords, comma separated. STOP, END, CANCEL, UNSUBSCRIBE and QUIT are honoured regardless of what is declared." }, { "key": "help_keywords", "type": "string", "format": "csv_keywords", "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Help keywords", "notes": "TCR helpKeywords, comma separated, e.g. HELP,INFO." }, { "key": "privacy_policy_link", "type": "string", "format": "url", "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Privacy policy URL", "notes": "TCR privacyPolicyLink." }, { "key": "terms_and_conditions_link", "type": "string", "format": "url", "required": false, "required_when": "compliance.campaign.inherit != true", "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Terms and conditions URL", "notes": "TCR termsAndConditionsLink." }, { "key": "volume", "type": "string", "format": null, "required": false, "required_when": null, "options": null, "min_length": null, "max_items": null, "item_fields": null, "label": "Expected monthly volume", "notes": "Decides how the campaign registers and which fee tier applies: below the low-volume threshold it registers as LOW_VOLUME with sub-use-cases, above it as a single use case or MIXED. Omitting it registers the campaign at the higher-fee standard tier." } ], "label": "Messaging campaign", "notes": "What the programme sends and how recipients consented. Omit to run on your organization's; supplying it takes one of your own. { \"inherit\": true } says so outright." } ], "setup": [ { "step": 1, "resource": "channel", "method": "POST", "path": "/v3/channels/sms", "why": "Adds the market, claims a number for it, and records everything The Campaign Registry asks — the identity in `compliance.brand`, the programme in `compliance.campaign`. The registration stays outstanding until it is filed and answered, which happens off this call.", "body": { "country": "US", "number_type": "TEN_DLC", "sender_value": null, "compliance": { "brand": { "inherit": null, "legal_name": null, "business_name": null, "tax_id": null, "tax_id_type": null, "ein_issuing_country": null, "entity_type": null, "street": null, "city": null, "state": null, "postal_code": null, "country": null, "website": null, "contact_name": null, "contact_email": null, "contact_phone": null }, "campaign": { "inherit": null, "description": null, "message_flow": null, "use_cases": null, "opt_in_message": null, "opt_out_message": null, "help_message": null, "opt_in_keywords": null, "opt_out_keywords": null, "help_keywords": null, "privacy_policy_link": null, "terms_and_conditions_link": null, "volume": null } } }, "attachments": null } ] }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.895543+00:00", "version": "v3" } } } } }, "400": { "description": "Missing or unrecognised channel, country or sender type", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "type must be one of: LOCAL, MOBILE, TEN_DLC, TOLL_FREE, SHORT_CODE, ALPHANUMERIC", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.8955458+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "501": { "description": "That channel's requirements are not published here yet", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "503": { "description": "The market exists but its configuration is incomplete, so nothing can be sent there yet", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/rcs": { "post": { "tags": [ "Channels" ], "summary": "Add an RCS agent", "description": "Asks for an RCS agent and records the order form the carriers vet it against. Always `202`: an agent is approved by the carriers, not by this call, and nothing here can make that happen sooner.\n\n## What it asks for\n\nThe RCS Agent Order Form — the same one our team fills in on your behalf today, so nothing has to be collected from you twice. **All fields are required** and must be submitted together so the carrier review has everything it needs. The only exception is `opt_in_screenshot_url`.\n\n**Agent identity:** `display_name`, `description`, `agent_use_case` (must be one of the accepted use cases; the error names the set), `brand_color` (six-digit hex, `#RRGGBB`).\n\n**Brand identity:** `brand_name` — the brand this agent presents. Not taken from `compliance.brand`: a business may present a different brand on RCS than the one its 10DLC registration is filed against, and the carriers vet this one. `privacy_policy_url`, `terms_and_conditions_url`, `website_url`, `logo_url`, and `banner_url` must be absolute `http(s)` URLs that the carriers can fetch without authentication. The form specifies 224×224 px and 50 KB for the logo and 1440×448 px and 200 KB for the banner; these cannot be checked without the image bytes.\n\n**Contact details:** `brand_phone_number`, `customer_support_phone_number`, `brand_email`, `customer_support_email`, `contact_name_and_title`.\n\n**Company:** `company_ein`, `entity_type`, `official_address` (street, city, state, postal_code, country), `brief_company_description`.\n\n**Consent and messages:** `opt_in_process_description`, `start_message`, `help_message`, `stop_message`, `sample_messages` (at least one example message).\n\n**Optional:** `opt_in_screenshot_url` (validated as an http(s) URL if supplied).\n\nAnything supplied is checked against accepted values rather than passed through: a value the provider rejects would otherwise surface days later, to somebody who cannot fix it without asking you.\n\n**A customer has one agent.** Asking again while you have one is `409`.\n\n## What comes back, and what does not\n\nReturns **the agent** — the form as stored, plus `id` and `status`. Not your other channels, which this call cannot have changed.\n\n`status` is `PROVISIONING` until the agent is handed to the carriers and approved. **`GET /v3/channels` reports `rcs: null` until then** — a channel row is what routing reads to decide you are sendable, and writing one for an unapproved agent would claim a channel that cannot carry traffic.\n\nSend `x-profile-id` with an organization key to ask for one of your profiles' agents.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsAddRcsChannelEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "AddRcsChannelRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddRcsChannelRequest" } } }, "required": true, "x-position": 1 }, "responses": { "202": { "description": "The agent is recorded with status PROVISIONING, awaiting carrier approval", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfRcsAgentState" }, "example": { "success": true, "data": { "id": "c87b77eb-d936-497f-b662-a865a35d802c", "status": "PROVISIONING", "reason_code": "CHANNEL_011", "reason": "This channel is being set up", "display_name": "Example Retail", "description": "Order and delivery notifications for Example Retail customers.", "agent_use_case": "NOTIFICATIONS", "brand_name": "Example Retail", "privacy_policy_url": "https://example.com/privacy", "terms_and_conditions_url": "https://example.com/terms", "website_url": "https://example.com", "brand_color": "#1a73e8", "brand_phone_number": "+12125550100", "customer_support_phone_number": "+18005550100", "brand_email": "hello@example.com", "customer_support_email": "support@example.com", "contact_name_and_title": "Jane Smith, Head of Marketing", "company_ein": "12-3456789", "entity_type": "PRIVATE_PROFIT", "official_address": { "street": "123 Main St", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" }, "brief_company_description": "Example Retail sells home goods across the US and ships to 48 states.", "opt_in_process_description": "Customers opt in at checkout by checking the SMS/RCS notifications box.", "start_message": "Welcome to Example Retail! Reply HELP for help or STOP to opt out.", "help_message": "For help, visit https://example.com/support or call 1-800-555-0100.", "stop_message": "You have been unsubscribed from Example Retail notifications.", "sample_messages": [ "Your order #12345 has shipped and will arrive tomorrow." ], "created_at": "2025-06-01T12:00:00+00:00" }, "meta": { "request_id": "req_7D5fRp1sSw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "A required field is missing or not an accepted value", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "brand_name is required", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7D5fRp1sSw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "409": { "description": "This customer already has an RCS agent", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_007", "message": "This customer already has an RCS agent. An agent cannot be withdrawn through the API once asked for, so contact support to change or replace it.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7D5fRp1sSw", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "500": { "description": "The agent could not be written", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/sms": { "post": { "tags": [ "Channels" ], "summary": "Add an SMS market — a country and sender type", "description": "Gives the customer a sender in one country — the first market it sends in, and the fifth.\n\n## What to have in place first\n\n**Call `GET /v3/compliance/requirements?country=US&type=TEN_DLC` first.** It returns this request's body ready to fill in, plus the brand and campaign calls to make before it, in order. You never have to track forty countries' rules yourself.\n\n**A market that registers with a compliance regime needs an identity, and this call takes one.** US `TEN_DLC` registers with The Campaign Registry and files that registration against a business identity. Send it in `compliance.brand` and it is recorded here, before the registration that attaches to it — so a customer with no identity reaches a first 10DLC market in one call.\n\n`{ \"inherit\": true }` runs on your organization's instead. A market with neither — none stored, none sent — is `400`, because accepting it would write a channel that could never register and leave it provisioning for ever with nothing saying why.\n\n**Everything the regime wants arrives in this request's `compliance`**, as two declared objects: `brand` — the identity the registration is filed against — and `campaign`, with the use case, the consent narrative, the volume, the sample messages and the keywords. There is nothing to set up first. Nothing is submitted here either: the rows are what a submission is later assembled from, and filing is externally rejectable so it happens on its own path.\n\n**A half you run yourself has to be complete here.** Whichever of `brand` and `campaign` is your own rather than your organization's must carry every field the regime asks of it, counting what you already hold — send the rest in this request. A missing one is `400` naming each field, rather than a `202` for a market that could never be filed. A half you inherit is asked for nothing.\n\nA market that registers with nobody — an alphanumeric sender in most countries — needs neither, and may need documents instead.\n\n## Sending it\n\nTakes the same fields `channels.sms` takes on `POST /v3/sender-profiles`, because it is the same work, and both run one provisioning path. `compliance` is top-level and answers for the market in this request, carrying `brand` and `campaign` where the market registers.\n\n**Accepts multipart as well as JSON**, with each file named after the compliance key it satisfies — a market that pre-registers its sender needs its documents at the same moment it needs the sender. Every required document must be attached to this request; a missing or invalid file is rejected before the market is added.\n\n**`area_codes` puts the sender somewhere specific**, in your order of preference, for a `LOCAL` sender in any country or a US `TEN_DLC` sender — a 10DLC number is an ordinary local long code bound to a registered campaign, so both take the same codes out of the same inventory. It is honoured exactly: you get a number in one of the codes you named or you get none, never one in a code you left out.\n\n## Several numbers\n\n**`numbers` lists the numbers you want, one entry per area code**, e.g. `[{\"area_code\": \"212\", \"quantity\": 2}, {\"quantity\": 1}]` for two numbers in 212 and one in any area code. `quantity` defaults to 1, and an entry without `area_code` means any area code. Omit `numbers` for one number. It is for `LOCAL` and `TEN_DLC` only and cannot be combined with `area_codes`. A market holds at most 10 numbers, counting the ones it already has.\n\n**On a `LOCAL` market you already hold, `numbers` adds those numbers to it** instead of `409`. US `TEN_DLC` numbers belong to the market's campaign and are assigned when the campaign is approved, not at request time. Until then they read as `PROVISIONING` in the response's `numbers`, each with the area code it was asked for. A profile inheriting your organization's campaign cannot request `numbers` (`400`). `numbers` on a `TEN_DLC` market you already hold is `409`: its numbers belong to its one campaign and are set when the market is created.\n\n**A market you already send in is `409`**: adding what is already there is a mistake worth reporting rather than a silent no-op. A market is a `(country, sender_type)` pair, so a **second sender type in a country you already send in is fine** — `US TOLL_FREE` alongside `US TEN_DLC` is the ordinary case. Two of the same type is not.\n\n**A market you hold that has no sender yet is not a duplicate**, and re-sending it re-asks for a sender rather than being refused. That is the way out of an area-code request nothing could fill: send the call again to name different codes, or no codes at all to take a number anywhere in the country. It answers `201` with the sender when the pool has one, otherwise `202` with the codes recorded — and changes nothing else; compliance on a market you hold is `PATCH /v3/channels/sms/{country}/{type}`.\n\nOne exception: while a market's sender type is still unassigned, adding any type to that country is `409` once it has a sender, because the market you have may be about to become the one you asked for.\n\nReturns **the market**, in the shape `GET` and `PATCH` on `/v3/channels/sms/{country}/{type}` use — so what this answers can be read back and written back without reshaping. Not every channel you have: adding a market cannot change an RCS agent or a WhatsApp account, and `GET /v3/channels` is the whole picture. `201` when the market is ready; `202` while a sender or a registration is still outstanding.\n\nSend `x-profile-id` with an organization key to add a market to one of your profiles.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsAddSmsChannelEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "AddSmsChannelRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddSmsChannelRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddSmsChannelRequest" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "The market is ready", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSmsMarketState" }, "example": { "success": true, "data": { "country": "GB", "number_type": "ALPHANUMERIC", "sender_value": "ExmplRetail", "numbers": [], "status": "ACTIVE", "compliance": { "documents": [ { "key": "senderid_registration_requirements", "file_name": "sender-id-registration.pdf", "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6" } ] } }, "meta": { "request_id": "req_5B3dPn9qSu", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "202": { "description": "Added, or re-asked, with a sender or a registration still outstanding", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSmsMarketState" }, "example": { "success": true, "data": { "country": "US", "number_type": "TEN_DLC", "sender_value": null, "numbers": [], "status": "PROVISIONING", "reason_code": "CHANNEL_011", "reason": "Sent is setting this market up.", "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US", "website": "https://example.com" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout." }, "documents": [] } }, "meta": { "request_id": "req_5B3dPn9qSu", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "TEN_DLC is a US registration and cannot be added for GB.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_5B3dPn9qSu", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "The customer could not be read", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "409": { "description": "The customer already sends in that market, or in that country under a sender type that is not assigned yet", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_007", "message": "This customer already sends in US as TEN_DLC", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_5B3dPn9qSu", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "422": { "description": "A required pre-registration document is missing or an uploaded file is invalid", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Channels" ], "summary": "List your SMS markets", "description": "Every market you send SMS in, each with its sender, where that sender stands, and what its compliance holds.\n\nThe same entries `GET /v3/channels` reports under `sms`, and the same shape `GET /v3/channels/sms/{country}/{type}` returns for one of them — so a list, a member read and the all-channels read cannot describe a market differently.\n\nSend `x-profile-id` with an organization key to list one of your profiles' markets.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsMarketGetSmsMarketsEndpoint", "parameters": [ { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Your SMS markets", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfSmsMarketState" }, "example": { "success": true, "data": [ { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550100", "numbers": [], "status": "ACTIVE", "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout." }, "documents": [] } }, { "country": "GB", "number_type": "ALPHANUMERIC", "sender_value": "ExmplRetail", "numbers": [], "status": "ACTIVE", "compliance": { "documents": [ { "key": "senderid_registration_requirements", "file_name": "sender-id-registration.pdf", "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6" } ] } } ], "meta": { "request_id": "req_3Z0aNl7oQs", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "The customer could not be read", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_004", "message": "The customer could not be read", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_3Z0aNl7oQs", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/voice": { "post": { "tags": [ "Channels", "Voice" ], "summary": "Turn phone calls on for a number", "description": "Adds voice to one of the numbers you hold, or gives you a new one. Send `number` for a number that is already yours (see `GET /v3/channels`); leave it out to be given a new US number, optionally in a particular `area_code`. Sending both is refused. Nothing registers, so the number can carry calls as soon as this returns.\n\nWhat happens on a call is decided by your `callback_url`: when a call arrives on the number, or a caller presses a key on a menu, Sent POSTs a signed question there and follows the answer. The response carries the `callback_secret` the questions are signed with, the one time it is shown without rotating; verify a question the way you verify a webhook. `POST /v3/channels/voice/{number}/test` sends a test question and reports the verdict.\n\nYour first voice number becomes the line app-originated calls are placed from when a voice token names no number; send `default_for_app_calls: true` to give that role to another number. A number you turned off earlier is turned back on, and the same number with a different `callback_url` has its URL replaced and keeps its secret.\n\nRead the number's settings with `GET /v3/channels/voice` and change them with `PATCH /v3/channels/voice/{number}`.\n\nWith `sandbox: true` the request is validated and a simulated number reported with `202`; nothing is written and no number is bought.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsAddVoiceChannelEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "AddVoiceChannelRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest" }, "examples": { "Example": { "value": { "number": "+12125550100", "area_code": null, "callback_url": "https://example.com/voice", "default_for_app_calls": false, "sandbox": false } }, "Give me a number": { "summary": "No number of your own: Sent finds you one in the area code and turns calls on for it.", "value": { "number": null, "area_code": "212", "callback_url": "https://example.com/voice", "default_for_app_calls": null, "sandbox": false } } } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Voice is on for the number; store callback_secret now", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberCreatedResponse" }, "example": { "success": true, "data": { "callback_secret": "whsec_MWYyZDFlMmU2N2RmNmI3YThmNTZhODFiYzJlNGQzYjI=", "number": "+12125550100", "status": "ACTIVE", "default_for_app_calls": true, "callback_url": "https://example.com/voice", "created_at": "2026-07-22T12:00:00+00:00", "updated_at": "2026-07-22T12:00:00+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9526947+00:00", "version": "v3" } } } } }, "202": { "description": "Sandbox: the request is valid and this is what would have been written", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberCreatedResponse" } } } }, "400": { "description": "The number is not a phone number or not one of your numbers, number and area_code were both sent, or callback_url is not a public HTTP or HTTPS URL", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_022", "message": "Phone number is not owned by this account", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9526987+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "description": "Another account already carries calls on this number, or no number is available in the area code asked for", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "502": { "description": "The number could not be set up to receive calls; nothing was written", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Channels", "Voice" ], "summary": "List your voice numbers", "description": "Every number you turned phone calls on for, active or inactive, oldest first. Each entry carries the number's status, whether it is the default line for calls placed from your app, and its callback URL. The signing secret is never on a read; it is shown when voice is turned on and by `POST /v3/channels/voice/{number}/rotate-secret`.\n\nThe same entries `GET /v3/channels` reports under `voice`, and the same shape `GET /v3/channels/voice/{number}` returns for one of them. Change a number with `PATCH /v3/channels/voice/{number}`.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsGetVoiceChannelsEndpoint", "parameters": [ { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Your voice numbers", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfVoiceNumberState" }, "example": { "success": true, "data": [ { "number": "+12125550100", "status": "ACTIVE", "default_for_app_calls": true, "callback_url": "https://example.com/voice", "created_at": "2026-07-22T12:00:00+00:00", "updated_at": "2026-07-22T12:00:00+00:00" }, { "number": "+12125550101", "status": "INACTIVE", "default_for_app_calls": false, "callback_url": "https://example.com/voice-support", "created_at": "2026-07-23T09:30:00+00:00", "updated_at": "2026-08-01T16:45:00+00:00" } ], "meta": { "request_id": "req_5V2kLm8nQr", "timestamp": "2026-07-22T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/whatsapp": { "post": { "tags": [ "Channels" ], "summary": "Add a WhatsApp account", "description": "Connects a WhatsApp Business Account shared with us through a Multi-Partner Solution to the calling sender profile. Send `x-profile-id` for the profile the account belongs to.\n\n**Two fields, because everything else is derived.** `waba_id` says which of your organization's shared accounts this is — you hold one per client, and nothing else can say which. `phone_number_id` names the account's number, which is what assigns it to the profile as the number it sends from.\n\nThe solution the account arrived through, the client business portfolio that owns it, the access token and its expiry are all resolved from your organization. They are not accepted here: the first two are Meta's answer about provenance, and the token is minted per client business and rotates roughly every sixty days, so a value you sent would be stale before it was useful.\n\n`phone_number_id` is optional. Omit it to connect the account now and settle the number later — the channel reads as `ACTION_NEEDED` with `reason_code` `CHANNEL_007`, and the profile's WhatsApp messages fail until a number is named. They do not fall back to your organization's account. Call this endpoint again with `phone_number_id` to name one.\n\nThe same resolution runs behind `channels.whatsapp` on `POST /v3/sender-profiles`, so connecting at create and connecting afterwards fill the same fields.\n\nReturns **the account**, not every channel you have — adding one cannot change a market or an RCS agent, and `GET /v3/channels` is the whole picture. Giving an account up is not self-service: ask support, because deregistering a number lands in your own Meta business.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsAddWhatsappChannelEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "AddWhatsappChannelRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddWhatsappChannelRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The account is connected to the profile", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWhatsappChannelState" }, "example": { "success": true, "data": { "waba_id": "102290129340398", "phone_number_id": "106540352242922", "solution_id": "473829105612345", "owner_business_id": "918273645098765", "status": "ACTIVE" }, "meta": { "request_id": "req_8E6gSq2tUx", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "waba_id is missing, the call was not scoped to a sender profile with x-profile-id, the account is not one this organization can reach, Meta would not issue a token for it, or the number is already in use by another profile", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "WhatsApp Business Account not found", "details": { "waba_id": [ "WhatsApp Business Account not found" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_8E6gSq2tUx", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "The account was connected but could not be read back", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/voice/tokens": { "post": { "tags": [ "Channels", "Voice" ], "summary": "Create a voice token", "description": "Mints a short-lived token for one of your app users. Call this from your backend and return the token to your app, which passes it to the voice client SDK to register. The identity is bound to the given number, or to your default app-call number when omitted, and calls placed by that identity are routed through the bound number. Minting again re-binds the identity, so an identity can move between numbers.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsCreateVoiceTokenEndpoint", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CreateVoiceTokenRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsCreateVoiceTokenRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Token minted and identity bound to the number", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceTokenResponse" }, "example": { "success": true, "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudC00MiJ9.signature", "identity": "agent-42", "number": "+12025550123", "expires_at": "2026-07-22T12:34:56+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9575809+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid identity, ttl out of range, or number not voice-enabled for this account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_024", "message": "Phone number is not voice-enabled for this account", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9575826+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Phone calls are not enabled for this account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_023", "message": "Phone calls are not enabled for this account", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9575832+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while creating the voice token", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9575836+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels": { "get": { "tags": [ "Channels" ], "summary": "Get your channels", "description": "Every market you send SMS in, your WhatsApp account, your RCS agent and the numbers you carry phone calls on — with each one's status, and what each market has supplied.\n\n**Status lives on the channel, never on you or your brand.** An identity has no lifecycle; what has one is the registration of a sender in a market and the approval of a channel. So a customer live in one country and mid-registration in another reports exactly that, rather than one flattened answer.\n\n`sms[n].compliance` carries what each market holds: `brand` and `campaign` for markets that register with a compliance regime such as US TEN_DLC, and `documents` for markets that pre-register an alphanumeric or similar sender. Absent means the market registers with nobody and nothing has been supplied. `GET /v3/compliance/requirements` says what a market demands of any new customer; this says what you gave it.\n\nSend `x-profile-id` with an organization key to read one of your profiles' channels.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsGetChannelsEndpoint", "parameters": [ { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The channels you send on", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfileChannelsState" }, "example": { "success": true, "data": { "customer_id": "550e8400-e29b-41d4-a716-446655440000", "sms": [ { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550100", "numbers": [], "status": "ACTIVE", "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout." }, "documents": [] } }, { "country": "GB", "number_type": "ALPHANUMERIC", "sender_value": "ExmplRetail", "numbers": [], "status": "ACTIVE", "compliance": { "documents": [ { "key": "senderid_registration_requirements", "file_name": "sender-id-registration.pdf", "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6" } ] } } ], "whatsapp": null, "rcs": { "id": "c87b77eb-d936-497f-b662-a865a35d802c", "status": "PROVISIONING", "reason_code": "CHANNEL_011", "reason": "This channel is being set up", "display_name": "Example Retail", "description": "Order and delivery notifications for Example Retail customers.", "agent_use_case": "NOTIFICATIONS", "brand_name": "Example Retail", "privacy_policy_url": "https://example.com/privacy", "terms_and_conditions_url": "https://example.com/terms", "website_url": "https://example.com", "brand_color": "#1a73e8", "brand_phone_number": "+12125550100", "customer_support_phone_number": "+18005550100", "brand_email": "hello@example.com", "customer_support_email": "support@example.com", "contact_name_and_title": "Jane Smith, Head of Marketing", "company_ein": "12-3456789", "entity_type": "PRIVATE_PROFIT", "official_address": { "street": "123 Main St", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" }, "brief_company_description": "Example Retail sells home goods across the US and ships to 48 states.", "opt_in_process_description": "Customers opt in at checkout by checking the SMS/RCS notifications box.", "start_message": "Welcome to Example Retail! Reply HELP for help or STOP to opt out.", "help_message": "For help, visit https://example.com/support or call 1-800-555-0100.", "stop_message": "You have been unsubscribed from Example Retail notifications.", "sample_messages": [ "Your order #12345 has shipped and will arrive tomorrow." ], "created_at": "2025-06-01T12:00:00+00:00" }, "mms": [], "voice": [ { "number": "+12125550100", "status": "ACTIVE", "default_for_app_calls": true, "callback_url": "https://example.com/voice", "created_at": "2025-06-01T12:00:00+00:00", "updated_at": "2025-06-01T12:00:00+00:00" } ] }, "meta": { "request_id": "req_4A2cNm8pRt", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "The customer could not be read", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_004", "message": "The customer could not be read", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_4A2cNm8pRt", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/voice/{number}": { "get": { "tags": [ "Channels", "Voice" ], "summary": "Get one voice number", "description": "Reads one of your voice numbers, active or inactive: its status, whether it is the default line for calls placed from your app, and its callback URL. The signing secret is not on this read.\n\nThe same shape `GET /v3/channels/voice` lists, and the same shape `PATCH` on this path accepts and returns, so what comes back can be sent back.\n\nThe number is the E.164 value in the path with the plus sign URL-encoded (`%2B`).", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsGetVoiceChannelEndpoint", "parameters": [ { "name": "number", "in": "path", "required": true, "description": "The number in E.164 format with the plus sign URL-encoded, e.g. %2B12125550100", "schema": { "type": "string" }, "example": "+12125550100" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The voice number", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberState" }, "example": { "success": true, "data": { "number": "+12125550100", "status": "ACTIVE", "default_for_app_calls": true, "callback_url": "https://example.com/voice", "created_at": "2026-07-22T12:00:00+00:00", "updated_at": "2026-07-22T12:00:00+00:00" }, "meta": { "request_id": "req_8H3jNq5sWx", "timestamp": "2026-07-22T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "The number is not a phone number", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "'number' must be a valid phone number in E.164 format (e.g. +14155551234)", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_8H3jNq5sWx", "timestamp": "2026-07-22T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "This account has no voice number for that number", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_013", "message": "This account has no voice number +12125550100", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_8H3jNq5sWx", "timestamp": "2026-07-22T12:00:00+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "patch": { "tags": [ "Channels", "Voice" ], "summary": "Change one voice number", "description": "Changes one of your voice numbers and answers with the number as stored, the same shape `GET` on this path returns, so what comes back can be sent back.\n\n## What it changes\n\n| Body | Effect |\n| --- | --- |\n| `\"status\": \"ACTIVE\"` | turns calls on again for a number you turned off; the callback URL and the secret it had are kept |\n| `\"status\": \"INACTIVE\"` | turns calls off; the callback URL and the secret stay on the number |\n| `\"default_for_app_calls\": true` | makes this the line app-originated calls are placed from when a voice token names no number |\n| `\"callback_url\": \"https://example.com/voice\"` | replaces where Sent asks what to do with each call on the number; the signing secret is kept, and a number that was waiting for its first URL is turned on |\n| key omitted | left exactly as it is |\n\n`status` is matched ignoring case. Any combination is accepted: `status: \"ACTIVE\"` with `default_for_app_calls: true` turns a number on as the new default, and a `callback_url` sent with either status is written too. A body that names none of the three is refused.\n\n## What it will refuse\n\n**`default_for_app_calls: false` is `400`.** An account with active voice numbers always has exactly one default, so the default moves by giving it to another number.\n\n**Turning the default line off is `409`** while other active voice numbers remain. Move the default to another number first. Turning off your last voice number is allowed; that turns phone calls off.\n\n**Making an inactive number the default is `400`.** Send `status: \"ACTIVE\"` in the same call.\n\nA number added without a `callback_url` is `INACTIVE` for that one reason, so sending it a `callback_url` turns it on by itself, and it becomes your default line if you have no other active voice number. A number you turned off while it had a URL stays off.\n\n**A number you never turned voice on for is `404`.** Add it with `POST /v3/channels/voice`.\n\nThe number is the E.164 value in the path with the plus sign URL-encoded (`%2B`).\n\nWith `sandbox: true` nothing is written: the request is validated against the stored number and the number is reported with `200` as it would read after the change.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsPatchVoiceChannelEndpoint", "parameters": [ { "name": "number", "in": "path", "required": true, "description": "The number in E.164 format with the plus sign URL-encoded, e.g. %2B12125550100", "schema": { "type": "string" }, "example": "+12125550100" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "PatchVoiceChannelRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsPatchVoiceChannelRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The voice number as stored", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberState" }, "example": { "success": true, "data": { "number": "+12125550100", "status": "ACTIVE", "default_for_app_calls": true, "callback_url": "https://example.com/voice", "created_at": "2026-07-22T12:00:00+00:00", "updated_at": "2026-08-01T16:45:00+00:00" }, "meta": { "request_id": "req_2D6gPt4vYz", "timestamp": "2026-08-01T16:45:00+00:00", "version": "v3" } } } } }, "400": { "description": "The number is not a phone number, status is not ACTIVE or INACTIVE, callback_url is not a public HTTP or HTTPS URL, default_for_app_calls is false, the body changes nothing, or an inactive number was made the default", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Supply at least one of status, default_for_app_calls or callback_url", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_2D6gPt4vYz", "timestamp": "2026-08-01T16:45:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "This account has no voice number for that number", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_013", "message": "This account has no voice number +12125550100", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_2D6gPt4vYz", "timestamp": "2026-08-01T16:45:00+00:00", "version": "v3" } } } } }, "409": { "description": "The number is the default line for app calls and other active voice numbers remain", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_007", "message": "This number is the default line for app calls and other voice numbers are active; move the default to another number first", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_2D6gPt4vYz", "timestamp": "2026-08-01T16:45:00+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/voice/{number}/rotate-secret": { "post": { "tags": [ "Channels", "Voice" ], "summary": "Rotate a voice number's callback secret", "description": "Generates a new signing secret for the questions Sent sends to this number's callback URL and returns it. The previous secret stops signing immediately, so update your backend before the next call reaches it. The number is the E.164 value in the path with the plus sign URL-encoded (`%2B`).\n\nWith `sandbox: true` a secret is generated and returned with `202`, and nothing is written.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsRotateVoiceSecretEndpoint", "parameters": [ { "name": "number", "in": "path", "required": true, "description": "The voice number from the route, in E.164 format with the plus sign URL-encoded (%2B),\nfor example /v3/channels/voice/%2B12025550123/rotate-secret.", "schema": { "type": "string" }, "example": "+12125550100" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "RotateVoiceSecretRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsRotateVoiceSecretRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The new secret. The old one no longer signs anything", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceSecretResponse" }, "example": { "success": true, "data": { "callback_secret": "whsec_MWYyZDFlMmU2N2RmNmI3YThmNTZhODFiYzJlNGQzYjI=" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9690426+00:00", "version": "v3" } } } } }, "202": { "description": "Sandbox: a secret that was not stored", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceSecretResponse" } } } }, "400": { "description": "Invalid number, or the number has never had voice turned on", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_024", "message": "Phone number is not voice-enabled for this account", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9690439+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/voice/{number}/test": { "post": { "tags": [ "Channels", "Voice" ], "summary": "Test a voice number's callback URL", "description": "Sends a synthetic call.request question, flagged \"test\": true, to the number's callback URL, signed with that number's real secret, and reports what came back. Use it to build and debug your callback endpoint without placing calls: no call is placed, nothing is billed, and nothing is stored. One attempt with the same deadline as a live call, no retry. The outcome is ok when your endpoint answered 2xx with a valid answer; otherwise it is timeout, connection_failed, http_error or invalid_answer, with the reason and, for an invalid answer, the field at fault. The number is the E.164 value in the path with the plus sign URL-encoded (`%2B`).\n\nWith `sandbox: true` nothing is sent: the verdict comes back ok with `202` and no request or response in it.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsTestVoiceCallbackEndpoint", "parameters": [ { "name": "number", "in": "path", "required": true, "description": "The voice number from the route, in E.164 format with the plus sign URL-encoded (%2B),\nfor example /v3/channels/voice/%2B12025550123/test. The test question goes to this\nnumber's callback URL and is signed with this number's secret.", "schema": { "type": "string" }, "example": "+12025550123" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "TestVoiceCallbackRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsTestVoiceCallbackRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The test ran. Read outcome to see whether your endpoint passed", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceCallbackTestResponse" }, "example": { "success": true, "data": { "outcome": "ok", "call_id": "call_9f2ab000-0000-4000-8000-000000000001", "request": { "url": "https://example.com/voice", "headers": { "User-Agent": "SentDM-Voice/1.0", "X-Webhook-ID": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "X-Webhook-Timestamp": "1784721600", "X-Webhook-Signature": "v1,xJ/WfHm26o0BBWZ/SIDmZio7C3BbqlcbxvO/QIZpjUA=", "X-Request-Id": "req_7X9zKp2jDw" }, "body": "{\"type\":\"call.request\",\"version\":\"1\",\"callId\":\"call_9f2ab000-0000-4000-8000-000000000001\",\"number\":\"+12025550123\",\"timestamp\":\"2026-07-22T12:00:00+00:00\",\"test\":true,\"direction\":\"outbound\",\"from\":{\"kind\":\"user\",\"identity\":\"test-user\"},\"to\":{\"kind\":\"number\",\"number\":\"+12025550142\"}}" }, "response": { "status_code": 200, "body": "{ \"action\": { \"action\": \"connectToUser\", \"identity\": \"agent-42\" } }" }, "answer": { "valueKind": "Object" }, "error": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.973138+00:00", "version": "v3" } } } } }, "202": { "description": "Sandbox: nothing was sent", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceCallbackTestResponse" } } } }, "400": { "description": "Invalid number, or number not voice-enabled for this account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_024", "message": "Phone number is not voice-enabled for this account", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9731406+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "The account has no voice-enabled number", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_023", "message": "Phone calls are not enabled for this account", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9731415+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while testing the callback URL", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9731419+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/channels/sms/{country}/{type}": { "get": { "tags": [ "Channels" ], "summary": "Get one SMS market (country and sender type)", "description": "Reads one market you send in — its sender, where that sender stands, and everything its compliance holds.\n\n## What `compliance` carries\n\nA market that registers with a compliance regime reports `brand` — the identity the registration is filed against — and `campaign`, the programme filed against it. Each carries `inherit`, saying whether it is yours or your organization's.\n\nA market that registers with nobody has neither, so **both keys are absent** rather than null: absent says this market does not ask, where null would say it asks and you supplied nothing. It reports `documents` instead.\n\n`GET /v3/compliance/requirements` says what a market demands of any new customer; this says what you gave it.\n\n## Writing it back\n\n**`PATCH` this same path**, with the `compliance` object from this response:\n\n```json\n{ \"compliance\": { \"brand\": { \"tax_id\": \"12-3456789\" } } }\n```\n\nNothing else to learn — what comes back can be sent back, an omitted key is left alone. There is no sub-resource for either half: both are singletons of the market, so both are written here.\n\n`GET /v3/compliance/requirements` says what a market demands of anybody; this says what you gave it.\n\nSend `x-profile-id` with an organization key to read one of your profiles' markets.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsMarketGetSmsMarketEndpoint", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code, e.g. us", "schema": { "type": "string" }, "example": "US" }, { "name": "type", "in": "path", "required": true, "description": "Sender type: local, mobile, 10dlc (or ten_dlc), toll_free, short_code, alphanumeric. Matched ignoring case.", "schema": { "type": "string" }, "example": "ten_dlc" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The market", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSmsMarketState" }, "example": { "success": true, "data": { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550100", "numbers": [], "status": "ACTIVE", "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US", "website": "https://example.com" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout." }, "documents": [] } }, "meta": { "request_id": "req_6C4eQo0rTv", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "Unrecognised country or sender type", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "type must be one of: LOCAL, MOBILE, TEN_DLC, TOLL_FREE, SHORT_CODE, ALPHANUMERIC", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_6C4eQo0rTv", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "The customer does not send in that market", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_013", "message": "This customer does not send in US as TEN_DLC", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_6C4eQo0rTv", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "patch": { "tags": [ "Channels" ], "summary": "Amend one SMS market — compliance, documents and numbers", "description": "Supplies whatever this market is waiting on, and answers with the market as stored — the same shape `GET` on this path returns, so **what comes back can be sent back**.\n\n**A market reporting `ACTION_NEEDED` is fixed here**, whatever it is waiting on:\n\n| Outstanding | Send |\n| --- | --- |\n| a `brand` or `campaign` value (US `TEN_DLC`) | `compliance`, as below |\n| a document, in any market | a multipart file named after the document's key |\n| a registration sent back for correction | `compliance.brand` and/or `compliance.campaign` — the identity is accepted even once filed, and the registration goes back for review |\n| different numbers | `numbers`, the list the market asks for from now on |\n\n## Partial, at every level\n\n**An omitted key is left alone. An explicit `null` clears it.** Those are different requests, so `{}` changes nothing and is refused rather than silently accepted, and correcting one field does not blank the others.\n\n```json\n{ \"compliance\": { \"brand\": { \"contact_phone\": \"+12125550123\" } } }\n```\n\nThat leaves the campaign untouched, along with every other field of the identity.\n\n## What a US `TEN_DLC` market holds\n\nTwo halves, both singular: `brand`, the identity the registration is filed against, and `campaign`, the programme filed against it. Each carries `inherit`.\n\n| Body | Effect |\n| --- | --- |\n| `\"brand\": { … }` | supplies or corrects the identity, and takes one of your own |\n| `\"brand\": { \"inherit\": true }` | runs on your organization's, giving up your own |\n| `\"brand\": null` | the same thing, said the short way |\n| `\"campaign\": { … }` | supplies or corrects the programme, and takes one of your own |\n| `\"campaign\": { \"inherit\": true }` | runs on your organization's |\n| key omitted | left exactly as it is |\n\n**Nothing here creates a second anything.** One identity and one campaign per market, so a write is an upsert and a replayed request lands on the row it already wrote. Sending the campaign twice does not file two registrations.\n\n## Every other market\n\nMarkets that register with no regime have neither half, so `compliance` is `400` there. Their compliance is documents, sent here as multipart.\n\n## Documents\n\nSend `multipart/form-data` with **each file named after the compliance key it satisfies** — the key the market's `requirements` names. A file that matches no document the market asks for is `400` naming the keys that would, and a file the upload rules refuse (empty, too large, an unsupported type) is `422`. `compliance` and `numbers` may ride in the same form as text parts holding their JSON.\n\n## Numbers\n\n`numbers` takes the list `POST /v3/channels/sms` takes, for a `LOCAL` or `TEN_DLC` market, and **replaces** what the market asks for — send the list you want, not a difference. Numbers already assigned stay; a list that leaves one of them out is `400`, because nothing here releases a number.\n\n```json\n{ \"numbers\": [ { \"area_code\": \"415\", \"quantity\": 2 }, { \"quantity\": 1 } ] }\n```\n\nA `LOCAL` market is claimed from inventory at once, and whatever inventory cannot cover stays pending. A `TEN_DLC` market's numbers are recorded on its campaign and assigned once the carriers elect it — on the next acquisition cycle when it already has been. They need a campaign of the profile's own: one inherited from the organization is `400`.\n\n## What it will refuse\n\n**A filed identity is `409`.** Once the registration has gone to The Campaign Registry they hold a copy, and a local change would diverge from it silently. The campaign is not frozen — omit `brand` and the same body is accepted. The exception is a registration sent back for correction: the identity is accepted, and a correction to either half sends the registration back for review. Refiling it with The Campaign Registry stays with Sent.\n\n**More than one campaign is `409`.** The schema permits several and an account built on the admin side may hold them; this surface writes one, and editing whichever sorted first would leave the others unmentioned and unedited.\n\nNothing is submitted to a regime here. These are the rows a submission is later assembled from, which is what lets them be corrected without waiting on something externally rejectable.\n\nSend `x-profile-id` with an organization key to write one of your profiles' markets.", "operationId": "SentDmServicesEndpointsCustomerAPIv3ChannelsMarketPatchSmsMarketEndpoint", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code, e.g. us", "schema": { "type": "string" }, "example": "US" }, { "name": "type", "in": "path", "required": true, "description": "Sender type, e.g. 10dlc (or ten_dlc), local or alphanumeric. Only 10dlc in us declares compliance values.", "schema": { "type": "string" }, "example": "ten_dlc" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "MarketComplianceWriteRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsMarketMarketComplianceWriteRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsMarketMarketComplianceWriteRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The market as stored", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSmsMarketState" }, "example": { "success": true, "data": { "country": "US", "number_type": "TEN_DLC", "sender_value": "+12125550100", "numbers": [], "status": "ACTIVE", "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US", "website": "https://example.com", "tax_id": "12-3456789" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout.", "message_flow": "Customers opt in at checkout by checking a consent box." }, "documents": [] } }, "meta": { "request_id": "req_9F7hTr3uVy", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "400": { "description": "A rejected value, an unknown key or file, numbers that leave out a held number, or a body that changes nothing", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Supply at least one value to change", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_9F7hTr3uVy", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No such market, or the customer does not send in it", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_013", "message": "This customer does not send in US as TEN_DLC", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_9F7hTr3uVy", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "409": { "description": "The identity has been filed, or the account holds several campaigns", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_007", "message": "The identity for this profile has already been filed with The Campaign Registry and cannot be changed here. Contact support.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_9F7hTr3uVy", "timestamp": "2025-06-01T12:00:00+00:00", "version": "v3" } } } } }, "422": { "description": "An uploaded file the upload rules refuse", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "500": { "description": "Server Error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/calls/{id}/participants": { "post": { "tags": [ "Voice" ], "summary": "Add a participant to a call", "description": "Dials one of your app users or a phone number into a call that is in a conference room, and answers with the participant's own call record. The participant is a call of their own: it has its own id, can be looked up and hung up, and is billed and reported through call.completed and call.failed like any other call. Every participant needs a positive balance. A phone participant is called from caller_id, which must be one of your numbers, or from the call's owning number when omitted, and needs a destination you may call. Only a call your answer connected to a conference can take participants: a call connected to a user or a number answers 409.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsAddCallParticipantEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "AddCallParticipantRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsRequestsAddCallParticipantRequest" } } }, "required": true, "x-position": 1 }, "responses": { "202": { "description": "The participant is being dialed; the body is their call record", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallResponse" }, "example": { "success": true, "data": { "id": "call_9f2ab000-0000-4000-8000-000000000002", "direction": "outbound", "from": { "kind": "conference", "value": "daily-standup" }, "to": { "kind": "number", "value": "+14155551234" }, "number": "+12025550123", "status": "INITIATED", "failure_reason": null, "started_at": "2026-07-22T12:00:00+00:00", "answered_at": null, "ended_at": null, "duration_seconds": null, "price": null, "recording_available": false, "timeline": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9900913+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid id, participant or caller id; a caller id you do not own; a destination country that is not allowed; or the participant could not be dialed (BUSINESS_025)", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_022", "message": "Phone number is not owned by this account", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9900933+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "402": { "description": "Insufficient balance; checked for every participant, app user or phone", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_003", "message": "Insufficient balance", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9900938+00:00", "version": "v3" } } } } }, "404": { "description": "No call with this id belongs to your account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_015", "message": "Call not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9900943+00:00", "version": "v3" } } } } }, "409": { "description": "The call has already ended, or is not in a conference", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_009", "message": "Call is not in a conference", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9900955+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while adding the participant", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9900959+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Voice" ], "summary": "List the participants of a call", "description": "Lists who is in the conference room one of your live calls is in: each participant's own call id, who they are, whether the room mutes them, and how long they have been connected. The call itself is one of the participants. Use a participant's id to mute or remove them; it is also a call id, so GET /v3/calls/{id} accepts it. A call that has ended answers 409, as does a call that is not in a conference.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsGetCallParticipantsEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The participants of the room the call is in; empty once everyone has left", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfCallParticipantResponse" }, "example": { "success": true, "data": [ { "id": "call_9f2ab000-0000-4000-8000-000000000001", "kind": "user", "value": "agent-42", "muted": false, "duration_seconds": 184 }, { "id": "call_9f2ab000-0000-4000-8000-000000000002", "kind": "number", "value": "+14155551234", "muted": true, "duration_seconds": 96 } ], "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9933401+00:00", "version": "v3" } } } } }, "400": { "description": "The id is not a call id", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "id": [ "'id' must be a call id, such as call_9f2ab000-0000-4000-8000-000000000001" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9933439+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No call with this id belongs to your account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_015", "message": "Call not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9933444+00:00", "version": "v3" } } } } }, "409": { "description": "The call has already ended, or is not in a conference", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_009", "message": "Call is not in a conference", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9933447+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while listing the participants", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9933459+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "delete": { "tags": [ "Voice" ], "summary": "Remove every participant from a call", "description": "Removes every participant from the conference room a live call is in, the call itself included. Every leg ends and is reported through call.completed like any other call. A room that is already empty answers 204 as well. A call that has ended answers 409, as does a call that is not in a conference.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsRemoveCallParticipantsEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "RemoveCallParticipantsRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsRequestsRemoveCallParticipantsRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "Every participant has been removed from the room", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "The id is not a call id", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No call with this id belongs to your account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_015", "message": "Call not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0033864+00:00", "version": "v3" } } } } }, "409": { "description": "The call has already ended, or is not in a conference", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_009", "message": "Call is not in a conference", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0033876+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while removing the participants", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.003388+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/calls/{id}": { "get": { "tags": [ "Voice" ], "summary": "Get a call", "description": "Retrieves one of your calls by id: the parties, the owning number, the current status with its failure reason, duration, price, recording availability, and a timeline of when the call entered each status.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsGetCallEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Call retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallResponse" }, "example": { "success": true, "data": { "id": "call_9f2ab000-0000-4000-8000-000000000001", "direction": "outbound", "from": { "kind": "user", "value": "agent-42" }, "to": { "kind": "number", "value": "+12025550142" }, "number": "+12025550123", "status": "COMPLETED", "failure_reason": null, "started_at": "2026-07-22T12:00:00+00:00", "answered_at": "2026-07-22T12:00:05+00:00", "ended_at": "2026-07-22T12:00:47+00:00", "duration_seconds": 42, "price": null, "recording_available": false, "timeline": [ { "status": "INITIATED", "timestamp": "2026-07-22T12:00:00+00:00" }, { "status": "ANSWERED", "timestamp": "2026-07-22T12:00:05+00:00" }, { "status": "COMPLETED", "timestamp": "2026-07-22T12:00:47+00:00" } ] }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.991867+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid call id format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "id": [ "'id' must be a call id, such as call_9f2ab000-0000-4000-8000-000000000001" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9918705+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Call not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_015", "message": "Call not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.991871+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving the call", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9918714+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/calls/{id}/recordings": { "get": { "tags": [ "Voice" ], "summary": "List a call's recordings", "description": "Returns pre-signed links to the recordings of one of your calls, each valid until its url_expires_at. A recording appears once the call was recorded, by a connect answer with record set, a startRecording instruction or the recordings command, and the call.recording_ready webhook has been sent; until then, and for a call that was never recorded, the list is empty. A call recorded more than once lists every recording, oldest first, each under the recording_id its call.recording_ready webhook carried.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsGetCallRecordingsEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The call's recordings, each with a link", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallRecordingsResponse" }, "example": { "success": true, "data": { "recordings": [ { "recording_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "download_url": "https://recordings.example.com/9f2ab000-0000-4000-8000-000000000001/7c1d2e3f4a5b4c6d8e9f0a1b2c3d4e5f.mp3?X-Amz-Expires=3600&X-Amz-Signature=...", "url_expires_at": "2026-07-22T13:00:00+00:00" } ] }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9948145+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid call id format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "id": [ "'id' must be a call id, such as call_9f2ab000-0000-4000-8000-000000000001" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.994818+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No call with this id belongs to your account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_015", "message": "Call not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9948185+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving the recordings", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9948189+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "post": { "tags": [ "Voice" ], "summary": "Start or stop recording a call", "description": "Starts or stops recording one of your live calls. Use start to begin recording mid-call, or stop to end a recording, whether it was started here or by a connect answer with record set. A call that has already ended answers 409, and so does a call with no phone leg, such as one between two app users, which can't be recorded.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsRecordCallEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "RecordCallRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsRequestsRecordCallRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "The recording is being started or stopped", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "The id is not a call id, or the action is neither start nor stop", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "action": [ "'action' must be one of: start, stop" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0010895+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Call recording is not available", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BUSINESS_026", "message": "Call recording is not available", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0010906+00:00", "version": "v3" } } } } }, "404": { "description": "No call with this id belongs to your account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_015", "message": "Call not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0010911+00:00", "version": "v3" } } } } }, "409": { "description": "The call has already ended, or has no phone leg", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_008", "message": "Call is no longer active", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0010915+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while changing the recording", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0010926+00:00", "version": "v3" } } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/calls": { "get": { "tags": [ "Voice" ], "summary": "List calls", "description": "Retrieves a paginated list of your calls, most recent first. Filter by direction, status, the owning number, and the time the call started (from and to are inclusive). Use the call webhooks for real-time updates; this list is for looking calls up afterwards.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsGetCallsEndpoint", "parameters": [ { "name": "page", "in": "query", "required": true, "description": "Page number (1-indexed)", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page_size", "in": "query", "required": true, "description": "Number of items per page", "schema": { "type": "integer", "format": "int32" }, "example": 20 }, { "name": "direction", "in": "query", "description": "Optional direction filter: outbound for calls placed from your app, inbound for calls to one of your numbers", "schema": { "type": "string", "nullable": true }, "example": "outbound" }, { "name": "status", "in": "query", "description": "Optional status filter: initiated, ringing, answered, completed, failed, no_answer or rejected", "schema": { "type": "string", "nullable": true }, "example": "COMPLETED" }, { "name": "number", "in": "query", "description": "Optional filter on the number that owns the call, one of your voice-enabled numbers in E.164 format", "schema": { "type": "string", "nullable": true }, "example": "+12025550123" }, { "name": "from", "in": "query", "description": "Only calls started at or after this time (ISO 8601)", "schema": { "type": "string", "format": "date-time", "nullable": true }, "example": "2026-07-22T00:00:00+00:00" }, { "name": "to", "in": "query", "description": "Only calls started at or before this time (ISO 8601)", "schema": { "type": "string", "format": "date-time", "nullable": true }, "example": "2026-07-22T23:59:59+00:00" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Calls retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallsListResponse" }, "example": { "success": true, "data": { "calls": [ { "id": "call_9f2ab000-0000-4000-8000-000000000001", "direction": "outbound", "from": { "kind": "user", "value": "agent-42" }, "to": { "kind": "number", "value": "+12025550142" }, "number": "+12025550123", "status": "COMPLETED", "failure_reason": null, "started_at": "2026-07-22T12:00:00+00:00", "answered_at": "2026-07-22T12:00:05+00:00", "ended_at": "2026-07-22T12:00:47+00:00", "duration_seconds": 42, "price": null, "recording_available": false, "timeline": null } ], "pagination": { "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1, "has_more": false, "cursors": null } }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9964169+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid paging, filter value, number, or time window", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "status": [ "'status' must be one of: INITIATED, RINGING, ANSWERED, COMPLETED, FAILED, NO_ANSWER, REJECTED" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9964235+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving calls", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9964239+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/calls/{id}/hangup": { "post": { "tags": [ "Voice" ], "summary": "Hang up a call", "description": "Ends one of your live calls. The call then ends the way any other call does once the disconnect is reported: an answered call as COMPLETED with call.completed, a call still ringing as NO_ANSWER, REJECTED or FAILED with call.failed. A call that has already ended answers 409, and so does a call with no phone leg, such as one between two app users.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsHangupCallEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "HangupCallRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsRequestsHangupCallRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "The call is being ended", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "The id is not a call id", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No call with this id belongs to your account", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_015", "message": "Call not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9983718+00:00", "version": "v3" } } } } }, "409": { "description": "The call has already ended, or has no phone leg", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_008", "message": "Call is no longer active", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9983729+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while hanging up the call", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9983733+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/calls/{id}/participants/{participantId}": { "patch": { "tags": [ "Voice" ], "summary": "Update a participant", "description": "Mutes or unmutes one participant of the conference room a live call is in, named by the participant's own call id from the participants list: send muted true to silence them, muted false to let them be heard again. Muting a participant who is already muted succeeds, as does unmuting one who is not. A participant who is not in this call's room answers 404. A call that has ended answers 409, as does a call that is not in a conference.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsPatchCallParticipantEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "participantId", "in": "path", "required": true, "description": "The participant's own call id from the route, as listed by the participants endpoint, for example call_9f2ab000-0000-4000-8000-000000000002", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000002" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "PatchCallParticipantRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsRequestsPatchCallParticipantRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "The participant is now muted or unmuted", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "An id is not a call id, or muted is missing", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Request validation failed", "details": { "muted": [ "'muted' is required" ] }, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.999737+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No call with this id belongs to your account, or the participant is not in its room", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_017", "message": "Participant not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9997381+00:00", "version": "v3" } } } } }, "409": { "description": "The call has already ended, or is not in a conference", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_009", "message": "Call is not in a conference", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9997384+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while changing the participant", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:18.9997388+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] }, "delete": { "tags": [ "Voice" ], "summary": "Remove a participant from a call", "description": "Removes one participant from the conference room a live call is in, named by the participant's own call id from the participants list. Their leg ends and is reported through call.completed like any other call; everyone else stays connected. A participant who is not in this call's room answers 404. A call that has ended answers 409, as does a call that is not in a conference.", "operationId": "SentDmServicesEndpointsCustomerAPIv3CallsRemoveCallParticipantEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call id from the route, as carried by call webhooks and the calls list, for example call_9f2ab000-0000-4000-8000-000000000001", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000001" }, { "name": "participantId", "in": "path", "required": true, "description": "The participant's own call id from the route, as listed by the participants endpoint, for example call_9f2ab000-0000-4000-8000-000000000002", "schema": { "type": "string" }, "example": "call_9f2ab000-0000-4000-8000-000000000002" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "RemoveCallParticipantRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsRequestsRemoveCallParticipantRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "The participant has been removed from the room", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "An id is not a call id", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid API credentials", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "No call with this id belongs to your account, or the participant is not in its room", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_017", "message": "Participant not found", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0022817+00:00", "version": "v3" } } } } }, "409": { "description": "The call has already ended, or is not in a conference", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT_009", "message": "Call is not in a conference", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0022829+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while removing the participant", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0022838+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/profiles/{profileId}/campaigns": { "post": { "tags": [ "Profiles" ], "summary": "Create a campaign for a profile's brand", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nCreates a new campaign scoped under the brand of the specified profile. Each campaign must include at least one use case with sample messages.", "operationId": "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsCreateBrandCampaignEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "CreateBrandCampaignRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCreateBrandCampaignRequest" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Campaign created successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfBrandCampaignV3Response" }, "example": { "success": true, "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "customerId": "00000000-0000-0000-0000-000000000000", "type": "App", "name": "Customer Notifications", "description": "Appointment reminders and account notifications", "brandId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": null, "tcrCampaignId": null, "submittedToTCR": false, "submittedAt": null, "cost": null, "billedDate": null, "messageFlow": "User signs up on website and opts in to receive SMS notifications", "volume": null, "privacyPolicyLink": null, "termsAndConditionsLink": null, "optinMessage": null, "optoutMessage": null, "helpMessage": null, "optinKeywords": null, "optoutKeywords": null, "helpKeywords": null, "dcaElectionsComplete": null, "dcaElectionsCompletedAt": null, "tcrSyncError": null, "hasSubmissionTransaction": false, "useCases": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "campaignId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "customerId": "00000000-0000-0000-0000-000000000000", "messagingUseCaseUs": "ACCOUNT_NOTIFICATION", "sampleMessages": [ "Hi {name}, your appointment is confirmed for {date} at {time}.", "Your order #{order_id} has been shipped. Track at {url}" ], "createdAt": "0001-01-01T00:00:00+00:00", "updatedAt": null } ], "createdAt": "2026-10-06T14:45:19.0063423+00:00", "updatedAt": null }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0064047+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request - validation errors or inherit_tcr_campaign=true", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Cannot create campaigns when inherit_tcr_campaign=true. Set inherit_tcr_campaign=false to create your own campaigns.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.006407+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Valid API key required", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile or brand not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_009", "message": "Brand not found for this profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0064074+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error occurred", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to create campaign. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0064078+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] }, "get": { "tags": [ "Profiles" ], "summary": "Get campaigns for a profile's brand", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nRetrieves all campaigns linked to the profile's brand, including use cases and sample messages. Returns inherited campaigns if inherit_tcr_campaign=true.", "operationId": "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsGetBrandCampaignsEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaigns retrieved successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfBrandCampaignV3Response" }, "example": { "success": true, "data": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "customerId": "00000000-0000-0000-0000-000000000000", "type": "App", "name": "Customer Notifications", "description": "Appointment reminders and account notifications", "brandId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": null, "tcrCampaignId": null, "submittedToTCR": false, "submittedAt": null, "cost": null, "billedDate": null, "messageFlow": "User signs up on website and opts in to receive SMS notifications", "volume": null, "privacyPolicyLink": null, "termsAndConditionsLink": null, "optinMessage": null, "optoutMessage": null, "helpMessage": null, "optinKeywords": null, "optoutKeywords": null, "helpKeywords": null, "dcaElectionsComplete": null, "dcaElectionsCompletedAt": null, "tcrSyncError": null, "hasSubmissionTransaction": false, "useCases": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "campaignId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "customerId": "00000000-0000-0000-0000-000000000000", "messagingUseCaseUs": "ACCOUNT_NOTIFICATION", "sampleMessages": [ "Hi {name}, your appointment is confirmed for {date} at {time}.", "Your order #{order_id} has been shipped. Track at {url}" ], "createdAt": "0001-01-01T00:00:00+00:00", "updatedAt": null } ], "createdAt": "2026-10-06T14:45:19.0535289+00:00", "updatedAt": null } ], "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0535303+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Valid API key required", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile or brand not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_009", "message": "Brand not found for this profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0535328+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error occurred", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to retrieve campaigns. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0535338+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/profiles/{profileId}/campaigns/{campaignId}": { "delete": { "tags": [ "Profiles" ], "summary": "Delete a campaign", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nDeletes a campaign by ID from the brand of the specified profile. The profile must belong to the authenticated organization.", "operationId": "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsDeleteBrandCampaignEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "campaignId", "in": "path", "required": true, "description": "Campaign ID from route parameter", "schema": { "type": "string", "format": "uuid" }, "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "DeleteBrandCampaignRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsDeleteBrandCampaignRequest" } } }, "required": true, "x-position": 1 }, "responses": { "204": { "description": "Campaign deleted successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid profile or campaign ID format", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "Invalid profile or campaign ID format", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0078215+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Valid API key required", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile, brand, or campaign not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_010", "message": "Campaign not found for this profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0078226+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error occurred", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to delete campaign. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.007823+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] }, "put": { "tags": [ "Profiles" ], "summary": "Update a campaign", "description": "**Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be removed in a future release. It still behaves exactly as before, so nothing needs to change today — but new integrations should use `/v3/sender-profiles`, which models a profile's markets, compliance, brand, campaigns and billing explicitly.\n\nUpdates an existing campaign under the brand of the specified profile. Cannot update campaigns that have already been submitted to TCR.", "operationId": "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsUpdateBrandCampaignEndpoint", "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Profile ID from route", "schema": { "type": "string", "format": "uuid" }, "example": "770e8400-e29b-41d4-a716-446655440002" }, { "name": "campaignId", "in": "path", "required": true, "description": "Campaign ID from route", "schema": { "type": "string", "format": "uuid" }, "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.", "schema": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$" }, "example": "req_abc123_retry1" }, { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "x-name": "UpdateBrandCampaignRequest", "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsUpdateBrandCampaignRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Campaign updated successfully", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfBrandCampaignV3Response" }, "example": { "success": true, "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "customerId": "00000000-0000-0000-0000-000000000000", "type": "App", "name": "Customer Notifications Updated", "description": "Updated appointment reminders and account notifications", "brandId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": null, "tcrCampaignId": null, "submittedToTCR": false, "submittedAt": null, "cost": null, "billedDate": null, "messageFlow": null, "volume": null, "privacyPolicyLink": null, "termsAndConditionsLink": null, "optinMessage": null, "optoutMessage": null, "helpMessage": null, "optinKeywords": null, "optoutKeywords": null, "helpKeywords": null, "dcaElectionsComplete": null, "dcaElectionsCompletedAt": null, "tcrSyncError": null, "hasSubmissionTransaction": false, "useCases": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "campaignId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "customerId": "00000000-0000-0000-0000-000000000000", "messagingUseCaseUs": "ACCOUNT_NOTIFICATION", "sampleMessages": [ "Hi {name}, your appointment is confirmed for {date} at {time}.", "Your order #{order_id} has been shipped. Track at {url}" ], "createdAt": "0001-01-01T00:00:00+00:00", "updatedAt": null } ], "createdAt": "2026-09-29T14:45:19.0553521+00:00", "updatedAt": "2026-10-06T14:45:19.0553535+00:00" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0553669+00:00", "version": "v3" } } } } }, "400": { "description": "Invalid request - validation errors or inherit_tcr_campaign=true", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_001", "message": "These campaigns are read-only. Set inherit_tcr_campaign to false to manage your own campaigns.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.055369+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Valid API key required", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Profile, brand, or campaign not found", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RESOURCE_010", "message": "Campaign not found for this profile", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0553693+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error occurred", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "Failed to update campaign. Please contact support with request ID: req_7X9zKp2jDw", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0553697+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "deprecated": true, "security": [ { "CustomerApiKey": [] } ] } }, "/v3/me": { "get": { "tags": [ "Accounts" ], "summary": "Get authenticated account", "description": "Returns the account associated with the provided API key. The response includes account identity, contact information, messaging channel configuration, and — depending on the account type — either a list of child profiles or the profile's own settings.\n\n**Account types:**\n- `organization` — Has child profiles. The `profiles` array is populated.\n- `user` — Standalone account with no profiles.\n- `profile` — Child of an organization. Includes `organization_id`, `short_name`, `status`, and `settings`.\n\n**Channels:**\nThe `channels` object always includes `sms`, `whatsapp`, and `rcs`. Each channel has a `configured` boolean. Configured channels expose additional details such as `phone_number`.\n\n**Sending number:**\n`sending_phone_number` is the account's US SMS sender. It is intentionally the same value as `channels.sms.phone_number` — the two are kept in step, and it is published under both names because `sending_phone_number` is what this value is called on `GET /v3/profiles`. Read either. One difference: `sending_phone_number` is always present, including as `null`, while `channels.sms.phone_number` is omitted when there is no sender.\n\n`sending_phone_number_profile_id` names the account that holds that number in inventory — normally this account, and a different one where a number is shared. Both are `null` when the account has no US SMS sender.\n\n**Template auto-creation:**\n`enable_template_auto_creation_for_sp` reports whether this account may mark a template for automatic creation on its sender profiles. It is granted by Sent and off by default. A `profile` reports `false`, having no sender profiles of its own to create anything on.", "operationId": "SentDmServicesEndpointsCustomerAPIv3AccountGetAccountEndpoint", "parameters": [ { "name": "x-profile-id", "in": "header", "description": "Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Account retrieved successfully. Response shape varies by account type (organization, user, or profile).", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfAccountResponse" }, "example": { "success": true, "data": { "type": "profile", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organization_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "name": "Marketing", "short_name": "MKT", "email": "marketing@acme.com", "icon": "https://cdn.sent.dm/icons/marketing.png", "description": "Marketing department sender profile", "created_at": "2025-01-20T14:00:00+00:00", "channels": { "sms": { "configured": true, "phone_number": "+14155550100" }, "whatsapp": { "configured": true, "phone_number": "+14155550100", "business_name": "Acme Corporation" }, "rcs": { "configured": false, "phone_number": "+14155550100" } }, "sending_phone_number": "+14155550100", "sending_phone_number_profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "approved", "enable_template_auto_creation_for_sp": false, "settings": { "allow_contact_sharing": false, "allow_template_sharing": false, "inherit_contacts": false, "inherit_templates": false, "inherit_tcr_brand": true, "inherit_tcr_campaign": false, "billing_model": "organization" }, "profiles": [] }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0580946+00:00", "version": "v3" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "AUTH_001", "message": "Invalid or missing API key. Ensure the x-api-key header is set with a valid key.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/authentication" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0580971+00:00", "version": "v3" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_001", "message": "An unexpected error occurred while retrieving account information. Please try again later.", "details": null, "doc_url": "https://docs.sent.dm/reference/api/error-catalog" }, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-10-06T14:45:19.0580977+00:00", "version": "v3" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "Unique request identifier for support and debugging", "schema": { "type": "string" } }, "X-Response-Time": { "description": "Server processing time (e.g. \"12ms\")", "schema": { "type": "string" } }, "X-API-Version": { "description": "API version (always \"v3\")", "schema": { "type": "string" } }, "X-Profile-Id": { "description": "Echoed profile UUID when the request is profile-scoped via `x-profile-id`", "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "CustomerApiKey": [] } ] } } }, "components": { "schemas": { "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookV3Response": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "description": "Which customer owns this — the key's own, or the profile named in x-profile-id. Says whose\nresource this is, which the resource's own id does not.", "format": "uuid" }, "display_name": { "type": "string" }, "endpoint_url": { "type": "string" }, "signing_secret": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "event_types": { "type": "array", "items": { "type": "string" } }, "event_filters": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "retry_count": { "type": "integer", "format": "int32" }, "timeout_seconds": { "type": "integer", "format": "int32" }, "last_delivery_attempt_at": { "type": "string", "format": "date-time", "nullable": true }, "last_successful_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "consecutive_failures": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3SharedApiError": { "type": "object", "description": "Error information", "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g., \"RESOURCE_001\")" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Additional validation error details (field-level errors)", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "doc_url": { "type": "string", "description": "URL to documentation about this error", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3SharedApiMeta": { "type": "object", "description": "Request and response metadata", "additionalProperties": false, "properties": { "request_id": { "type": "string", "description": "Unique identifier for this request (for tracing and support)" }, "timestamp": { "type": "string", "description": "Server timestamp when the response was generated", "format": "date-time" }, "version": { "type": "string", "description": "API version used for this request" } } }, "SentDmServicesEndpointsCustomerAPIv3SharedApiErrorResponse": { "type": "object", "description": "Standard error response envelope (non-generic, used for error response documentation)", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Always false for error responses" }, "error": { "type": "object", "description": "Error details", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsCreateWebhookV3Request": { "type": "object", "example": { "display_name": "Order Notifications", "endpoint_url": "https://example.com/webhooks/orders", "event_types": [ "contact", "message", "templates" ], "event_filters": { "message": [ "delivered", "failed" ], "templates": [ "approved", "rejected" ] }, "retry_count": 3, "timeout_seconds": 30, "sandbox": false }, "required": [ "display_name" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsCreateWebhookV3Request_Properties", "type": "object", "additionalProperties": false, "properties": { "display_name": { "type": "string", "maxLength": 255, "minLength": 0, "nullable": false, "example": "Order Notifications" }, "endpoint_url": { "type": "string", "example": "https://example.com/webhooks/orders" }, "event_types": { "type": "array", "example": [ "contact", "message", "templates" ], "items": { "type": "string" } }, "event_filters": { "type": "object", "nullable": true, "example": { "message": [ "delivered", "failed" ], "templates": [ "approved", "rejected" ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "sender_profile": { "type": "object", "description": "Clones this webhook onto every existing and future sender profile, with the same URL and signing\nsecret, receiving these events. Only an organization's webhook can set it.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsWebhookSenderProfileV3Config" } ] }, "retry_count": { "type": "integer", "format": "int32", "maximum": 5.0, "minimum": 1.0, "example": 3 }, "timeout_seconds": { "type": "integer", "format": "int32", "maximum": 120.0, "minimum": 5.0, "example": 30 } } } ] }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsWebhookSenderProfileV3Config": { "type": "object", "description": "Request-only: the events an organization webhook's sender profile clones receive, one clone per existing\nand future profile. Responses never return it.", "additionalProperties": false, "properties": { "event_types": { "type": "array", "items": { "type": "string" } }, "event_filters": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" }, { "title": "SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase_Properties", "type": "object", "description": "Base request for mutation operations (POST, PUT, PATCH) with sandbox mode support", "additionalProperties": false, "properties": { "sandbox": { "type": "boolean", "description": "Sandbox flag - when true, the operation is simulated without side effects\nUseful for testing integrations without actual execution", "example": false } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest": { "type": "object", "description": "Base request with authentication headers for v3 API", "additionalProperties": false }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsDeleteWebhookV3Request": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsGetWebhookV3Request": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookEventsListV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventsListV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventsListV3Response": { "type": "object", "description": "A paginated list of webhook delivery records.", "additionalProperties": false, "properties": { "events": { "type": "array", "description": "The events on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventV3Response" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventV3Response": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "event_data": { "description": "The exact event body that was delivered, or attempted, for this record. One of the six\nwebhook envelopes:\n \nmessage — an outbound message changed status.\nmessage with event: message.received — someone replied to you.\ntemplates — a template was approved, rejected, paused or similar.\nchannel — one of your markets moved in provisioning or compliance.\ncontact — a consent signal: opt-in, opt-out or help.\nlink — a tracked short link was clicked or a hosted file downloaded, or one\n expired or was revoked.\n \nRead field and event to tell which, the same way your endpoint does.\nThe two message envelopes are the reason that is two fields and not one: they share\na field and differ by event.\n \nTreat the list as open. It has grown twice — channel and then link —\nand a handler that rejects an envelope it does not recognise will break on the next\naddition rather than ignore it.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsWebhookEventOfMessageWebhookPayload" }, { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsWebhookEventOfInboundMessageWebhookPayload" }, { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsWebhookEventOfTemplateWebhookPayload" }, { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsWebhookEventOfChannelWebhookPayload" }, { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsWebhookEventOfContactWebhookPayload" }, { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload" }, { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload" } ] }, "delivery_status": { "type": "string" }, "http_status_code": { "type": "integer", "format": "int32", "nullable": true }, "response_body": { "type": "string", "nullable": true }, "delivery_attempts": { "type": "integer", "format": "int32" }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "processing_started_at": { "type": "string", "format": "date-time", "nullable": true }, "processing_completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "SystemTextJsonJsonElement": { "type": "object" }, "SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta": { "type": "object", "description": "Pagination metadata for list responses", "additionalProperties": false, "properties": { "page": { "type": "integer", "description": "Current page number (1-indexed)", "format": "int32" }, "page_size": { "type": "integer", "description": "Number of items per page", "format": "int32" }, "total_count": { "type": "integer", "description": "Total number of items across all pages", "format": "int32" }, "total_pages": { "type": "integer", "description": "Total number of pages", "format": "int32" }, "has_more": { "type": "boolean", "description": "Whether there are more pages after this one" }, "cursors": { "type": "object", "description": "Always null. v3 pages by page and page_size; no endpoint has ever produced a\ncursor, so nothing was ever populated here.\n \nRetained because every paginated v3 response published \"cursors\": null, and a field going\nfrom null to absent is the kind of difference that is invisible until some client's schema\nvalidation is stricter than ours. It is deprecated rather than removed so that stops being true on a\ndate somebody chooses.", "deprecated": true, "x-deprecatedMessage": "Always null. v3 paginates by page/page_size and has never emitted a cursor.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationCursors" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3SharedPaginationCursors": { "type": "object", "description": "Cursor-based pagination. Never populated — see Cursors.", "deprecated": true, "x-deprecatedMessage": "Never populated. v3 paginates by page/page_size.", "additionalProperties": false, "properties": { "after": { "type": "string", "description": "Cursor to fetch the next page.", "nullable": true }, "before": { "type": "string", "description": "Cursor to fetch the previous page.", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsGetWebhookEventsV3Request": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhookEventTypesListV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventTypesListV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventTypesListV3Response": { "type": "object", "description": "The webhook event types a customer can subscribe to.", "additionalProperties": false, "properties": { "event_types": { "type": "array", "description": "The event_types on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventTypeV3Response" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventTypeV3Response": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "event_type": { "type": "string", "nullable": true }, "sub_types": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookEventTypeV3Response" } } } }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWebhooksListV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhooksListV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhooksListV3Response": { "type": "object", "description": "A paginated list of webhooks.", "additionalProperties": false, "properties": { "webhooks": { "type": "array", "description": "The webhooks on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesWebhookV3Response" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsGetWebhooksV3Request": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfRotateSecretV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesRotateSecretV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesRotateSecretV3Response": { "type": "object", "additionalProperties": false, "properties": { "signing_secret": { "type": "string" } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsRotateWebhookSecretV3Request": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTestWebhookV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesTestWebhookV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksResponsesTestWebhookV3Response": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsTestWebhookV3Request": { "type": "object", "example": { "event_type": "message.sent", "sandbox": false }, "required": [ "event_type" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsTestWebhookV3Request_Properties", "type": "object", "additionalProperties": false, "properties": { "event_type": { "type": "string", "minLength": 1, "nullable": false, "example": "message.sent" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsToggleWebhookStatusV3Request": { "type": "object", "example": { "is_active": false, "sandbox": false }, "required": [ "is_active" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsToggleWebhookStatusV3Request_Properties", "type": "object", "additionalProperties": false, "properties": { "is_active": { "type": "boolean", "nullable": false, "example": false } } } ] }, "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsUpdateWebhookV3Request": { "type": "object", "example": { "display_name": "Updated Order Notifications", "endpoint_url": "https://example.com/webhooks/orders-v2", "event_types": [ "contact", "message", "templates" ], "event_filters": { "message": [ "delivered", "failed" ] }, "retry_count": 5, "timeout_seconds": 60, "sandbox": false }, "required": [ "display_name" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsUpdateWebhookV3Request_Properties", "type": "object", "additionalProperties": false, "properties": { "display_name": { "type": "string", "maxLength": 255, "minLength": 0, "nullable": false, "example": "Updated Order Notifications" }, "endpoint_url": { "type": "string", "example": "https://example.com/webhooks/orders-v2" }, "event_types": { "type": "array", "example": [ "contact", "message", "templates" ], "items": { "type": "string" } }, "event_filters": { "type": "object", "nullable": true, "example": { "message": [ "delivered", "failed" ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "sender_profile": { "type": "object", "description": "The sender profile clones. Omit or pass null to keep them; pass an empty event_types list to\ndelete them. Other changes to this webhook are copied onto its clones. At least one event must\nremain across both selections after the update. An empty result returns a V3 validation error.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsWebhookSenderProfileV3Config" } ] }, "retry_count": { "type": "integer", "format": "int32", "maximum": 5.0, "minimum": 1.0, "example": 5 }, "timeout_seconds": { "type": "integer", "format": "int32", "maximum": 120.0, "minimum": 5.0, "example": 60 } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfUserResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersResponsesUserResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3UsersResponsesUserResponse": { "type": "object", "description": "User response for v3 API", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "User unique identifier", "format": "uuid" }, "customer_id": { "type": "string", "description": "Which customer owns this — the key's own, or the profile named in x-profile-id. Says whose\nresource this is, which the resource's own id does not.", "format": "uuid" }, "email": { "type": "string", "description": "User email address" }, "name": { "type": "string", "description": "User full name" }, "role": { "type": "string", "description": "User role in the organization: admin, billing, developer" }, "status": { "type": "string", "description": "User status: active, invited, suspended, rejected" }, "invited_at": { "type": "string", "description": "When the user was invited", "format": "date-time", "nullable": true }, "last_login_at": { "type": "string", "description": "When the user last logged in", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "description": "When the user was added to the organization", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the user record was last updated", "format": "date-time", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3UsersRequestsGetUserRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersRequestsUserBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3UsersRequestsUserBaseRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfUsersListResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersResponsesUsersListResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3UsersResponsesUsersListResponse": { "type": "object", "description": "The users in the organization.", "additionalProperties": false, "properties": { "users": { "type": "array", "description": "The users on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersResponsesUserResponse" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3UsersRequestsGetUsersRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3UsersRequestsUserBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3UsersRequestsInviteUserRequest": { "type": "object", "example": { "email": "newuser@example.com", "name": "New User", "role": "developer", "sandbox": false }, "required": [ "email", "name" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3UsersRequestsInviteUserRequest_Properties", "type": "object", "description": "Request to invite a user to an organization", "additionalProperties": false, "properties": { "email": { "type": "string", "description": "User email address (required)", "format": "email", "minLength": 1, "pattern": "^[^@]+@[^@]+$", "nullable": false, "example": "newuser@example.com" }, "name": { "type": "string", "description": "User full name (required)", "maxLength": 100, "minLength": 0, "nullable": false, "example": "New User" }, "role": { "type": "string", "description": "User role: admin, billing, or developer (required)", "example": "developer" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3UsersRequestsRemoveUserRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3UsersRequestsUpdateUserRequest": { "type": "object", "example": { "role": "billing", "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3UsersRequestsUpdateUserRequest_Properties", "type": "object", "description": "Request to update a user's role", "additionalProperties": false, "properties": { "role": { "type": "string", "description": "User role: admin, billing, or developer (required)", "example": "billing" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTemplateResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3TemplatesResponsesTemplateResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3TemplatesResponsesTemplateResponse": { "type": "object", "description": "Template response for v3 API", "additionalProperties": false, "required": [ "customer_id" ], "properties": { "id": { "type": "string", "description": "Unique template identifier", "format": "uuid" }, "customer_id": { "type": "string", "description": "Which customer owns this — the key's own, or the profile named in x-profile-id. Says whose\nresource this is, which the resource's own id does not.", "format": "uuid" }, "name": { "type": "string", "description": "Template display name" }, "category": { "type": "string", "description": "Template category: MARKETING, UTILITY, AUTHENTICATION" }, "auto_reply_action": { "type": "string", "description": "Which consent keyword this template answers, when it is one of Sent's auto-replies:\nOPT_IN, OPT_OUT, HELP, or OTHER for a customer-defined keyword.\nNull for an ordinary template, and omitted from the response, so its presence is the answer to\n\"is this an auto-reply\".\n \nDeliberately not required, unlike CustomerId, even though the\nsame \"no single mapper\" argument applies: NJsonSchema publishes a C# required member in the\nschema's required array, so the contract would have advertised a field this response omits\nfor every ordinary template, and a generated client could refuse the common case. A compile-time\nguard is not worth a wrong published contract. Every mapping site sets it explicitly, and\nTemplateResponseSchemaTests pins the field as optional so it cannot be reintroduced.", "nullable": true }, "language": { "type": "string", "description": "Template language code (e.g., en_US)" }, "status": { "type": "string", "description": "Template status: DRAFT, PENDING, APPROVED, REJECTED. A template created with\nsubmit_for_review: false starts as DRAFT and stays there until it is submitted." }, "channels": { "type": "array", "description": "The channels this template's definition can render on, in canonical order: sms,\nwhatsapp, rcs.\n \nDerived from the definition's body, mirroring each channel's send-time fallback chain, so a\nchannel is listed only when a real body would be produced for it: SMS reads\nsms ?? multiChannel, WhatsApp reads whatsapp ?? multiChannel, and RCS reads\nrcs ?? multiChannel ?? sms. A multiChannel body therefore reports all three, and\nthe extra SMS fallback on RCS is why an sms/whatsapp pair reports RCS too.\n \nThis says what the content can render on, not what may be sent: sending also needs the\ntemplate approved for that channel.", "nullable": true, "items": { "type": "string" } }, "variables": { "type": "array", "description": "Template variables for personalization", "nullable": true, "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the template was created", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the template was last updated", "format": "date-time", "nullable": true }, "is_published": { "type": "boolean", "description": "Whether the template is published and active" } } }, "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsCreateTemplateRequest": { "type": "object", "example": { "category": "MARKETING", "language": "en_US", "definition": { "body": { "multiChannel": { "type": "text", "template": "Hello {{0:variable}}! Welcome to {{1:variable}}. We are glad to have you on board.", "variables": [ { "id": 0, "name": "name", "type": "variable", "props": { "variableType": "text", "sample": "John" } }, { "id": 1, "name": "company", "type": "variable", "props": { "variableType": "text", "sample": "SentDM" } } ] } }, "definitionVersion": "1.0" }, "auto_create_for_sp": false, "submit_for_review": false, "sandbox": false }, "required": [ "definition" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsCreateTemplateRequest_Properties", "type": "object", "description": "Request to create a new template", "additionalProperties": false, "properties": { "category": { "type": "string", "description": "Template category: MARKETING, UTILITY, AUTHENTICATION (optional, auto-detected if not provided)", "nullable": true, "example": "MARKETING" }, "language": { "type": "string", "description": "Template language code (e.g., en_US) (optional, auto-detected if not provided)", "nullable": true, "example": "en_US" }, "definition": { "description": "Template definition including header, body, footer, and buttons", "nullable": false, "example": { "body": { "multiChannel": { "type": "text", "template": "Hello {{0:variable}}! Welcome to {{1:variable}}. We are glad to have you on board.", "variables": [ { "id": 0, "name": "name", "type": "variable", "props": { "variableType": "text", "sample": "John" } }, { "id": 1, "name": "company", "type": "variable", "props": { "variableType": "text", "sample": "SentDM" } } ] } }, "definitionVersion": "1.0" }, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateDefinition" } ] }, "creation_source": { "type": "string", "description": "Source of template creation (default: from-api)", "nullable": true, "example": null }, "auto_create_for_sp": { "type": "boolean", "description": "Create this template automatically on every sender profile of the organization, now and in future\n(default: false). Accepted only from an organization that has been enabled for it, and only at\ncreation — it cannot be changed afterwards.", "example": false }, "submit_for_review": { "type": "boolean", "description": "Whether to submit the template for review after creation (default: false)", "example": false } } } ] }, "SentDmServicesCommonEntitiesTemplateDefinition": { "type": "object", "description": "Complete definition of a message template including header, body, footer, and buttons", "additionalProperties": false, "required": [ "body" ], "properties": { "header": { "type": "object", "description": "Optional template header with optional variables", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateHeader" } ] }, "body": { "description": "Required template body with content for different channels (multi-channel, SMS-specific, or WhatsApp-specific)", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateBody" } ] }, "footer": { "type": "object", "description": "Optional template footer with optional variables", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateFooter" } ] }, "buttons": { "type": "array", "description": "Optional list of interactive buttons (e.g., quick replies, URLs, phone numbers)", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateButton" } }, "definitionVersion": { "type": "string", "description": "The version of the template definition format", "nullable": true }, "authenticationConfig": { "type": "object", "description": "Configuration specific to AUTHENTICATION category templates (optional)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesAuthenticationConfig" } ] } } }, "SentDmServicesCommonEntitiesTemplateHeader": { "type": "object", "description": "Header section of a message template", "additionalProperties": false, "required": [ "template" ], "properties": { "type": { "type": "string", "description": "The kind of header. One of:\n \ntext — up to 60 characters, at most one variable.\nimage — png, jpg or jpeg. Needs ExampleUrl.\nvideo — mp4. Needs ExampleUrl.\ngif — mp4, max 3.5MB. WhatsApp renders larger files as an ordinary video. Needs\nExampleUrl.\ndocument — pdf or docx; only the first page is shown as a thumbnail, so pdf is the\npractical choice. Needs ExampleUrl.\nlocation — a map pin, supplied through Location.\n \nKept lowercase because MetaToTemplateConverter writes Meta's format\nthrough ToLowerInvariant() into this field on import, and the two are compared directly.", "nullable": true }, "template": { "type": "string", "description": "The header template text with optional variable placeholders (e.g., \"Welcome to {{0:variable}}\")", "maxLength": 60, "minLength": 0, "nullable": false }, "variables": { "type": "array", "description": "List of variables used in the header template", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateVariable" } }, "example_url": { "type": "string", "description": "Request-only. The s.dm URL of the asset Meta's reviewers see — https://s.dm/s/{ID}, eight\nuppercase characters, uploaded to s.dm out of band. NormalizeRichHeader\nfolds it into the synthesized media variable's Props.Sample and clears it, so it never persists\nand a stored definition is indistinguishable from an imported one.\n \nStricter than the send path on purpose: TemplateUtils.ValidateMediaVariableValues accepts\nany absolute https URL for the per-send asset, because that one is the customer's and may live behind\na signed CDN link. This one is the review sample, has to outlive every resubmission, and so must be\nours. Do not \"fix\" one to match the other.", "nullable": true }, "static_resource": { "type": "boolean", "description": "Whether the asset registered at creation is reused when a caller omits the header's variable at send\ntime. Default false — the caller must supply it per message, which is the behaviour every\nexisting template has. Written only when true, so a default-valued header serializes byte-identically\nto one imported from Meta.\n \nStored and validated but not yet honoured at send: that lands with the Resumable Upload work,\nalongside the code that lets such a template be approved in the first place." }, "location": { "type": "object", "description": "Request-only, location headers only. Normalized into the four reserved\nLocationVariableNames variables and cleared, for the same reason\nas ExampleUrl.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateHeaderLocation" } ] } } }, "SentDmServicesCommonEntitiesTemplateVariable": { "type": "object", "additionalProperties": false, "required": [ "name", "type", "props" ], "properties": { "id": { "type": "integer", "description": "The variable's index, and the number its {{index:variable}} placeholder refers to.\n \nOmitting it is only safe for a section holding a single variable. The field is a\nnon-nullable int, so every variable that leaves it out defaults to 0, and a section with two\nsuch variables is refused by the unique-id rule (\"variables must have unique IDs\"). Number\nthem from 0 in the order they appear.", "format": "int32" }, "name": { "type": "string", "description": "The variable's name, and the key callers use for it in a send request's parameters object.\nMust start with a letter and hold only letters, digits and underscores.", "minLength": 1, "nullable": false }, "type": { "type": "string", "description": "One of variable, link or media. Decides which Props fields\nare required.", "minLength": 1, "nullable": false }, "props": { "nullable": false, "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateVariableProps" } } }, "SentDmServicesCommonEntitiesTemplateVariableProps": { "type": "object", "additionalProperties": false, "required": [ "variableType", "sample", "url", "mediaType" ], "properties": { "variableType": { "type": "string", "minLength": 1, "nullable": false }, "sample": { "type": "string", "description": "Example value substituted into the template when previewing it and when submitting it to\nMeta for review. Free text by nature, so the converter accepts a JSON number or boolean here\nand normalizes it — see JsonScalarToStringConverter for why — and guarantees it\nis always serialized back out as a JSON string.", "minLength": 1, "nullable": false }, "regex": { "type": "string", "nullable": true }, "url": { "type": "string", "minLength": 1, "nullable": false }, "shortUrl": { "type": "string", "nullable": true }, "alt": { "type": "string", "nullable": true }, "mediaType": { "type": "string", "minLength": 1, "nullable": false } } }, "SentDmServicesCommonEntitiesTemplateHeaderLocation": { "type": "object", "description": "The map pin a location header drops. Meta wants none of this at creation — the component is just\n{\"type\":\"header\",\"format\":\"location\"} — so these values exist for Sent: a preview, and the\ndefault a StaticResource header falls back to at send.", "additionalProperties": false, "required": [ "latitude", "longitude", "name", "address" ], "properties": { "latitude": { "type": "string", "minLength": 1, "nullable": false }, "longitude": { "type": "string", "minLength": 1, "nullable": false }, "name": { "type": "string", "minLength": 1, "nullable": false }, "address": { "type": "string", "minLength": 1, "nullable": false } } }, "SentDmServicesCommonEntitiesTemplateBody": { "type": "object", "description": "Body section of a message template.\n \nA body picks one of two authoring strategies, and mixing them is refused\n(TemplateDefinitionValidator.HaveValidChannelConfiguration):\na shared multiChannel body on its own, or\nan explicit sms + whatsapp pair, both present.\n \nmultiChannel together with sms or whatsapp is rejected, and so is\nsms or whatsapp on its own — every template is expected to be deliverable on every\nchannel. rcs is the one true override: it may accompany either strategy to vary the copy,\nbut cannot stand alone.", "additionalProperties": false, "properties": { "multiChannel": { "type": "object", "description": "The shared body, used for every channel. One half of the choice described above.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateBodyContent" } ] }, "sms": { "type": "object", "description": "The SMS body. It does not override multiChannel, it replaces it.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateBodyContent" } ] }, "whatsapp": { "type": "object", "description": "The WhatsApp body. It does not override multiChannel, it replaces it.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateBodyContent" } ] }, "rcs": { "type": "object", "description": "RCS-specific copy that overrides the chosen strategy for RCS only. The one true override:\noptional on top of either strategy, but it cannot be the only body present. Its length cap is\nthe higher one described on Template.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateBodyContent" } ] }, "mms": { "type": "object", "description": "MMS-specific content — subject, text and attachments.\n \nLike Rcs, an override that cannot stand on its own: a template still needs a\nMultiChannel body or the Sms + Whatsapp pair to be\ndeliverable at all. Unlike Rcs, it has no fallback at send time — MMS with no\nmedia is a more expensive SMS, so a template without this slot is deliberately not MMS-capable\nand never produces an MMS route candidate.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateMmsBodyContent" } ] } } }, "SentDmServicesCommonEntitiesTemplateBodyContent": { "type": "object", "additionalProperties": false, "required": [ "template" ], "properties": { "type": { "type": "string", "description": "The type of body content — send \"text\". It is dropped from the stored definition when null,\nso a body posted without it is saved with no type key at all and the template editor has\nnothing to render the block from.", "nullable": true }, "template": { "type": "string", "description": "The body copy, with variables written as {{index:variable}}.\n \nLength cap depends on which channel this body belongs to:\nTemplateContentLimits.MaxBodyLength (1024) for multiChannel, sms and\nwhatsapp — Meta's BODY limit, which a multiChannel body may be delivered under —\nand TemplateContentLimits.MaxRcsBodyLength (3072) for an rcs body, which never\nreaches Meta. The maxLength advertised on this schema is the 1024 one, because all four\nchannel bodies share this single schema — an rcs body between the two is accepted.\n \nMeta requires every variable to carry surrounding context, so a body is refused unless it also\nsatisfies all of the following (enforced by TemplateDefinitionValidator):\nAt least one letter before the first variable and after the last — trailing punctuation\nsuch as \"... {{1:variable}}.\" does not count.\nAt least (2 × variable count) + 1 words once the placeholders are removed.\nNo two variables adjacent with only whitespace between them.\nNo leading or trailing newline, no more than two consecutive line breaks, and no more than\nfour consecutive spaces.\n \nExample: \"Hello {{0:variable}}! Welcome to {{1:variable}}. We are glad to have you on\nboard.\" — two variables, so at least five words are required, and the copy after the final\nvariable contains letters.", "maxLength": 1600, "minLength": 0, "nullable": false }, "variables": { "type": "array", "description": "The variables referenced by the body copy, one entry per {{index:variable}} placeholder.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateVariable" } } } }, "SentDmServicesCommonEntitiesTemplateMmsBodyContent": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateBodyContent" }, { "title": "SentDmServicesCommonEntitiesTemplateMmsBodyContent_Properties", "type": "object", "description": "MMS-specific body content.\n \nWhy MMS needs its own type when the other channels share one: it is the only channel\nwith a subject line and the only one with attachments. Every other channel's body is text and\nvariables, which is exactly what TemplateBodyContent already is. Putting\nSubject and Media on the shared type instead would give sms, whatsapp and rcs two\nmembers none of them can ever use.\n \nDerives from TemplateBodyContent so that every existing consumer of a body slot —\nMessageUtils.ConvertVariableToReadable, TemplateDefinition.GetRequiredVariables,\nTemplateDefinitionValidator.ApplyBodyContentRules — reads it with no change. The two extra\nmembers are what the MMS strategy and the provider request need on top.", "additionalProperties": false, "properties": { "subject": { "type": "string", "description": "MMS subject line. Optional — most handsets render it above the body, some ignore it entirely.\nDeliberately its own field rather than riding TemplateHeader: the header is authored once\nand shared across every channel, and carries Meta's 60-character cap plus its no-newline,\nno-emoji text rules, none of which describe an MMS subject.", "maxLength": 80, "minLength": 0, "nullable": true }, "media": { "type": "array", "description": "Attachments carried by every send on this template, in order. A per-send media_urls on the\nrequest replaces this list rather than adding to it, so a template can hold a default creative and\na caller can still send something recipient-specific.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateMediaItem" } } } } ] }, "SentDmServicesCommonEntitiesTemplateMediaItem": { "type": "object", "description": "One attachment on an MMS template body.", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "Publicly fetchable https URL. The carrier's MMSC fetches this at send time, so it has to\n stay reachable and unauthenticated for the life of the send — including retries and a DLQ\n replay — which is why a presigned URL is not a valid value here." }, "mediaType": { "type": "string", "description": "One of MmsMediaTypes. Advisory: the carrier reads the Content-Type off the\n fetched object, not this field. It exists so an authoring UI can render the right preview and so a\n reviewer can see what was intended.", "nullable": true } } }, "SentDmServicesCommonEntitiesTemplateFooter": { "type": "object", "description": "Footer section of a message template", "additionalProperties": false, "required": [ "template" ], "properties": { "type": { "type": "string", "description": "The type of footer (typically \"text\")", "nullable": true }, "template": { "type": "string", "description": "The footer template text with optional variable placeholders", "maxLength": 60, "minLength": 0, "nullable": false }, "variables": { "type": "array", "description": "List of variables used in the footer template", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateVariable" } } } }, "SentDmServicesCommonEntitiesTemplateButton": { "type": "object", "description": "Interactive button in a message template", "additionalProperties": false, "required": [ "type", "props" ], "properties": { "id": { "type": "integer", "description": "The button's identifier (1-based index), unique within the template.\n \nOmitting it is only safe for a template holding a single button. The field is a\nnon-nullable int, so every button that leaves it out defaults to 0, and two such buttons are\nrefused by the unique-id rule (\"Button IDs must be unique\"). Number them from 1 in the order\nthey should appear — order matters on RCS, where only the first four buttons render.", "format": "int32" }, "type": { "type": "string", "description": "The type of button (e.g., QUICK_REPLY, URL, PHONE_NUMBER, VOICE_CALL, COPY_CODE)", "minLength": 1, "nullable": false }, "props": { "description": "Properties specific to the button type", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateButtonProps" } ] } } }, "SentDmServicesCommonEntitiesTemplateButtonProps": { "type": "object", "additionalProperties": false, "required": [ "text", "quickReplyType", "urlType", "url", "variables", "activeFor", "countryCode", "phoneNumber", "offerCode" ], "properties": { "text": { "type": "string", "description": "The button's label. Required for every button type, and capped at\nTemplateContentLimits.MaxButtonTextLength (25) characters.\n \nMeta accepts only static text here, so a label is refused when it contains a\n{{...}} variable placeholder, a newline, an emoji, or WhatsApp formatting markup\n(*, _, ~) — enforced by ApplyButtonLabelContentRules in\nTemplateButtonValidator. Meta reports all four as one error: \"Buttons can't have any\nvariables, newlines, emojis, or formatting characters.\"\n \nAUTHENTICATION OTP buttons are the exception: Meta auto-localizes their label from the\ntemplate language, and the converter drops whatever text was sent.", "maxLength": 25, "minLength": 0, "nullable": false }, "quickReplyType": { "type": "string", "minLength": 1, "nullable": false }, "urlType": { "type": "string", "minLength": 1, "nullable": false }, "url": { "type": "string", "maxLength": 2000, "minLength": 0, "nullable": false }, "variables": { "type": "array", "description": "Variables embedded in a dynamic URL button (only when UrlType = dynamic).\nCount is capped by TemplateContentLimits.MaxUrlButtonVariables; the placeholder must\nappear at the end of Url (validated in TemplateDefinitionValidator).", "nullable": false, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateVariable" } }, "activeFor": { "type": "integer", "format": "int32", "minimum": 0.0, "nullable": false, "exclusiveMinimum": true }, "countryCode": { "type": "string", "minLength": 1, "nullable": false }, "phoneNumber": { "type": "string", "minLength": 1, "nullable": false }, "offerCode": { "type": "string", "minLength": 1, "nullable": false }, "otpType": { "type": "string", "nullable": true }, "autofillText": { "type": "string", "nullable": true }, "packageName": { "type": "string", "nullable": true }, "signatureHash": { "type": "string", "nullable": true } } }, "SentDmServicesCommonEntitiesAuthenticationConfig": { "type": "object", "description": "Configuration for AUTHENTICATION category templates", "additionalProperties": false, "properties": { "addSecurityRecommendation": { "type": "boolean", "description": "Whether to add the security recommendation text: \"For your security, do not share this code.\"" }, "codeExpirationMinutes": { "type": "integer", "description": "Code expiration time in minutes (1-90). If set, adds footer: \"This code expires in X minutes.\"", "format": "int32", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsDeleteTemplateRequest": { "type": "object", "example": { "delete_from_meta": false, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsDeleteTemplateRequest_Properties", "type": "object", "description": "Request to delete a template", "additionalProperties": false, "properties": { "delete_from_meta": { "type": "boolean", "description": "Whether to also delete the template from WhatsApp/Meta (optional, defaults to false)", "nullable": true, "example": false } } } ] }, "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsGetTemplateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfTemplatesListResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3TemplatesResponsesTemplatesListResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3TemplatesResponsesTemplatesListResponse": { "type": "object", "description": "A paginated list of templates.", "additionalProperties": false, "properties": { "templates": { "type": "array", "description": "The templates on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3TemplatesResponsesTemplateResponse" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsGetTemplatesRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsUpdateTemplateRequest": { "type": "object", "example": { "name": "Updated Welcome Message", "category": "MARKETING", "submit_for_review": false, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3TemplatesRequestsUpdateTemplateRequest_Properties", "type": "object", "description": "Request to update an existing template", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Template display name", "nullable": true, "example": "Updated Welcome Message" }, "category": { "type": "string", "description": "Template category: MARKETING, UTILITY, AUTHENTICATION", "nullable": true, "example": "MARKETING" }, "language": { "type": "string", "description": "Template language code (e.g., en_US)", "nullable": true, "example": null }, "definition": { "type": "object", "description": "Template definition including header, body, footer, and buttons", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesTemplateDefinition" } ] }, "submit_for_review": { "type": "boolean", "description": "Whether to submit the template for review after updating (default: false)", "example": false } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfileResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesResponsesSenderProfileResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesResponsesSenderProfileResponse": { "type": "object", "description": "A sender profile as the API reports it — the same document the create call accepts, plus the read-only\nfacts it cannot: each market's status and what it still owes.\n \nNo status at the profile, brand or campaign level. Brand and campaign are identity, and\nidentity has no lifecycle. What has one is the registration of a sender in a market, and the approval of\na channel — so status lives there, where it says which specific thing is blocked rather than flattening\nseveral answers into one.", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "short_name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "api_key": { "type": "string", "description": "The API key for this profile.\n \nReturned by create and by nothing else. It is shown once; a read that repeated it would\nturn every profile list into a credential dump and put the key into any log or cache that keeps a\nresponse body.\n \nOmitted rather than null on a read. A key field that is always present and always empty\nsuggests it could be populated, which is an invitation to populate it; absent says there is nothing\nto look for. Doing it with a serializer condition rather than a second response type keeps create and\nread on one shape, which is what stops them drifting.", "nullable": true }, "billing": { "type": "object", "description": "Who pays, reported the way a create would have asked for it: { \"inherit\": true } for the\norganization, { \"inherit\": false } for the profile, and fallback for the profile drawing on\nboth.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesResponsesBillingResponse" } ] }, "notifications": { "type": "string", "description": "Who is notified about this profile's events: ORGANIZATION, SENDER_PROFILE, or\nORGANIZATION_AND_SENDER_PROFILE. Always present — a profile that never chose reports as\nORGANIZATION, the value a create would send to get the default behaviour.", "nullable": true }, "channels": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSenderProfileChannelsState" } ] }, "compliance": { "type": "object", "description": "Brand, campaign, and compliance documents lifted from all SMS markets to the profile root, so a\ncaller finds everything in one place rather than walking channels.sms[n].compliance.\nPer-market compliance is always null in profile responses after the lift.\nAbsent on a list read (documents are not fetched per market for a list).", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSuppliedComplianceState" } ] }, "created_at": { "type": "string", "format": "date-time" } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesResponsesBillingResponse": { "type": "object", "description": "Who pays for a sender profile's traffic, as a read reports it.\n \nIts own type, field for field the same as\nBillingRequest. Same reason as the brand: a response is not\na request, whatever it carries.", "additionalProperties": false, "properties": { "inherit": { "type": "boolean", "description": "Whether the organization pays, rather than the profile." } } }, "SentDmServicesCommonChannelsContractsSenderProfileChannelsState": { "type": "object", "description": "The channels a profile sends on. SMS is a list because a profile can send in several markets; WhatsApp\nand RCS are single, because a profile has one business account and one agent.", "additionalProperties": false, "properties": { "customer_id": { "type": "string", "description": "Which customer these channels belong to — the key's own, or the profile named in x-profile-id.\n \nSame reason the brand carries one: as the response to /v3/channels there is no other id in\nthe document, and under x-profile-id this is the profile the call resolved to rather than the\ncaller. Absent when nested inside a sender profile, whose own id already says whose they are.", "format": "uuid", "nullable": true }, "sms": { "type": "array", "items": { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSmsMarketState" } }, "whatsapp": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsWhatsappChannelState" } ] }, "rcs": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsRcsAgentState" } ] }, "mms": { "type": "array", "description": "The markets this profile can send MMS in, one entry per country, or empty when none.\n \nAppears alongside sms rather than replacing an entry in it: the two are separate senders\non the same number and a caller needs to see both — a market can be live for SMS while its MMS row is\nstill provisioning, or MMS-incapable entirely because the market's sender-type SKU does not carry\nit.", "items": { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsMmsMarketState" } }, "voice": { "type": "array", "description": "The numbers this profile carries phone calls on, one entry per number, or empty when none. Voice is\nper number like an SMS market is per country: each number is its own channel row, turned on and off\non its own, and one of them is the line app-originated calls fall back to.", "items": { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsVoiceNumberState" } } } }, "SentDmServicesCommonChannelsContractsSmsMarketState": { "type": "object", "description": "One SMS market the profile sends in — its sender, where that sender stands, and what the market wants.\n \nA profile may send in several: it is a tenant, not a market. Each carries its own status, because\na profile can be live in one country and mid-registration in another — and each carries what it still owes,\nrather than that being reported in a separate array a caller has to join on.", "additionalProperties": false, "properties": { "country": { "type": "string", "nullable": true }, "number_type": { "type": "string", "nullable": true }, "sender_value": { "type": "string", "description": "The sender itself. Null until a carrier-assigned number is procured. For a market holding several numbers,\nthe first one assigned — every number is in numbers.", "nullable": true }, "numbers": { "type": "array", "description": "Every number this market holds or is still owed, each with its area code and its own status\n(ACTIVE once it can send, PROVISIONING while it is still to be assigned). One entry for a\nmarket holding one number. US 10DLC numbers are assigned when the campaign is approved, so they read as\nowed until then. Read-only.", "items": { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSmsNumberState" } }, "status": { "type": "string", "description": "Where this market's sender stands, in terms of who is holding it up — PROVISIONING,\nACTION_NEEDED, PENDING_REVIEW or ACTIVE. Read-only.\n \nResolved rather than reported raw: a live sender reads ACTIVE whatever it still owes, a\nmarket with outstanding requirements or an open resubmission request reads ACTION_NEEDED, and a\nmarket that registers with a regime reads PENDING_REVIEW once its brand exists — filing to The\nCampaign Registry is ours to do and need not have happened yet, so a dedicated brand created through\nthis API reads PENDING_REVIEW from the moment it is stored.", "nullable": true, "example": "PROVISIONING", "enum": [ "PROVISIONING", "ACTION_NEEDED", "PENDING_REVIEW", "ACTIVE", "INACTIVE" ], "x-enum-descriptions": { "PROVISIONING": "We are working on it and there is nothing for you to do — a number is being procured, or a registration is being assembled. Minutes to hours.", "ACTION_NEEDED": "**Waiting on you.** Something the market asks for has not been supplied, a regulator rejected what was, or we have asked you to correct and resubmit your identity data. Nothing progresses until you act. For an SMS market, `GET /v3/channels/sms/{country}/{type}` names what it wants and `PATCH` on the same path supplies it — compliance values, documents and numbers alike.", "PENDING_REVIEW": "With a regulator or carrier — filed, or assembled and queued for us to file — and their answer is what moves it, to `ACTIVE` or back to `ACTION_NEEDED`. Nothing on your side changes it. Days for SMS, weeks for RCS.", "ACTIVE": "Can carry traffic now. A channel a sender profile runs on its organization's reads `ACTIVE` too — it sends, which is what the field is about.", "INACTIVE": "**It had a working sender and no longer does** — the number was released, or the campaign it carried lapsed. Distinct from `PROVISIONING`, which means it has never sent yet: the same absence of a sender, opposite news. Sends will fail until it returns to `ACTIVE`." } }, "reason_code": { "type": "string", "description": "Why the market is not ACTIVE, as a stable code: an ErrorCodes CHANNEL_xxx value such\nas CHANNEL_001 (something you owe) or CHANNEL_009 (under review). Switch on this rather than\non reason. Omitted while ACTIVE. Read-only; when nothing more specific is known it is the\ngeneric reason for the status.", "nullable": true }, "reason": { "type": "string", "description": "A sentence for reason_code: this market's own explanation, naming what is outstanding where that\nis you. Omitted while ACTIVE.", "nullable": true }, "compliance": { "type": "object", "description": "What this market has been given. Present on a list read for markets that register (brand and campaign\nincluded, documents absent); fully populated on a single-profile read. Null only when the market\nregisters with nobody and no compliance data was computed — nothing to show.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSuppliedComplianceState" } ] } } }, "SentDmServicesCommonChannelsContractsSmsNumberState": { "type": "object", "description": "One number of an SMS market.", "additionalProperties": false, "properties": { "sender_value": { "type": "string", "description": "The number, or null while it is still to be assigned.", "nullable": true }, "area_code": { "type": "string", "description": "The number's area code, e.g. 212. While the number is still to be assigned, the area code it was\nasked for, or null when it was asked for in any area code.", "nullable": true }, "status": { "type": "string", "description": "ACTIVE once the number can send; PROVISIONING while it is still to be assigned.", "nullable": true } } }, "SentDmServicesCommonChannelsContractsSuppliedComplianceState": { "type": "object", "description": "What a market has been given: the identity it registers under, its programme, and any documents attached.\n \nWhat it does not carry is what the market asks for. That is the subject of\nGET /v3/compliance/requirements, and it is the same answer for every caller — a description of what\na compliance regime wants, not a record of one customer's progress through it. It was reported here as\nwell for a while, which put the same array in six response shapes and left a caller deciding which of two\nsources to believe.\n \nPresent on a list read for markets that register (carrying brand and campaign), but with\ndocuments absent — documents are not fetched for a list, because a catalog lookup and a document\nread per market would multiply across a page. Absent documents is distinct from an empty list:\nabsent says they were not fetched; empty says the market has been given none. The parent object is null\nonly when the market registers with nobody and compliance was not computed — nothing to show at all.", "additionalProperties": false, "properties": { "brand": { "type": "object", "description": "The identity this market registers under, with inherit saying whose it is.\n \nReported here rather than on the profile because it belongs to the registration this market\nfiles, and only one market files one. It was a top-level block for a while, which put a per-registration\nvalue beside a list of markets and left a caller to work out which market it belonged to.\n \nAbsent for a market that registers with nobody — such a market asks for no identity, so there is\nnone to report. Absent and null mean different things: absent says this market does not ask, null would\nsay it asks and nothing was supplied.\n \nUntyped, like the request side, because its members are declared by the market's own schema rather\nthan by a C# class. A typed pair here would be a second definition of what a market wants, free to drift\nfrom the one that validates.", "nullable": true, "additionalProperties": {} }, "campaign": { "type": "object", "description": "The programme this market registers, with inherit saying whose it is.\n \n\n \nOne, not a list. TcrCampaigns permits several and an account built on the admin\nside may hold them, but this surface offers one — which is what lets the market's PATCH be an\nupsert rather than a collection with an addressable create behind it. An account holding several is\nreported as its first and refused on write, rather than half-edited.\n \nCarries no id. Nothing addresses a campaign, and an undeclared key would be refused if the\ncaller sent this object back — which it is meant to be able to do.", "nullable": true, "additionalProperties": {} }, "documents": { "type": "array", "description": "What has been supplied for this market.\n \nFiles, not values — the declared halves above carry the values. A document cannot be a JSON value,\nso it is sent as multipart on the channel call and reported here as a reference.\n \nAbsent on a list read, which fetches identity but does not compute compliance documents per\nmarket. Absent and empty mean different things: absent says the documents were not fetched; empty says\nthe market has been given none.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSuppliedDocument" } } } }, "SentDmServicesCommonChannelsContractsSuppliedDocument": { "type": "object", "description": "A document a market asked for and has been given.", "additionalProperties": false, "properties": { "key": { "type": "string", "description": "The catalog's name for this document, matching the requirement it satisfies." }, "file_name": { "type": "string", "nullable": true }, "document_id": { "type": "string", "description": "Identifier of the upload, for fetching it back through the documents endpoints.", "format": "uuid", "nullable": true } } }, "SentDmServicesCommonChannelsContractsWhatsappChannelState": { "type": "object", "description": "The profile's WhatsApp account. Its status is Meta's verification state.", "additionalProperties": false, "properties": { "waba_id": { "type": "string", "nullable": true }, "phone_number_id": { "type": "string", "description": "The Meta phone-number id the profile sends from, or null when the account is connected but no number\nhas been named yet — which is what a provisioning status means here.", "nullable": true }, "solution_id": { "type": "string", "description": "Derived, not echoed. The request no longer accepts this — it is read off the organization's\nshared-account listing at connect time and reported back so a caller can see which partnership the\naccount actually arrived through.", "nullable": true }, "owner_business_id": { "type": "string", "description": "Derived from the organization's shared-account listing, like SolutionId.", "nullable": true }, "status": { "type": "string", "description": "Read-only. Never carries a token — the row holds that and it is not returned. ACTION_NEEDED when\nno account is connected or the account has no phone number: both are yours to do.", "nullable": true, "example": "PROVISIONING", "enum": [ "PROVISIONING", "ACTION_NEEDED", "PENDING_REVIEW", "ACTIVE", "INACTIVE" ], "x-enum-descriptions": { "PROVISIONING": "We are working on it and there is nothing for you to do — a number is being procured, or a registration is being assembled. Minutes to hours.", "ACTION_NEEDED": "**Waiting on you.** Something the market asks for has not been supplied, a regulator rejected what was, or we have asked you to correct and resubmit your identity data. Nothing progresses until you act. For an SMS market, `GET /v3/channels/sms/{country}/{type}` names what it wants and `PATCH` on the same path supplies it — compliance values, documents and numbers alike.", "PENDING_REVIEW": "With a regulator or carrier — filed, or assembled and queued for us to file — and their answer is what moves it, to `ACTIVE` or back to `ACTION_NEEDED`. Nothing on your side changes it. Days for SMS, weeks for RCS.", "ACTIVE": "Can carry traffic now. A channel a sender profile runs on its organization's reads `ACTIVE` too — it sends, which is what the field is about.", "INACTIVE": "**It had a working sender and no longer does** — the number was released, or the campaign it carried lapsed. Distinct from `PROVISIONING`, which means it has never sent yet: the same absence of a sender, opposite news. Sends will fail until it returns to `ACTIVE`." } }, "reason_code": { "type": "string", "description": "Why the account is not ACTIVE, as a stable code: an ErrorCodes CHANNEL_xxx value such\nas CHANNEL_001 (something you owe) or CHANNEL_009 (under review). Switch on this rather than\non reason. Omitted while ACTIVE. Read-only; when nothing more specific is known it is the\ngeneric reason for the status.", "nullable": true }, "reason": { "type": "string", "description": "A sentence for reason_code, saying what to do where it is yours. Omitted while ACTIVE.", "nullable": true } } }, "SentDmServicesCommonChannelsContractsRcsAgentState": { "type": "object", "description": "An RCS agent as its owner sees it: the order form back, plus where the submission stands.\n \nNot RcsSenderResponse. That one is the admin projection and carries the pipeline we\ntrack about a customer's request — internalStatus, statusReason,\nisLaunched — and the S3 keys behind the assets. None of that is the customer's to read: an internal\nstatus is a note to ourselves, and an S3 key is a storage detail that would become a contract the moment\nit was published.\n \nWhat is here is what the caller sent, in the names it sent them under, plus the three things only we\ncan answer: the record's id, its status, and the number it sends from. So a read after a\nwrite shows the form as stored rather than as echoed.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The agent record. Stable across the whole approval, and what support will ask for.\n \nNullable and omitted when absent: a sender profile with RCS intent records the channel but has no\nagent until the order form is submitted, so no id exists to report. A zero GUID is not a valid id\nand is worse than the field being absent.", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "Where the agent stands, in terms of who is holding it up — PROVISIONING, ACTION_NEEDED,\nPENDING_REVIEW or ACTIVE.\n \nResolved from both of the provider's axes rather than reported raw: an agent whose resubmission\nwe have asked for reads ACTION_NEEDED however its carrier status still reads, and an agent not\nyet handed over reads PROVISIONING rather than pending a review nobody has started.", "nullable": true, "example": "PROVISIONING", "enum": [ "PROVISIONING", "ACTION_NEEDED", "PENDING_REVIEW", "ACTIVE", "INACTIVE" ], "x-enum-descriptions": { "PROVISIONING": "We are working on it and there is nothing for you to do — a number is being procured, or a registration is being assembled. Minutes to hours.", "ACTION_NEEDED": "**Waiting on you.** Something the market asks for has not been supplied, a regulator rejected what was, or we have asked you to correct and resubmit your identity data. Nothing progresses until you act. For an SMS market, `GET /v3/channels/sms/{country}/{type}` names what it wants and `PATCH` on the same path supplies it — compliance values, documents and numbers alike.", "PENDING_REVIEW": "With a regulator or carrier — filed, or assembled and queued for us to file — and their answer is what moves it, to `ACTIVE` or back to `ACTION_NEEDED`. Nothing on your side changes it. Days for SMS, weeks for RCS.", "ACTIVE": "Can carry traffic now. A channel a sender profile runs on its organization's reads `ACTIVE` too — it sends, which is what the field is about.", "INACTIVE": "**It had a working sender and no longer does** — the number was released, or the campaign it carried lapsed. Distinct from `PROVISIONING`, which means it has never sent yet: the same absence of a sender, opposite news. Sends will fail until it returns to `ACTIVE`." } }, "reason_code": { "type": "string", "description": "Why the agent is not ACTIVE, as a stable code: an ErrorCodes CHANNEL_xxx value such\nas CHANNEL_001 (something you owe) or CHANNEL_009 (under review). Switch on this rather than\non reason. Omitted while ACTIVE. Read-only; when nothing more specific is known it is the\ngeneric reason for the status.", "nullable": true }, "reason": { "type": "string", "description": "A sentence for reason_code, saying what to do where it is yours. Omitted while ACTIVE.", "nullable": true }, "phone_number": { "type": "string", "description": "The number the agent sends from, derived from brand_phone_number.", "nullable": true }, "display_name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "agent_use_case": { "type": "string", "nullable": true }, "brand_name": { "type": "string", "nullable": true }, "privacy_policy_url": { "type": "string", "nullable": true }, "terms_and_conditions_url": { "type": "string", "nullable": true }, "website_url": { "type": "string", "nullable": true }, "brand_color": { "type": "string", "nullable": true }, "brand_phone_number": { "type": "string", "nullable": true }, "customer_support_phone_number": { "type": "string", "nullable": true }, "brand_email": { "type": "string", "nullable": true }, "customer_support_email": { "type": "string", "nullable": true }, "contact_name_and_title": { "type": "string", "nullable": true }, "company_ein": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "nullable": true }, "official_address": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsRcsAddress" } ] }, "brief_company_description": { "type": "string", "nullable": true }, "opt_in_process_description": { "type": "string", "nullable": true }, "start_message": { "type": "string", "nullable": true }, "help_message": { "type": "string", "nullable": true }, "stop_message": { "type": "string", "nullable": true }, "sample_messages": { "type": "array", "nullable": true, "items": { "type": "string" } }, "created_at": { "type": "string", "description": "Omitted when no real agent record exists — the intent-only path has no creation timestamp.", "format": "date-time", "nullable": true } } }, "SentDmServicesCommonChannelsContractsRcsAddress": { "type": "object", "description": "The registered address of the company behind the agent.", "additionalProperties": false, "properties": { "street": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } } }, "SentDmServicesCommonChannelsContractsMmsMarketState": { "type": "object", "description": "One market the profile can send MMS in.\n \nDeliberately not SmsMarketState: an MMS market carries no compliance of its own. It\nis the same number, carrier and registration as its SMS twin in that country — MMS files nothing\nseparately — so a compliance block here would always be null and would invite the question of\nwhat an MMS market owes. It owes what the SMS market owes, reported there.", "additionalProperties": false, "properties": { "country": { "type": "string", "description": "ISO-3166 alpha-2 of the market.", "nullable": true }, "number_type": { "type": "string", "description": "The sender type the market sends from, mirroring the SMS sender.", "nullable": true }, "sender_value": { "type": "string", "description": "The sending number. Null while the market is still being provisioned.", "nullable": true }, "status": { "type": "string", "description": "Where this market's MMS sender stands. Read-only.", "nullable": true } } }, "SentDmServicesCommonChannelsContractsVoiceNumberState": { "type": "object", "description": "One number the profile carries phone calls on.", "additionalProperties": false, "properties": { "number": { "type": "string", "description": "The number, in E.164." }, "status": { "type": "string", "description": "ACTIVE while the number carries calls, INACTIVE once it was turned off. Nothing\nprovisions: a number the customer holds can carry calls the moment voice is turned on for it." }, "default_for_app_calls": { "type": "boolean", "description": "Whether this is the line app-originated calls are placed from when a voice token names no number.\nExactly one active voice number carries it while the profile has any." }, "callback_url": { "type": "string", "description": "Where Sent asks what to do with each call on this number: a signed question is POSTed here when\na call arrives or a caller presses a key, and the answer decides the call. The signing secret is\nnot on this read; it is shown when voice is turned on and by the rotate endpoint.", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsCreateSenderProfileRequest": { "type": "object", "example": { "name": "Example Retail", "short_name": "Example", "channels": { "sms": { "country": "US", "number_type": "TEN_DLC" } }, "compliance": { "brand": { "legal_name": "Example Retail Inc", "business_name": "Example Retail", "tax_id": "12-3456789", "tax_id_type": "us_ein", "entity_type": "PRIVATE_PROFIT", "street": "123 Main Street", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US", "website": "https://example.com", "contact_name": "John Smith", "contact_email": "john@example.com", "contact_phone": "+12125550123" }, "campaign": { "description": "Order and delivery updates for customers who have bought from Example Retail, plus occasional offers.", "message_flow": "Customers opt in at checkout on https://example.com by ticking a box that is unchecked by default, and again in the account settings page. Consent is not a condition of purchase.", "use_cases": [ { "use_case": "DELIVERY_NOTIFICATION", "sample_messages": [ "Example Retail: order 10432 is out for delivery and arrives today. Track it at https://example.com/t/10432. Reply STOP to opt out.", "Example Retail: order 10432 was delivered. Reply STOP to opt out." ] }, { "use_case": "MARKETING", "sample_messages": [ "Example Retail: 20% off everything this weekend with code SAVE20 at https://example.com/sale. Reply STOP to opt out." ] } ], "opt_in_message": "Example Retail: you are subscribed to order updates and offers. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to cancel.", "opt_out_message": "Example Retail: you are unsubscribed and will receive no further messages. Reply START to resubscribe.", "help_message": "Example Retail: email support@example.com or call +1 212 555 0123. Msg & data rates may apply. Reply STOP to unsubscribe.", "opt_in_keywords": "START,YES", "opt_out_keywords": "STOP,END,CANCEL,UNSUBSCRIBE,QUIT", "help_keywords": "HELP,INFO", "privacy_policy_link": "https://example.com/privacy", "terms_and_conditions_link": "https://example.com/terms", "volume": "1500" } }, "sandbox": false }, "required": [ "name", "short_name" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsCreateSenderProfileRequest_Properties", "type": "object", "description": "Create a sender profile under the authenticated organization.\n \nHow ownership is expressed. Every capability is one of two things, and the request says\nwhich without a flag per state: { \"inherit\": true } uses the organization's;\nsupplying the capability's own fields creates one for the profile; omitting the block entirely means the\nprofile has none. Ownership is one boolean — data is what owning looks like, and a\nsecond way to say it would let a request contradict itself.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Display name for the profile. Required.", "maxLength": 200, "minLength": 0, "nullable": false, "example": "Example Retail" }, "short_name": { "type": "string", "description": "Short name, which is also the SMS sender id — required. 3–11 characters of letters, numbers and\nspaces, with at least one letter.", "maxLength": 11, "minLength": 3, "pattern": "^(?=.*[A-Za-z])[A-Za-z0-9 ]+$", "nullable": false, "example": "Example" }, "description": { "type": "string", "nullable": true, "example": null }, "billing": { "type": "object", "description": "Who pays for what this profile sends.\n{ \"inherit\": true } bills the organization; { \"inherit\": false } (or an empty block) bills\nthe profile only. Omitting the block bills the profile first, with the organization covering what the\nprofile's balance cannot. Reads report that default as { \"inherit\": false }; GET /v3/account\nreports it in settings.billing_model.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonSenderProfilesContractsBillingRequest" } ] }, "notifications": { "type": "string", "description": "Who is notified about this profile's events: ORGANIZATION, SENDER_PROFILE, or\nORGANIZATION_AND_SENDER_PROFILE. Omitting it leaves the profile on the Organization default.", "nullable": true, "example": null }, "channels": { "type": "object", "nullable": true, "example": { "sms": { "country": "US", "number_type": "TEN_DLC" } }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileChannels" } ] }, "compliance": { "description": "What this market registers with. Its members are declared by the market itself — call `GET /v3/compliance/requirements?country=&type=` for the authoritative set.\n\n**US `TEN_DLC` is the only market that registers with a regime**, and the only one whose compliance carries `brand` and `campaign`; those are the members described here. Every other market's compliance is document keys, which come from configuration rather than from code and so cannot be listed in this document.", "allOf": [ { "$ref": "#/components/schemas/MarketCompliance" } ] } } } ] }, "SentDmServicesCommonSenderProfilesContractsBillingRequest": { "type": "object", "description": "Who pays for what a sender profile sends.\n \nOwnership reads the same way as BrandRequest and CampaignRequest:\ninherit: true is the organization paying; inherit: false (or an empty block) is the\nprofile paying for itself.\n \nAn absent block is the one place billing differs from brand and campaign: a profile still has to be\npaid for, so omitting billing stores ProfileAndOrganizationBilling — the profile pays first\nand its organization covers what the profile's balance cannot (see\nResolveStored). { \"name\": \"...\" } stays a complete request.\n \nBilling carries no fields of its own yet, so a profile paying for itself is\n{ \"inherit\": false } — or an empty block, which means the same. That is thinner than brand and\ncampaign, where supplying data is the act of owning; it becomes ordinary the moment billing gains a\ncontact or a payment method to carry.", "additionalProperties": false, "properties": { "inherit": { "type": "boolean", "description": "Whether the parent organization pays. false is the profile paying for itself." } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileChannels": { "type": "object", "description": "The channels the profile sends on. Each is independently the profile's own or absent — none can be\ninherited, so none carries a mode and presence is the whole of the request.\n \nA profile can send SMS in several markets, but create takes one — the market it starts in.\nFurther markets are added through POST /v3/channels/sms with x-profile-id, and a read returns\nthem all as a list. Create stays singular permanently rather than being a list that accepts one entry:\nthe constraint is in the type, and there is no later widening to break the contract.", "additionalProperties": false, "properties": { "sms": { "type": "object", "description": "The market this profile starts sending SMS in — one country and number_type, which is\nalso what the compliance block is answering for. Omit for a profile with no SMS sender of its\nown.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileSms" } ] }, "whatsapp": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileWhatsapp" } ] }, "rcs": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileRcs" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileSms": { "type": "object", "description": "One SMS market a profile sends in — a country and a sender type.\n \nA profile may have several. It is a tenant, not a market: a business sending to two countries is\none customer of yours, and forcing it into two profiles would give it two API keys, two inboxes and two\ncontact lists for one business. The platform already assumes many —\nCustomerChannelProviders is unique on (customer, channel, iso, number).\n \nNo mode: a sender is the profile's own or it has none. Listing a market is the request\nfor one.\n \nAlso the discriminator for everything else: the compliance catalog is keyed on (country, number\ntype), and that pair decides which fields brand accepts and what compliance is asked\nfor.", "additionalProperties": false, "required": [ "country" ], "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country the sender operates in, e.g. US.", "minLength": 1, "nullable": false }, "number_type": { "type": "string", "description": "Sender type: LOCAL, MOBILE, TEN_DLC, TOLL_FREE, SHORT_CODE or\nALPHANUMERIC. 10DLC is accepted as a synonym of TEN_DLC. Availability varies\nby country.", "nullable": true }, "sender_value": { "type": "string", "description": "The sender's identity, where the caller chooses it rather than the carrier assigning it. Required\nwhen number_type is ALPHANUMERIC; omit for carrier-assigned types and one is\nprovisioned.", "nullable": true }, "area_codes": { "type": "array", "description": "The area codes to put this sender in, in your own order of preference, e.g. [\"415\", \"628\"]\nfor the US or [\"20\"] for London. Omit it and a number is claimed anywhere in the country.\n \nOrdered, and the order is the request. The claim tries each code in turn and stops at the\nfirst that yields a number. Nothing sorts the list and a code listed twice is refused.\n \nOne to fifty entries, each the area code as digits: 415, with the trunk prefix as\n020, or with the country's dialing prefix as +1415 (all are stored as the bare code). A\ndialing prefix from a different country than country is refused. Each code is checked against\nthe country's numbering plan: it must start real local or mobile numbers there, so toll-free and\npremium ranges, service codes and another country's codes are refused with a reason.\n \nLOCAL senders in any country, and US TEN_DLC senders. No other sender type\nhas a geographic area code, and the list is refused with one rather than accepted and dropped.\n \nHonoured exactly or not at all. Ask for 415 and you get a 415 number or you\nget none, never a neighbouring code you did not name. A miss leaves the market with no sender yet and\nthe codes recorded on it, so it is filled when stock appears rather than filled now from somewhere else.\nMany countries outside North America require address or business documents before a local number can\nbe bought, which can delay or prevent the fill.", "nullable": true, "items": { "type": "string" } }, "numbers": { "type": "array", "description": "The numbers to assign, one entry per area code, e.g.\n[{\"area_code\": \"212\", \"quantity\": 2}, {\"area_code\": \"415\"}, {\"quantity\": 1}]: two numbers in 212,\none in 415 and one in any area code. quantity defaults to 1, and an entry without\narea_code means any area code. Omit numbers for one number.\n \nOnly with LOCAL or TEN_DLC, and not together with area_codes. Each area code is\nvalidated against country the same way area_codes is and may appear once, and at most one\nentry may leave area_code out. US TEN_DLC numbers are assigned when the campaign is\napproved, not at request time. Not available when the profile inherits the organization's\ncampaign.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonSenderProfilesContractsSmsNumberRequest" } } } }, "SentDmServicesCommonSenderProfilesContractsSmsNumberRequest": { "type": "object", "description": "One entry of numbers: how many numbers to assign in one area code, or in any area code when\nAreaCode is omitted.", "additionalProperties": false, "properties": { "area_code": { "type": "string", "description": "The area code, e.g. 212, validated against the request's country. Omit it for numbers in any\narea code.", "nullable": true }, "quantity": { "type": "integer", "description": "How many numbers. At least 1; omitted means 1.", "format": "int32", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileWhatsapp": { "type": "object", "description": "The profile's own WhatsApp Business Account, named by the two identifiers the organization cannot answer\nfor you.\n \nNo mode: a profile's WABA is its own or it has none. Sharing the organization's would mean\nsharing its inbox and its throughput, which makes the two indistinguishable to a recipient — so\ninheriting is not offered rather than refused.\n \nEverything derivable is derived. Whenever this block is present, the solution the account\narrived through, the client business portfolio that owns it, the access token and that token's expiry are\nall resolved from the organization by\nIPartnerSolutionService.ResolveAccountCredentialsAsync — the first two off the org's shared-account\nlisting, the token minted against the org's own solution. They were previously asked for and are no\nlonger accepted: solution_id and owner_business_id are Meta's answer about provenance, so\ntaking them from the caller let a request assert a partnership Meta disagreed with, and the listing has to\nbe consulted regardless because it is what proves the account is one this organization may reach.\n \nNo access token, and there never was one here: it is minted per client business portfolio and\nrotates roughly every sixty days, so a pasted value would be stale before it was useful. Asking a\ncustomer to mint a System User token in Meta Business Manager is skilled work in a console they were\nnever meant to see, and it would say nothing about which solution the account came from or when it is\nrevoked.", "additionalProperties": false, "properties": { "waba_id": { "type": "string", "description": "WhatsApp Business Account id — one of the accounts shared into your organization. Required: the\norganization holds one per client, and nothing but the caller says which belongs to this profile.", "nullable": true }, "phone_number_id": { "type": "string", "description": "The Meta phone-number id this profile sends from. Must already be registered under\nWabaId.\n \nOptional. Omit it to attach the account now and settle the number later: the channel reads as\nACTION_NEEDED with CHANNEL_007, and the profile's WhatsApp messages fail until a number\nis named. They do not fall back to the organization's account. Nothing picks one on your behalf.", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsSenderProfileRcs": { "type": "object", "description": "Asks for an RCS agent of the profile's own, optionally with the full order form inline.\n \nTwo modes, distinguished by whether any field is populated:\n\"rcs\": {} — intent only. Records that the profile wants its own agent; the order form is\nsubmitted separately through POST /v3/channels/rcs once the fields are ready.\n\"rcs\": { ...fields... } — full form. All required fields must be present; the agent is\ncreated alongside the profile in one call. Omitting opt_in_screenshot_url is allowed.", "additionalProperties": false, "required": [ "description" ], "properties": { "display_name": { "type": "string", "nullable": true }, "description": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": false }, "agent_use_case": { "type": "string", "nullable": true }, "hosting_region": { "type": "string", "nullable": true }, "billing_category": { "type": "string", "nullable": true }, "brand_name": { "type": "string", "nullable": true }, "privacy_policy_url": { "type": "string", "nullable": true }, "terms_and_conditions_url": { "type": "string", "nullable": true }, "website_url": { "type": "string", "nullable": true }, "brand_color": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "nullable": true }, "banner_url": { "type": "string", "nullable": true }, "brand_phone_number": { "type": "string", "nullable": true }, "customer_support_phone_number": { "type": "string", "nullable": true }, "brand_email": { "type": "string", "nullable": true }, "customer_support_email": { "type": "string", "nullable": true }, "contact_name_and_title": { "type": "string", "nullable": true }, "company_ein": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "nullable": true }, "official_address": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsRcsAddress" } ] }, "brief_company_description": { "type": "string", "nullable": true }, "opt_in_process_description": { "type": "string", "nullable": true }, "opt_in_screenshot_url": { "type": "string", "description": "Optional — uploaded separately and its URL may not be known at submission time.", "nullable": true }, "start_message": { "type": "string", "nullable": true }, "help_message": { "type": "string", "nullable": true }, "stop_message": { "type": "string", "nullable": true }, "sample_messages": { "type": "array", "nullable": true, "items": { "type": "string" } } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsDeleteSenderProfileRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsGetSenderProfileRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfilesListResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesResponsesSenderProfilesListResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesResponsesSenderProfilesListResponse": { "type": "object", "description": "A paginated list of sender profiles.", "additionalProperties": false, "properties": { "sender_profiles": { "type": "array", "description": "The sender_profiles on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SenderProfilesResponsesSenderProfileResponse" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsGetSenderProfilesRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsPatchSenderProfileRequest": { "type": "object", "example": { "name": "Example Retail Renamed", "short_name": "EXMPL", "sandbox": false }, "required": [ "name" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3SenderProfilesRequestsPatchSenderProfileRequest_Properties", "type": "object", "description": "Changes a sender profile's own attributes.\n \nOnly the profile's own attributes. Its identity, its markets and its compliance each get a\nsub-resource of their own; accepting them here as well would give every one of those fields two writers\nwith different validation, and no way to say which won.\n \nEvery field is optional, and an omitted field is left alone. An explicit null clears the\nfield — the two are different requests, and SuppliedFields is how the endpoint tells them\napart, because a nullable property cannot.", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 0, "nullable": false, "example": "Example Retail Renamed" }, "short_name": { "type": "string", "nullable": true, "example": "EXMPL" }, "description": { "type": "string", "maxLength": 2000, "minLength": 0, "nullable": true, "example": null }, "notifications": { "type": "string", "description": "Who is notified about this profile's events: ORGANIZATION, SENDER_PROFILE, or\nORGANIZATION_AND_SENDER_PROFILE. Cannot be cleared — a supplied value must be one of those.", "nullable": true, "example": null } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileCompletionResultResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfileCompletionResultResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfileCompletionResultResponse": { "type": "object", "description": "Response when a profile is already in the completed state and no further action is taken.", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Current process status of the profile (e.g., \"completed\", \"submitted\", \"in_progress\")." }, "message": { "type": "string", "description": "Human-readable message describing the result." } } }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileCompletionAcceptedResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfileCompletionAcceptedResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfileCompletionAcceptedResponse": { "type": "object", "description": "Response acknowledging that profile completion has been accepted and started in the background.\nThe provided webhook URL will be called when processing finishes.", "additionalProperties": false, "properties": { "message": { "type": "string", "description": "Human-readable message describing the accepted state." } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsCompleteProfileRequest": { "type": "object", "example": { "webHookUrl": "https://your-app.com/webhook/profile-complete", "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsCompleteProfileRequest_Properties", "type": "object", "description": "Request to complete a profile setup and connect it to the SMS and WhatsApp channels", "additionalProperties": false, "required": [ "webHookUrl" ], "properties": { "webHookUrl": { "type": "string", "description": "Webhook URL to call when profile completion finishes (success or failure)", "format": "uri", "minLength": 1, "example": "https://your-app.com/webhook/profile-complete" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfileDetailResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfileDetailResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfileDetailResponse": { "type": "object", "description": "Detailed profile response for v3 API", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Profile unique identifier", "format": "uuid" }, "organization_id": { "type": "string", "description": "Parent organization ID", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Profile name" }, "email": { "type": "string", "description": "Profile email (inherited from organization)", "nullable": true }, "icon": { "type": "string", "description": "Profile icon URL", "nullable": true }, "description": { "type": "string", "description": "Profile description", "nullable": true }, "short_name": { "type": "string", "description": "Profile short name/abbreviation. 3–11 characters: letters, numbers, and spaces only, with at least one letter.", "nullable": true }, "status": { "type": "string", "description": "Profile setup status: incomplete, pending_review, approved, rejected" }, "created_at": { "type": "string", "description": "When the profile was created", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the profile was last updated", "format": "date-time", "nullable": true }, "allow_contact_sharing": { "type": "boolean", "description": "Always false. A profile no longer shares contacts with sibling profiles — it sees only what\nit owns. Retained so existing v3 clients reading allow_contact_sharing keep deserializing; it\ncarries no information.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer share contacts; the flag it reported is gone.", "nullable": true }, "allow_template_sharing": { "type": "boolean", "description": "Always false. A profile no longer shares templates with sibling profiles. Retained so\nexisting v3 clients reading allow_template_sharing keep deserializing; it carries no\ninformation.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer share templates; the flag it reported is gone.", "nullable": true }, "inherit_contacts": { "type": "boolean", "description": "Always false. A profile no longer inherits its organization's contacts. Retained so existing\nv3 clients reading inherit_contacts keep deserializing; it carries no information.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer inherit contacts; the flag it reported is gone.", "nullable": true }, "inherit_templates": { "type": "boolean", "description": "Always false. A profile no longer inherits its organization's templates. Retained so existing\nv3 clients reading inherit_templates keep deserializing; it carries no information.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer inherit templates; the flag it reported is gone.", "nullable": true }, "inherit_tcr_brand": { "type": "boolean", "description": "Whether this profile inherits TCR brand from the organization" }, "inherit_tcr_campaign": { "type": "boolean", "description": "Whether this profile inherits TCR campaign from the organization" }, "billing_model": { "type": "string", "description": "Billing model: profile, organization, or profile_and_organization" }, "sending_phone_number_profile_id": { "type": "string", "description": "Deprecated. Always null. Sender borrowing is gone: a profile no longer points at another\nprofile for its SMS sender, and every profile owns the sender it sends from.\n \nKept on the wire, and never populated, because those are two different promises. Removing the key\nchanges the response's shape — a generated client loses the property and stops compiling on the next\nregenerate, for a value that is now null for every profile in existence. Keeping it null costs a key and\nbreaks nobody, and null is the honest answer rather than a placeholder: there is no borrowing left to\nreport.\n \nNothing could populate it. Migration 260813161500 dropped the column and copied each\nborrower its own channel-provider row; its Down() says outright that the borrower-to-lender\npairing is not recoverable. The only surviving trace is a notes string on the copied row.", "format": "uuid", "deprecated": true, "x-deprecatedMessage": "Sender borrowing is gone; always null. A profile owns its own sender — add one with POST /v3/channels/sms and the x-profile-id header.", "nullable": true }, "sending_whatsapp_number_profile_id": { "type": "string", "format": "uuid", "deprecated": true, "x-deprecatedMessage": "Sender borrowing is gone; always null. A profile owns its own sender — add one with POST /v3/channels/whatsapp and the x-profile-id header.", "nullable": true }, "sending_phone_number": { "type": "string", "description": "Direct SMS phone number", "nullable": true }, "whatsapp_phone_number": { "type": "string", "description": "Direct WhatsApp phone number", "nullable": true }, "allow_number_change_during_onboarding": { "type": "boolean", "description": "Whether number changes are allowed during onboarding", "nullable": true }, "waba_id": { "type": "string", "description": "WhatsApp Business Account ID associated with this profile.\nPresent whether the WABA is inherited from the organization or configured directly.", "nullable": true }, "billing_contact": { "type": "object", "description": "Billing contact for this profile. Present when billing_model is \"profile\" or \"profile_and_organization\".", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBillingContactResponse" } ] }, "brand": { "type": "object", "description": "Brand associated with this profile. Null if no brand has been configured yet.\nIncludes KYC information and TCR registration status.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandWithKycResponse" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBillingContactResponse": { "type": "object", "description": "Billing contact info returned in profile responses", "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandWithKycResponse": { "type": "object", "description": "Brand response with nested contact, business, and compliance sections — mirrors the request structure.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique identifier for the brand", "format": "uuid" }, "tcr_brand_id": { "type": "string", "description": "TCR brand ID (populated after TCR submission)", "nullable": true }, "status": { "type": "object", "description": "TCR brand status", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsTcrBrandStatus" } ] }, "identity_status": { "type": "object", "description": "TCR brand identity verification status", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsTcrBrandIdentityStatus" } ] }, "universal_ein": { "type": "string", "description": "Universal EIN from TCR", "nullable": true }, "csp_id": { "type": "string", "description": "Deprecated and scheduled for removal. Identifies the Campaign Service Provider that\nregistered the brand, which is Sent, so the value is the same for every brand and every\naccount. Nothing on your side can act on it and there is no replacement. Stop reading it.", "deprecated": true, "x-deprecatedMessage": "Identifies Sent as the registering CSP, is identical for every account, and has no replacement. Deprecated 2026-08-17 and scheduled for removal.", "nullable": true }, "submitted_to_tcr": { "type": "boolean", "description": "Whether this brand has been submitted to TCR" }, "submitted_at": { "type": "string", "description": "When the brand was submitted to TCR", "format": "date-time", "nullable": true }, "is_inherited": { "type": "boolean", "description": "Whether this brand is inherited from the parent organization" }, "created_at": { "type": "string", "description": "When the brand was created", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the brand was last updated", "format": "date-time", "nullable": true }, "contact": { "type": "object", "description": "Contact information for the brand", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandContactResponse" } ] }, "business": { "type": "object", "description": "Business details and address information", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandBusinessResponse" } ] }, "compliance": { "type": "object", "description": "Compliance and TCR-related information", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandComplianceResponse" } ] } } }, "SentDmServicesCommonEnumsTcrBrandStatus": { "type": "string", "description": "", "x-enumNames": [ "ACTIVE", "INACTIVE", "SUSPENDED" ], "enum": [ "ACTIVE", "INACTIVE", "SUSPENDED" ] }, "SentDmServicesCommonEnumsTcrBrandIdentityStatus": { "type": "string", "description": "", "x-enumNames": [ "SELF_DECLARED", "UNVERIFIED", "VERIFIED", "VETTED_VERIFIED" ], "enum": [ "SELF_DECLARED", "UNVERIFIED", "VERIFIED", "VETTED_VERIFIED" ] }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandContactResponse": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Primary contact name" }, "business_name": { "type": "string", "description": "Business/brand name", "nullable": true }, "role": { "type": "string", "description": "Contact's role in the business", "nullable": true }, "phone": { "type": "string", "description": "Contact phone number in E.164 format", "nullable": true }, "email": { "type": "string", "description": "Contact email address", "nullable": true }, "phone_country_code": { "type": "string", "description": "Contact phone country code (e.g., \"1\" for US)", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandBusinessResponse": { "type": "object", "additionalProperties": false, "properties": { "legal_name": { "type": "string", "description": "Legal business name", "nullable": true }, "tax_id": { "type": "string", "description": "Tax ID/EIN number", "nullable": true }, "tax_id_type": { "type": "string", "description": "Type of tax ID (e.g., us_ein, ca_bn)", "nullable": true }, "entity_type": { "type": "string", "description": "Business entity type", "nullable": true }, "street": { "type": "string", "description": "Street address", "nullable": true }, "city": { "type": "string", "description": "City", "nullable": true }, "state": { "type": "string", "description": "State/province code", "nullable": true }, "postal_code": { "type": "string", "description": "Postal/ZIP code", "nullable": true }, "country": { "type": "string", "description": "Country code (e.g., US, CA)", "nullable": true }, "url": { "type": "string", "description": "Business website URL", "nullable": true }, "country_of_registration": { "type": "string", "description": "Country where the business is registered", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesBrandComplianceResponse": { "type": "object", "additionalProperties": false, "properties": { "vertical": { "type": "object", "description": "Business vertical/industry category", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsTcrVertical" } ] }, "brand_relationship": { "type": "object", "description": "Brand relationship level with TCR", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsTcrBrandRelationship" } ] }, "is_tcr_application": { "type": "boolean", "description": "Whether this is a TCR (Campaign Registry) application" }, "phone_number_prefix": { "type": "string", "description": "Phone number prefix for messaging (e.g., \"+1\")", "nullable": true }, "destination_countries": { "type": "array", "description": "List of destination countries for messaging", "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesDestinationCountry" } }, "notes": { "type": "string", "description": "Additional notes about the business or use case", "nullable": true }, "primary_use_case": { "type": "string", "description": "Always null. The brand's free-text primary use case is no longer stored: it reached neither\nTCR nor any decision, and its column is dropped with no backfill, because the values were prose and\nthe typed equivalent is the campaign's MessagingUseCaseUS.\n \nRetained so existing v3 clients reading primary_use_case keep deserializing. Unlike the\nprofile sharing flags, which can answer false truthfully, there is no value to report here —\nthe field is present and empty rather than present and wrong.", "deprecated": true, "x-deprecatedMessage": "Always null. The brand's primary use case is not stored; the campaign's use cases replace it.", "nullable": true } } }, "SentDmServicesCommonEnumsTcrVertical": { "type": "string", "description": "", "x-enumNames": [ "PROFESSIONAL", "REAL_ESTATE", "HEALTHCARE", "HUMAN_RESOURCES", "ENERGY", "ENTERTAINMENT", "RETAIL", "TRANSPORTATION", "AGRICULTURE", "INSURANCE", "POSTAL", "EDUCATION", "HOSPITALITY", "FINANCIAL", "POLITICAL", "GAMBLING", "LEGAL", "CONSTRUCTION", "NGO", "MANUFACTURING", "GOVERNMENT", "TECHNOLOGY", "COMMUNICATION" ], "enum": [ "PROFESSIONAL", "REAL_ESTATE", "HEALTHCARE", "HUMAN_RESOURCES", "ENERGY", "ENTERTAINMENT", "RETAIL", "TRANSPORTATION", "AGRICULTURE", "INSURANCE", "POSTAL", "EDUCATION", "HOSPITALITY", "FINANCIAL", "POLITICAL", "GAMBLING", "LEGAL", "CONSTRUCTION", "NGO", "MANUFACTURING", "GOVERNMENT", "TECHNOLOGY", "COMMUNICATION" ] }, "SentDmServicesCommonEnumsTcrBrandRelationship": { "type": "string", "description": "", "x-enumNames": [ "BASIC_ACCOUNT", "MEDIUM_ACCOUNT", "LARGE_ACCOUNT", "SMALL_ACCOUNT", "KEY_ACCOUNT" ], "enum": [ "BASIC_ACCOUNT", "MEDIUM_ACCOUNT", "LARGE_ACCOUNT", "SMALL_ACCOUNT", "KEY_ACCOUNT" ] }, "SentDmServicesCommonEntitiesDestinationCountry": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "isMain": { "type": "boolean" } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsCreateProfileRequest": { "type": "object", "example": { "name": "Sales Team", "icon": "https://example.com/sales-icon.png", "description": "Sales department sender profile", "short_name": "SALES", "inherit_tcr_brand": false, "inherit_tcr_campaign": false, "billing_model": "profile", "billing_contact": { "name": "Acme Corp", "email": "billing@acmecorp.com", "phone": "+12025551234", "address": "123 Main Street, New York, NY 10001, US" }, "whatsapp_business_account": { "waba_id": "123456789012345", "phone_number_id": "987654321098765", "access_token": "EAAxxxxxxxxxxxxxxx" }, "brand": { "contact": { "name": "John Smith", "businessName": "Acme Corp", "role": "CEO", "phone": "+12025551234", "email": "john@acmecorp.com", "phoneCountryCode": "1" }, "business": { "legalName": "Acme Corporation LLC", "taxId": "12-3456789", "taxIdType": "us_ein", "entityType": "PRIVATE_PROFIT", "street": "123 Main Street", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US", "url": "https://acmecorp.com", "countryOfRegistration": "US" }, "compliance": { "vertical": "PROFESSIONAL", "brandRelationship": "SMALL_ACCOUNT", "isTcrApplication": true, "phoneNumberPrefix": "+1", "destinationCountries": [ { "id": "US", "isMain": false } ] } }, "payment_details": { "card_number": "4111111111111111", "expiry": "09/27", "cvc": "123", "zip_code": "10001" }, "sandbox": false }, "required": [ "name" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsCreateProfileRequest_Properties", "type": "object", "description": "Request to create a new profile", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Profile name (required)", "maxLength": 100, "minLength": 0, "nullable": false, "example": "Sales Team" }, "icon": { "type": "string", "description": "Profile icon URL (optional)", "nullable": true, "example": "https://example.com/sales-icon.png" }, "description": { "type": "string", "description": "Profile description (optional)", "nullable": true, "example": "Sales department sender profile" }, "short_name": { "type": "string", "description": "Profile short name/abbreviation (optional). Must be 3–11 characters, contain only letters, numbers,\nand spaces, and include at least one letter. Example: \"SALES\", \"Mkt 2\", \"Support1\".", "nullable": true, "example": "SALES" }, "inherit_tcr_brand": { "type": "boolean", "description": "Whether this profile inherits TCR brand from organization (default: false)", "nullable": true, "example": false }, "inherit_tcr_campaign": { "type": "boolean", "description": "Whether this profile inherits TCR campaign from organization (default: false)", "nullable": true, "example": false }, "billing_model": { "type": "string", "description": "Billing model: profile, organization, or profile_and_organization (default: profile).\n- \"organization\": the organization's billing details are used; no profile-level billing info needed.\n- \"profile\": the profile is billed independently; billing_contact is required.\n- \"profile_and_organization\": the profile is billed first with the organization as fallback; billing_contact is required.", "nullable": true, "example": "profile" }, "billing_contact": { "type": "object", "description": "Billing contact for this profile. Required when billing_model is \"profile\" or \"profile_and_organization\".\nIdentifies who receives invoices and who is responsible for payment.", "nullable": true, "example": { "name": "Acme Corp", "email": "billing@acmecorp.com", "phone": "+12025551234", "address": "123 Main Street, New York, NY 10001, US" }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsBillingContactInfo" } ] }, "whatsapp_business_account": { "type": "object", "description": "Direct WhatsApp Business Account credentials for this profile.\nWhen provided, the profile uses its own WhatsApp Business Account instead of inheriting from the organization.\nWhen omitted, the profile inherits the organization's WhatsApp Business Account (requires the organization\nto have completed WhatsApp Embedded Signup).", "nullable": true, "example": { "waba_id": "123456789012345", "phone_number_id": "987654321098765", "access_token": "EAAxxxxxxxxxxxxxxx" }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsWhatsappBusinessAccountCredentials" } ] }, "brand": { "type": "object", "description": "Brand and KYC information for this profile (optional).\nWhen provided, creates the brand associated with this profile.\nCannot be set when inherit_tcr_brand is true.", "nullable": true, "example": { "contact": { "name": "John Smith", "businessName": "Acme Corp", "role": "CEO", "phone": "+12025551234", "email": "john@acmecorp.com", "phoneCountryCode": "1" }, "business": { "legalName": "Acme Corporation LLC", "taxId": "12-3456789", "taxIdType": "us_ein", "entityType": "PRIVATE_PROFIT", "street": "123 Main Street", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US", "url": "https://acmecorp.com", "countryOfRegistration": "US" }, "compliance": { "vertical": "PROFESSIONAL", "brandRelationship": "SMALL_ACCOUNT", "isTcrApplication": true, "phoneNumberPrefix": "+1", "destinationCountries": [ { "id": "US", "isMain": false } ] } }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandData" } ] }, "payment_details": { "type": "object", "description": "Payment card details for this profile (optional).\nAccepted when billing_model is \"profile\" or \"profile_and_organization\".\nNot persisted on our servers — forwarded to the payment processor.", "nullable": true, "example": { "card_number": "4111111111111111", "expiry": "09/27", "cvc": "123", "zip_code": "10001" }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsPaymentDetails" } ] }, "allow_contact_sharing": { "type": "boolean", "description": "Deprecated. Accepted and ignored. Contact and template sharing between sender profiles is gone\n— a profile sees only what it owns, and the organization still sees all of its profiles' contacts and\ntemplates through read-time widening. The four columns behind these flags were dropped by\nM260720120000.\n \nBound rather than dropped so the properties survive on the wire and in a generated client: an\nSDK that assigns them keeps compiling, which is the compatibility this exists for. Deliberately not\nrefused either — a 400 would break an integration that is otherwise working, and the capability\nthey ask for is gone either way. Same rule as SendingPhoneNumberProfileId.\n \nThe read is what makes this survivable: every profile reports all four as false, so a\ncaller that checks its own write can see it did not take. Requests carrying one are logged, so we can\ntell when nobody sends them any more and the fields can go for real.", "deprecated": true, "x-deprecatedMessage": "Contact and template sharing is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null }, "allow_template_sharing": { "type": "boolean", "deprecated": true, "x-deprecatedMessage": "Contact and template sharing is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null }, "inherit_contacts": { "type": "boolean", "deprecated": true, "x-deprecatedMessage": "Contact inheritance is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null }, "inherit_templates": { "type": "boolean", "deprecated": true, "x-deprecatedMessage": "Template inheritance is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null } } } ] }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsBillingContactInfo": { "type": "object", "description": "Billing contact information for a profile.\nRequired when billing_model is \"profile\" or \"profile_and_organization\".", "additionalProperties": false, "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "Full name of the billing contact or company (required)", "minLength": 1, "nullable": false }, "email": { "type": "string", "description": "Email address where invoices will be sent (required)", "format": "email", "minLength": 1, "pattern": "^[^@]+@[^@]+$", "nullable": false }, "phone": { "type": "string", "description": "Phone number for the billing contact (optional)", "nullable": true }, "address": { "type": "string", "description": "Billing address (optional). Free-form text including street, city, state, postal code, and country.", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsWhatsappBusinessAccountCredentials": { "type": "object", "description": "Direct WhatsApp Business Account credentials for a profile.\nUse this when the profile should have its own WhatsApp Business Account instead of inheriting from the organization.\nCredentials must be obtained from Meta Business Manager by creating a System User with\nwhatsapp_business_messaging and whatsapp_business_management scopes.", "additionalProperties": false, "required": [ "waba_id", "access_token" ], "properties": { "waba_id": { "type": "string", "description": "WhatsApp Business Account ID from Meta Business Manager", "minLength": 1, "nullable": false }, "phone_number_id": { "type": "string", "description": "Phone Number ID of an existing number already registered under this WABA in Meta Business Manager.\nOptional — when omitted, a number will be provisioned from our pool and registered in the WABA\nduring the onboarding flow. When provided, the number must already exist in the WABA.", "nullable": true }, "access_token": { "type": "string", "description": "System User access token with whatsapp_business_messaging and\nwhatsapp_business_management permissions. This value is stored securely\nand never returned in API responses.", "minLength": 1, "nullable": false } } }, "SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandData": { "type": "object", "description": "Brand and KYC data grouped into contact, business, and compliance sections", "additionalProperties": false, "required": [ "contact", "compliance" ], "properties": { "contact": { "description": "Contact information for the brand", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandContactInfo" } ] }, "business": { "type": "object", "description": "Business details and address information", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandBusinessInfo" } ] }, "compliance": { "description": "Compliance and TCR-related information", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandComplianceInfo" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandContactInfo": { "type": "object", "description": "Contact information for brand KYC", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Primary contact name (required)", "minLength": 1 }, "businessName": { "type": "string", "description": "Business/brand name", "nullable": true }, "role": { "type": "string", "description": "Contact's role in the business", "nullable": true }, "phone": { "type": "string", "description": "Contact phone number in E.164 format", "nullable": true }, "email": { "type": "string", "description": "Contact email address", "format": "email", "nullable": true }, "phoneCountryCode": { "type": "string", "description": "Contact phone country code (e.g., \"1\" for US)", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandBusinessInfo": { "type": "object", "description": "Business details and address for brand KYC", "additionalProperties": false, "properties": { "legalName": { "type": "string", "description": "Legal business name", "nullable": true }, "taxId": { "type": "string", "description": "Tax ID/EIN number", "nullable": true }, "taxIdType": { "type": "string", "description": "Type of tax ID (e.g., us_ein, ca_bn)", "nullable": true }, "entityType": { "type": "object", "description": "Business entity type", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesEntityType" } ] }, "street": { "type": "string", "description": "Street address", "nullable": true }, "city": { "type": "string", "description": "City", "nullable": true }, "state": { "type": "string", "description": "State/province code", "nullable": true }, "postalCode": { "type": "string", "description": "Postal/ZIP code", "nullable": true }, "country": { "type": "string", "description": "Country code (e.g., US, CA)", "nullable": true }, "url": { "type": "string", "description": "Business website URL", "format": "uri", "nullable": true }, "countryOfRegistration": { "type": "string", "description": "Country where the business is registered", "nullable": true } } }, "SentDmServicesCommonEntitiesEntityType": { "type": "string", "description": "", "x-enumNames": [ "PRIVATE_PROFIT", "PUBLIC_PROFIT", "NON_PROFIT", "SOLE_PROPRIETOR", "GOVERNMENT" ], "enum": [ "PRIVATE_PROFIT", "PUBLIC_PROFIT", "NON_PROFIT", "SOLE_PROPRIETOR", "GOVERNMENT" ] }, "SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandComplianceInfo": { "type": "object", "description": "Compliance and TCR information for brand registration", "additionalProperties": false, "required": [ "vertical", "brandRelationship" ], "properties": { "vertical": { "description": "Business vertical/industry category (required for TCR)", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsTcrVertical" } ] }, "brandRelationship": { "description": "Brand relationship level with TCR (required for TCR)", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsTcrBrandRelationship" } ] }, "isTcrApplication": { "type": "boolean", "description": "Whether this is a TCR (Campaign Registry) application", "nullable": true }, "phoneNumberPrefix": { "type": "string", "description": "Phone number prefix for messaging (e.g., \"+1\")", "nullable": true }, "destinationCountries": { "type": "array", "description": "List of destination countries for messaging", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesDestinationCountry" } }, "notes": { "type": "string", "description": "Additional notes about the business or use case", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsPaymentDetails": { "type": "object", "additionalProperties": false, "required": [ "card_number", "expiry", "cvc", "zip_code" ], "properties": { "card_number": { "type": "string", "description": "Card number (digits only, 13–19 characters)", "minLength": 1, "pattern": "^\\d{13,19}$", "nullable": false }, "expiry": { "type": "string", "description": "Card expiry date in MM/YY format (e.g. \"09/27\")", "minLength": 1, "pattern": "^(0[1-9]|1[0-2])\\/\\d{2}$", "nullable": false }, "cvc": { "type": "string", "description": "Card security code (3–4 digits)", "minLength": 1, "pattern": "^\\d{3,4}$", "nullable": false }, "zip_code": { "type": "string", "description": "Billing ZIP / postal code associated with the card", "minLength": 1, "nullable": false } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsDeleteProfileRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsGetProfileRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsProfileBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsProfileBaseRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfProfilesListResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfilesListResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfilesListResponse": { "type": "object", "description": "The profiles in the organization.", "additionalProperties": false, "properties": { "profiles": { "type": "array", "description": "The profiles on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesResponsesProfileDetailResponse" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsGetProfilesRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsProfileBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsUpdateProfileRequest": { "type": "object", "example": { "name": "Sales Team - Updated", "description": "Updated sales department sender profile", "short_name": "SALES", "billing_model": "organization", "brand": { "contact": { "name": "John Smith", "businessName": "Acme Corp", "role": "CEO", "phone": "+12025551234", "email": "john@acmecorp.com", "phoneCountryCode": "1" }, "business": { "legalName": "Acme Corporation LLC", "taxId": "12-3456789", "taxIdType": "us_ein", "entityType": "PRIVATE_PROFIT", "street": "123 Main Street", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US", "url": "https://acmecorp.com", "countryOfRegistration": "US" }, "compliance": { "vertical": "PROFESSIONAL", "brandRelationship": "SMALL_ACCOUNT", "isTcrApplication": true, "phoneNumberPrefix": "+1", "destinationCountries": [ { "id": "US", "isMain": false } ] } }, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsUpdateProfileRequest_Properties", "type": "object", "description": "Request to update a profile", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Profile name (optional)", "maxLength": 100, "minLength": 0, "nullable": true, "example": "Sales Team - Updated" }, "icon": { "type": "string", "description": "Profile icon URL (optional)", "nullable": true, "example": null }, "description": { "type": "string", "description": "Profile description (optional)", "nullable": true, "example": "Updated sales department sender profile" }, "short_name": { "type": "string", "description": "Profile short name/abbreviation (optional). Must be 3–11 characters, contain only letters, numbers,\nand spaces, and include at least one letter. Example: \"SALES\", \"Mkt 2\", \"Support1\".", "nullable": true, "example": "SALES" }, "inherit_tcr_brand": { "type": "boolean", "description": "Whether this profile inherits TCR brand from organization (optional)", "nullable": true, "example": null }, "inherit_tcr_campaign": { "type": "boolean", "description": "Whether this profile inherits TCR campaign from organization (optional)", "nullable": true, "example": null }, "billing_model": { "type": "string", "description": "Billing model: profile, organization, or profile_and_organization (optional).\n- \"organization\": the organization's billing details are used; no profile-level billing info needed.\n- \"profile\": the profile is billed independently; billing_contact is required.\n- \"profile_and_organization\": the profile is billed first with the organization as fallback; billing_contact is required.", "nullable": true, "example": "organization" }, "billing_contact": { "type": "object", "description": "Billing contact for this profile. Required when billing_model is \"profile\" or \"profile_and_organization\"\nand no billing contact has been configured yet. Identifies who receives invoices and who is responsible for payment.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsBillingContactInfo" } ] }, "sending_phone_number_profile_id": { "type": "string", "description": "Deprecated. Accepted and ignored. Sender borrowing is gone: a profile cannot send from another\nprofile's SMS number. Supplying this changes nothing and the request still succeeds.\n \nBound rather than dropped so the property survives on the wire and in a generated client — an SDK\nthat assigns it keeps compiling, which is the compatibility this exists for. It is deliberately not\nrefused: a 400 here would break an integration that is otherwise working, and the capability it\nasks for is gone either way.\n \nThe trade-off, stated plainly. A caller asking for borrowing is told it succeeded when\nnothing happened. What makes that survivable is the read: sending_phone_number_profile_id comes\nback null on every profile, so a caller that checks its own write can see it did not take. Every\nrequest that carries one is logged, so we can tell when nobody is sending it any more and the field can\ngo for real.\n \nGive the profile a sender of its own instead: POST /v3/channels/sms with the\nx-profile-id header naming it.", "format": "uuid", "deprecated": true, "x-deprecatedMessage": "Sender borrowing is gone. Accepted and ignored; supply a sender of the profile's own with POST /v3/channels/sms and the x-profile-id header.", "nullable": true, "example": null }, "sending_whatsapp_number_profile_id": { "type": "string", "format": "uuid", "deprecated": true, "x-deprecatedMessage": "Sender borrowing is gone. Accepted and ignored; supply a sender of the profile's own with POST /v3/channels/whatsapp and the x-profile-id header.", "nullable": true, "example": null }, "allow_contact_sharing": { "type": "boolean", "description": "Deprecated. Accepted and ignored. Contact and template sharing between sender profiles is gone\n— a profile sees only what it owns, and the organization still sees all of its profiles' contacts and\ntemplates through read-time widening. The four columns behind these flags were dropped by\nM260720120000.\n \nRetired the same way as SendingPhoneNumberProfileId, and for the same reason: the\nproperties stay bound so an SDK that assigns them keeps compiling, and a 400 would break a\nworking integration over a capability that is gone regardless. Every profile reports all four as\nfalse, so a caller that checks its own write can see it did not take.", "deprecated": true, "x-deprecatedMessage": "Contact and template sharing is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null }, "allow_template_sharing": { "type": "boolean", "deprecated": true, "x-deprecatedMessage": "Contact and template sharing is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null }, "inherit_contacts": { "type": "boolean", "deprecated": true, "x-deprecatedMessage": "Contact inheritance is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null }, "inherit_templates": { "type": "boolean", "deprecated": true, "x-deprecatedMessage": "Template inheritance is gone. Accepted and ignored; every profile reads back false.", "nullable": true, "example": null }, "sending_phone_number": { "type": "string", "description": "Direct phone number for SMS sending (optional)", "nullable": true, "example": null }, "whatsapp_phone_number": { "type": "string", "description": "Direct phone number for WhatsApp sending (optional)", "nullable": true, "example": null }, "allow_number_change_during_onboarding": { "type": "boolean", "description": "Whether number changes are allowed during onboarding (optional)", "nullable": true, "example": null }, "brand": { "type": "object", "description": "Brand and KYC information for this profile (optional).\nWhen provided, creates or updates the brand associated with this profile.\nCannot be set when inherit_tcr_brand is true.\nOnce a brand has been submitted to TCR it cannot be modified.", "nullable": true, "example": { "contact": { "name": "John Smith", "businessName": "Acme Corp", "role": "CEO", "phone": "+12025551234", "email": "john@acmecorp.com", "phoneCountryCode": "1" }, "business": { "legalName": "Acme Corporation LLC", "taxId": "12-3456789", "taxIdType": "us_ein", "entityType": "PRIVATE_PROFIT", "street": "123 Main Street", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US", "url": "https://acmecorp.com", "countryOfRegistration": "US" }, "compliance": { "vertical": "PROFESSIONAL", "brandRelationship": "SMALL_ACCOUNT", "isTcrApplication": true, "phoneNumberPrefix": "+1", "destinationCountries": [ { "id": "US", "isMain": false } ] } }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsRequestsBrandData" } ] }, "payment_details": { "type": "object", "description": "Payment card details for this profile (optional).\nAccepted when billing_model is \"profile\" or \"profile_and_organization\".\nNot persisted on our servers — forwarded to the payment processor.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ProfilesRequestsPaymentDetails" } ] } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfNumberLookupResultResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3NumbersResponsesNumberLookupResultResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3NumbersResponsesNumberLookupResultResponse": { "type": "object", "additionalProperties": false, "properties": { "phone_number": { "type": "string" }, "is_valid": { "type": "boolean" }, "carrier_name": { "type": "string", "nullable": true }, "line_type": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "mobile_country_code": { "type": "string", "nullable": true }, "mobile_network_code": { "type": "string", "nullable": true }, "is_ported": { "type": "boolean", "nullable": true }, "is_voip": { "type": "boolean", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3NumbersRequestsPhoneNumberRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCancelMessageV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesCancelMessageV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesCancelMessageV3Response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageResponse" }, { "title": "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesCancelMessageV3Response_Properties", "type": "object", "description": "The cancelled message, in the shape GET /v3/messages/{id} reports it: a cancellation answers with\nthe message it acted on rather than a bespoke acknowledgement, so a client can hand the body to the same\nreader it already has. status is read off the row the claim just wrote, not asserted by the\nendpoint.\n \nIt carries scheduled_at for the same reason ScheduledMessageResponse does, and\nwith the same meaning — the instant the message was being held for. A cancelled message was necessarily\nheld, so the key is present on every real cancellation, and the two endpoints agree on what they report\nabout the same message. It is a property here rather than inheritance because\nScheduledMessageResponse is sealed.", "additionalProperties": false, "properties": { "scheduled_at": { "type": "string", "description": "The send time that was called off, in UTC — the scheduled_at the message was being\n held for, whether you set it or the recipient's quiet hours moved it there. Omitted only for a held\n message that carried no recorded instant.", "format": "date-time", "nullable": true } } } ] }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageResponse": { "type": "object", "description": "Message response for v3 API — same shape as v2 with snake_case JSON conventions.\n \nThe shape of a message that was sent immediately: it never has a scheduled_at key. A message that is\nor was held for a later instant is a ScheduledMessageResponse, and the endpoint decides which of\nthe two to answer with. From\nalways returns this type.", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "phone": { "type": "string" }, "phone_international": { "type": "string" }, "region_code": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "nullable": true }, "template_name": { "type": "string", "nullable": true }, "template_category": { "type": "string", "nullable": true }, "channel": { "type": "string" }, "message_body": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesMessageBody" } ] }, "status": { "type": "string" }, "direction": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "price": { "type": "number", "format": "decimal", "nullable": true }, "active_contact_price": { "type": "number", "format": "decimal", "nullable": true }, "events": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageEventV3" } }, "reason_code": { "type": "string", "description": "Why the message is at its current status, as a stable platform code such as\nDELIVERY_007, BUSINESS_003 or\nDELIVERY_003. Present when the current status is FAILED, FILTERED or\nBLOCKED and the lifecycle was loaded; omitted otherwise. Switch on this rather than on\nreason: the code is stable, the wording may be improved. It is the platform's\nclassification of the outcome, never a carrier or vendor code.", "nullable": true }, "reason": { "type": "string", "description": "A human-readable sentence for reason_code, for example \"Insufficient balance\". Omitted whenever\nreason_code is.", "nullable": true } } }, "SentDmServicesCommonEntitiesMessageBody": { "type": "object", "description": "Structured message body format for database storage.\nPreserves channel-specific components (header, header media, body, footer, buttons, MMS subject\nand media).\n \nPersisted as the messageBody jsonb column on Messages. Every write path goes\nthrough MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope shape is\nstable regardless of channel or status. Anything that rebuilds this object field by field — the\nfour IMessageBodyStrategy implementations and MessageUtils.BuildSegmentBody — has to\ncarry every member, or that member is silently dropped on whichever path forgot it.", "additionalProperties": false, "properties": { "header": { "type": "string", "nullable": true }, "content": { "type": "string" }, "footer": { "type": "string", "nullable": true }, "buttons": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesMessageButton" } }, "subject": { "type": "string", "description": "MMS subject line. Null on every other channel.", "nullable": true }, "media": { "type": "array", "description": "MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on every other\nchannel.\n \nPersisted rather than derived because a resend and a curfew release rebuild the send from\nthe stored row — MessageReplayCommandBuilder reads templateId and\ntemplateVariables and nothing else — so media that lives only on the original request\nwould silently turn a replayed MMS into a text message.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesMessageMedia" } }, "headerMedia": { "type": "object", "description": "The asset delivered on a media header, when the template has one.\n \nDeliberately a separate field rather than part of Header: that is rendered\n*text* which RcsChannelOrchestrator prepends as a line of the body, so putting a URL\nthere would leak a raw link into RCS and SMS transcripts. Keeping the asset out of the text\nmeans display surfaces can show the image while every text path stays clean.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEntitiesMessageHeaderMedia" } ] } } }, "SentDmServicesCommonEntitiesMessageButton": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string" }, "text": { "type": "string", "nullable": true }, "value": { "type": "string" }, "postbackData": { "type": "string", "nullable": true } } }, "SentDmServicesCommonEntitiesMessageMedia": { "type": "object", "description": "One attachment on a message, in either direction — and in both, a URL somebody else hosts.\n \nOutbound: the customer supplied a public URL and we handed it to the carrier.\nInbound: the carrier hosts the file and we record where. sent.dm never holds the bytes, so\nthere is no key, no expiry bookkeeping and nothing minted per read — what is stored is what is\nserved.\n \nAn inbound link expires on the carrier's own schedule and is unauthenticated. That is the\ncustomer's to manage, and it is documented where they will see it rather than only here — a\nrecipient who needs an attachment to outlive that window copies it on receipt.\n \nStoring a presigned URL is the specific mistake this shape still avoids:\nM260826130000 and M260826140000 exist because RCS assets were stored as signed URLs\nand went stale. Nothing here is signed.", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "Where the file lives. Outbound: the URL the customer gave us and the carrier fetched. Inbound:\nthe URL the carrier hosts it at, relayed unchanged.", "nullable": true }, "mediaType": { "type": "string", "description": "One of MmsMediaTypes when the content type is known. Advisory — a reader should\n trust the fetched object's own Content-Type.", "nullable": true }, "mimeType": { "type": "string", "description": "Content type as the provider declared it. Null when it declared none.", "nullable": true }, "sizeBytes": { "type": "integer", "description": "Size as the provider declared it. Never measured here — nothing downloads the file.", "format": "int64", "nullable": true }, "sourceHashSha256": { "type": "string", "description": "Inbound only: the SHA-256 the provider declared alongside the attachment, when it declared one.\nRelayed to the customer so they can verify what they fetch matches what the carrier said it sent.\nIt is the only integrity signal available on an attachment nobody here has read.", "nullable": true } } }, "SentDmServicesCommonEntitiesMessageHeaderMedia": { "type": "object", "description": "The media asset that rode a message's header, recorded as sent.", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "\"image\", \"video\" or \"document\" — taken from the header's media variable." }, "url": { "type": "string", "description": "The https URL the caller supplied for this send. Never the template's stored\nprops.sample, which is Meta's expiring header_handle rather than what was delivered." } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageEventV3": { "type": "object", "description": "Represents a status change event in a message's lifecycle (v3)", "additionalProperties": false, "required": [ "status", "timestamp" ], "properties": { "status": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "reason_code": { "type": "string", "description": "Why the message reached this status, as a stable platform code such as DELIVERY_007.\nPresent on FAILED, FILTERED and BLOCKED events; omitted on every status that needs no\nexplanation. Same wire name and vocabulary as on the activities list and the webhook.", "nullable": true }, "reason": { "type": "string", "description": "A human-readable sentence for reason_code. Omitted whenever reason_code is.", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesRequestsCancelMessageV3Request": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfMessageActivitiesResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageActivitiesResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageActivitiesResponse": { "type": "object", "description": "Response for GET /messages/{id}/activities", "additionalProperties": false, "properties": { "message_id": { "type": "string", "description": "The message ID these activities belong to", "format": "uuid" }, "activities": { "type": "array", "description": "List of activity events ordered by most recent first", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageActivityResponse" } }, "pagination": { "description": "Pagination metadata. Present even though this endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageActivityResponse": { "type": "object", "description": "A single message activity event for v3 API.\n \nThe activity list mixes statuses, so unlike a message it is one shape rather than two: a SCHEDULED\nentry carries scheduled_at, and every other entry has no such key.", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SCHEDULED, SENT, DELIVERED, READ, FAILED.\nInbound (from contact): RECEIVED (terminal)." }, "description": { "type": "string", "description": "Human-readable description of the activity" }, "from": { "type": "string", "description": "Sender phone number for this activity (the customer's sending number for outbound, the external sender for inbound). Null when not reported by the provider.", "nullable": true }, "timestamp": { "type": "string", "description": "When this activity occurred", "format": "date-time" }, "scheduled_at": { "type": "string", "description": "SCHEDULED and CANCELLED activities only, in UTC: on a SCHEDULED entry, when the held\nmessage will be released for delivery; on a CANCELLED entry, the instant that was called off. Same\nwire name as on the send response, the message and the webhook. Omitted on every other activity. A message\nthat quiet hours moved at release has two SCHEDULED entries, each carrying the instant as it stood at\nthat moment.", "format": "date-time", "nullable": true }, "reason_code": { "type": "string", "description": "Why the message reached this status, as a stable platform code such as DELIVERY_007\nor BUSINESS_003. Present on FAILED, FILTERED and BLOCKED activities;\nomitted on every status that needs no explanation. Switch on this rather than on reason: the code\nis stable, the wording may be improved. Same wire name and vocabulary as on the message and the webhook.", "nullable": true }, "reason": { "type": "string", "description": "A human-readable sentence for reason_code, for example \"The recipient is not registered on this channel\"\nOmitted whenever reason_code is.", "nullable": true }, "price": { "type": "string", "description": "Channel cost for this activity (e.g., SMS/WhatsApp provider cost), formatted to 4 decimal places.", "nullable": true }, "active_contact_price": { "type": "string", "description": "Active contact markup applied on top of the channel cost, formatted to 4 decimal places.", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesRequestsGetMessageActivitiesRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfMessageResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesRequestsGetMessageRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfResendMessageV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesResendMessageV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesResendMessageV3Response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesSendMessageResponse" } ] }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesSendMessageResponse": { "type": "object", "description": "The result of a multi-recipient send.\n \nDeclared here rather than in the service layer. POST /v3/messages used to publish\nMessageSendResult — a type in Common.Services.Messaging.Contracts — so the public contract was\nwhatever the send service happened to return, and changing that service for an internal reason changed the\nAPI. The service keeps its result; this is what a caller sees, and the mapping between them is a decision the\nendpoint makes.\n \nThe shape of an immediate send: it never has a scheduled_at key. A send that carried\nscheduled_at is a ScheduledSendMessageResponse, and the endpoint decides which of the two to\nanswer with. From always returns this type.", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "QUEUED: the batch is accepted. A request that carried scheduled_at is QUEUED\n here too; each message moves to SCHEDULED once it is held, as GET /v3/messages/{id} and the\n message.scheduled webhook report." }, "template_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageRecipientResponse" } } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageRecipientResponse": { "type": "object", "description": "What one recipient of a send got, as the API reports it.", "additionalProperties": false, "properties": { "message_id": { "type": "string", "description": "Identifier for tracking this recipient's message.", "format": "uuid" }, "to": { "type": "string", "description": "Phone number in E.164 format." }, "channel": { "type": "string", "description": "Channel this message will be sent on — sms, whatsapp — or null to auto-detect.", "nullable": true }, "body": { "type": "string", "description": "Resolved template body for this recipient's channel, or null when the channel is auto-detected.", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesRequestsResendMessageV3Request": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSendMessageResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesSendMessageResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3MessagesRequestsSendMessageV3Request": { "type": "object", "example": { "to": [ "+14155551234", "+14155555678" ], "channel": [ "sms", "whatsapp" ], "template": { "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "order_confirmation", "parameters": { "name": "John Doe", "order_id": "12345" } }, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3MessagesRequestsSendMessageV3Request_Properties", "type": "object", "description": "Request to send a message (v3 SDK-style with multi-recipient and multi-channel broadcast)", "additionalProperties": false, "properties": { "to": { "type": "array", "description": "List of recipient phone numbers in E.164 format (multi-recipient fan-out)", "example": [ "+14155551234", "+14155555678" ], "items": { "type": "string" } }, "channel": { "type": "array", "description": "Channels to broadcast on, e.g. [\"whatsapp\", \"sms\"].\nEach channel produces a separate message per recipient.\n\"sent\" = auto-detect.\nDefaults to [\"sent\"] (auto-detect) if omitted.", "nullable": true, "example": [ "sms", "whatsapp" ], "items": { "type": "string" } }, "template": { "type": "object", "description": "Template reference (by id or name, with optional parameters).\nOptional — provide either Template or Message.", "nullable": true, "example": { "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "order_confirmation", "parameters": { "name": "John Doe", "order_id": "12345" } }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesTemplatesContractsTemplateV3Ref" } ] }, "text": { "type": "string", "description": "Plain-text (free-form) message body. Provide either Template or this.", "nullable": true, "example": null }, "media_urls": { "type": "array", "description": "Attachments for this send, as publicly fetchable https URLs. Used by the MMS channel and ignored\nby every other one.\n \nSupplying these replaces the media on the template's mms body rather than\nadding to it, so a template can hold a default creative while a caller still sends something\nrecipient-specific.\n \nTheir presence is also what makes a message eligible for MMS on an auto-detect send: a\nmessage with nothing attached is delivered as SMS, because an MMS with no media is a more\nexpensive text message.\n \nThe recipient's carrier fetches each URL after the send is accepted, so it must stay\npublicly reachable — a link that expires, or one behind auth, arrives as a failed message.", "nullable": true, "example": null, "items": { "type": "string" } }, "subject": { "type": "string", "description": "Subject line for this send, overriding the template's. MMS only; ignored on every other channel.\nMost handsets render it above the body, some ignore it entirely.", "nullable": true, "example": null }, "scheduled_at": { "type": "string", "description": "Optional future send time as an ISO-8601 timestamp with an explicit UTC offset, e.g.\n2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A value without an offset is rejected\n(400) rather than read in the server's zone. The offset only fixes the instant: it is stored and echoed\nin UTC as scheduled_at. Omit to send now. Must be at least one minute ahead and at most 30 days\nahead. Accepted messages report SCHEDULED and are released for delivery at this time. Quiet hours,\nbalance and template approval are evaluated at release, not at acceptance: a message whose time\nfalls inside a recipient's protected quiet-hours window is moved to the next allowed time and a second\nmessage.scheduled webhook reports the new scheduled_at.", "format": "date-time", "nullable": true, "example": null } } } ] }, "SentDmServicesCommonServicesTemplatesContractsTemplateV3Ref": { "type": "object", "description": "SDK-style template reference: resolve by ID or by name, with optional parameters.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Template ID (mutually exclusive with name)", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Template name (mutually exclusive with id)", "nullable": true }, "parameters": { "type": "object", "description": "Template variable parameters for personalization, keyed by variable name.\n \nEvery variable the template declares is required; GET /v3/templates/{id} lists them.\nSupplying a key the template does not declare is ignored.\n \nMedia headers. A template whose header is an image (designed in WhatsApp Manager and\nimported into Sent) declares a reserved header_image key. Its value is a publicly\nreachable https URL that Meta fetches at send time — Sent does not host the asset, and the\nsample approved with the template is not reused. The key is derived from the header's media type,\nso header_video and header_document follow the same shape when those formats ship.\n \n\"parameters\": {\n \"header_image\": \"https://cdn.example.com/banner.jpg\",\n \"name\": \"John Doe\"\n}", "nullable": true, "additionalProperties": { "type": "string" } } } }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfConversationMessagesListResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ConversationsResponsesConversationMessagesListResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ConversationsResponsesConversationMessagesListResponse": { "type": "object", "description": "A paginated list of messages — used by both conversation read endpoints.", "additionalProperties": false, "properties": { "messages": { "type": "array", "description": "The messages on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3MessagesResponsesMessageResponse" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ConversationsRequestsGetConversationByIdRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3ConversationsRequestsGetConversationsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsResponsesContactResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ContactsResponsesContactResponse": { "type": "object", "description": "Contact response for v3 API\nUses snake_case for JSON property names", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique identifier for the contact", "format": "uuid" }, "customer_id": { "type": "string", "description": "Which customer owns this — the key's own, or the profile named in x-profile-id. Says whose\nresource this is, which the resource's own id does not.", "format": "uuid" }, "phone_number": { "type": "string", "description": "Phone number in original format" }, "format_e164": { "type": "string", "description": "Phone number in E.164 format (e.g., +1234567890)" }, "format_international": { "type": "string", "description": "Phone number in international format (e.g., +1 234-567-890)" }, "format_national": { "type": "string", "description": "Phone number in national format (e.g., (234) 567-890)" }, "format_rfc": { "type": "string", "description": "Phone number in RFC 3966 format (e.g., tel:+1-234-567-890)" }, "country_code": { "type": "string", "description": "Country calling code (e.g., 1 for US/Canada)" }, "region_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g., US, CA, GB)" }, "available_channels": { "type": "string", "description": "Comma-separated list of available messaging channels (e.g., \"sms,whatsapp\")" }, "default_channel": { "type": "string", "description": "Default messaging channel to use (e.g., \"sms\" or \"whatsapp\")" }, "opt_out": { "type": "boolean", "description": "Whether the contact has opted out of messaging. Single source of truth — opt-out is\nper-contact, not per-channel." }, "is_inherited": { "type": "boolean", "description": "Always false. Contacts are no longer shared or inherited between sender profiles — a\nprofile sees only the contacts it owns. Retained so existing v3 clients reading\nis_inherited keep deserializing; it carries no information.", "deprecated": true, "x-deprecatedMessage": "Always false. Contacts are no longer shared or inherited between sender profiles." }, "created_at": { "type": "string", "description": "When the contact was created", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the contact was last updated", "format": "date-time", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsCreateContactRequest": { "type": "object", "example": { "phone_number": "+1234567890", "sandbox": false }, "required": [ "phone_number" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsCreateContactRequest_Properties", "type": "object", "description": "Request to create a new contact", "additionalProperties": false, "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string", "description": "Phone number of the contact to create", "minLength": 1, "nullable": false, "example": "+1234567890" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsDeleteContactRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsGetContactByIdRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactMessageSummaryResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsResponsesContactMessageSummaryResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ContactsResponsesContactMessageSummaryResponse": { "type": "object", "additionalProperties": false, "properties": { "contact_id": { "type": "string", "format": "uuid" }, "message_count": { "type": "integer", "format": "int32" }, "first_message_at": { "type": "string", "format": "date-time", "nullable": true }, "last_message_at": { "type": "string", "format": "date-time", "nullable": true }, "channels_used": { "type": "array", "items": { "type": "string" } }, "channel_scores": { "type": "array", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsResponsesChannelScoreResponse" } } } }, "SentDmServicesEndpointsCustomerAPIv3ContactsResponsesChannelScoreResponse": { "type": "object", "additionalProperties": false, "properties": { "channel": { "type": "string" }, "success_score": { "type": "integer", "description": "Percentage (0-100) of messages on this channel that reached a successful terminal state: SENT/DELIVERED/READ for outbound, RECEIVED for inbound.", "format": "int32" }, "fail_score": { "type": "integer", "description": "Percentage (0-100) of messages on this channel that ended in FAILED.", "format": "int32" } } }, "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsGetContactMessageSummaryRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfContactsListResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsResponsesContactsListResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ContactsResponsesContactsListResponse": { "type": "object", "description": "A paginated list of contacts.", "additionalProperties": false, "properties": { "contacts": { "type": "array", "description": "The contacts on this page.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ContactsResponsesContactResponse" } }, "pagination": { "description": "Pagination metadata. Present even when the endpoint does not page, describing the single page it\nreturned, so a caller can loop over any v3 list without knowing which ones paginate.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsGetContactsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsUpdateContactRequest": { "type": "object", "example": { "default_channel": "whatsapp", "opt_out": false, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ContactsRequestsUpdateContactRequest_Properties", "type": "object", "description": "Request to update a contact", "additionalProperties": false, "properties": { "default_channel": { "type": "string", "description": "Default messaging channel: \"sms\" or \"whatsapp\"", "nullable": true, "example": "whatsapp" }, "opt_out": { "type": "boolean", "description": "Whether the contact has opted out of messaging. Single source of truth — opt-out is\nper-contact, not per-channel.", "nullable": true, "example": false } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfComplianceRequirementsResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceRequirementsResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceRequirementsResponse": { "type": "object", "description": "Everything a market expects of a sender, for one channel, country and sender type.", "additionalProperties": false, "properties": { "channel": { "type": "string", "description": "Channel the requirements apply to — sms, whatsapp or rcs.\n \nEchoed so the document says which channel it describes. It always described one: setup's\nlast step is a specific channel path, and every type is an SMS sender type — but a caller reading\nthe payload had to infer that from the path to know it." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country the requirements apply to." }, "type": { "type": "string", "description": "Sender type the requirements apply to.\n \nNon-nullable while sms is the only channel answered here, because it is the only channel\nwhose senders have a type — the day another one is answered, this becomes nullable along with it. Not\nnullable in advance: nothing can emit null today, and publishing a shape the API never sends is the\nsame mistake as publishing a field it does not have." }, "required": { "type": "boolean", "description": "Whether this market demands anything before a sender can be registered. When false, the\ncompliance array may be omitted entirely and the profile is ready once provisioned." }, "sender_id_pattern": { "type": "string", "description": "Pattern the sender's own value must match, where the market dictates one — alphanumeric\nsender ids and short codes. Null when the value is carrier-assigned.", "nullable": true }, "requirements": { "type": "array", "description": "Values to supply in compliance. Empty when the market demands nothing. Values Sent\nsupplies on your behalf are never listed, and neither are ones it derives from what you send.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceRequirementResponse" } }, "setup": { "type": "array", "description": "The calls that set this market up, in the order they have to be made, each carrying a body that can be\nsent as it stands.\n \nThis is the answer to \"what do I actually do\". Requirements describes each value\nthe market wants; this assembles those descriptions into the requests that supply them, so a caller — or an\nagent acting for one — copies a body out and sends it rather than building one from a table.\n \nThe last step is always the channel itself, and it is where the regime's own values are supplied.\nThe one before it, where there is one, is the brand a registering market files against — so it is a step of\nits own and the channel call refuses until it exists. A market that registers with nobody has one step.", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceSetupStep" } } } }, "SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceRequirementResponse": { "type": "object", "description": "One value a market expects in a channel call's compliance map.", "additionalProperties": false, "properties": { "key": { "type": "string", "description": "Key to use in the compliance map." }, "type": { "type": "string", "description": "Value type: string, number, boolean, date, enum,\nobject, array or document." }, "format": { "type": "string", "description": "Refinement of type where the market demands a specific shape, e.g. e164,\nurl, email, iso3166_alpha2, csv_keywords.", "nullable": true }, "required": { "type": "boolean", "description": "Whether the market always demands this value." }, "required_when": { "type": "string", "description": "Condition that makes this value required, when it is only required in some cases —\ne.g. brand.entity_type == PUBLIC_PROFIT. Evaluate it against your own payload to know\nwhether to collect the field.", "nullable": true }, "options": { "type": "array", "description": "Accepted values, when the type is an enum or a constrained array.", "nullable": true, "items": { "type": "string" } }, "min_length": { "type": "integer", "description": "Shortest acceptable value, where the market sets one. TCR refuses a consent narrative under 40\ncharacters, and finding that out at submission time is the round trip this exists to save.", "format": "int32", "nullable": true }, "max_items": { "type": "integer", "description": "Most entries this value accepts, where the market caps it.", "format": "int32", "nullable": true }, "item_fields": { "type": "array", "description": "Shape of each entry, when this requirement is a list of objects rather than of scalars.\n \nThe compliance value stays null in the setup body like every other blank —\na body that carries a half-filled object is one the endpoint refuses, which would break the promise\nthat the published body can be sent as it stands. So the shape is described here instead, and each\nentry the caller composes has these keys.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceRequirementResponse" } }, "label": { "type": "string", "description": "Human label, suitable for a form field.", "nullable": true }, "notes": { "type": "string", "description": "Why the market asks for this.", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceSetupStep": { "type": "object", "description": "One call to make, with a body that can be sent as it stands.\n \nThe steps are ordered and the order is load-bearing: a channel that registers with a regime is filed\nagainst a brand, so the brand call comes first and the channel call refuses until it has been made. Doing them\nin order is the whole of setting a market up.", "additionalProperties": false, "properties": { "step": { "type": "integer", "description": "Position in the sequence, from 1. Steps must be performed in this order.", "format": "int32" }, "resource": { "type": "string", "description": "What this call sets up: brand or channel." }, "method": { "type": "string" }, "path": { "type": "string", "description": "Path to call. Add the x-profile-id header with an organization key to make the same call for one of\nyour sender profiles — there is no separate path for that." }, "why": { "type": "string", "description": "Why this market needs this call, in one sentence." }, "body": { "description": "The request body, with every key this market wants already present and the values left blank. Send it as\nit stands and the response names each blank that still has to be filled.", "nullable": true }, "attachments": { "type": "array", "description": "Files to attach as multipart, when this call takes any. Absent when it does not.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceAttachmentTemplate" } } } }, "SentDmServicesEndpointsCustomerAPIv3ComplianceResponsesComplianceAttachmentTemplate": { "type": "object", "description": "A file this market wants, and the multipart field to send it as.\n \nSeparate from compliance because a file is not JSON: the channel call accepts multipart, and\neach file is named after the key it satisfies. Listing documents among the JSON entries would describe a\nrequest nobody could send.", "additionalProperties": false, "properties": { "field_name": { "type": "string", "description": "The multipart field name to attach the file under." }, "label": { "type": "string", "nullable": true }, "required": { "type": "boolean" } } }, "SentDmServicesEndpointsCustomerAPIv3ComplianceRequestsGetComplianceRequirementsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfRcsAgentState": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsRcsAgentState" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddRcsChannelRequest": { "type": "object", "example": { "display_name": "Example Retail", "description": "Order and delivery notifications for Example Retail customers.", "agent_use_case": "NOTIFICATIONS", "brand_name": "Example Retail", "privacy_policy_url": "https://example.com/privacy", "terms_and_conditions_url": "https://example.com/terms", "website_url": "https://example.com", "brand_color": "#1a73e8", "logo_url": "https://example.com/assets/logo-224x224.png", "banner_url": "https://example.com/assets/banner-1440x448.png", "brand_phone_number": "+12125550100", "customer_support_phone_number": "+18005550100", "brand_email": "hello@example.com", "customer_support_email": "support@example.com", "contact_name_and_title": "Jane Smith, Head of Marketing", "company_ein": "12-3456789", "entity_type": "PRIVATE_PROFIT", "official_address": { "street": "123 Main St", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" }, "brief_company_description": "Example Retail sells home goods across the US and ships to 48 states.", "opt_in_process_description": "Customers opt in at checkout by checking the SMS/RCS notifications box.", "start_message": "Welcome to Example Retail! Reply HELP for help or STOP to opt out.", "help_message": "For help, visit https://example.com/support or call 1-800-555-0100.", "stop_message": "You have been unsubscribed from Example Retail notifications.", "sample_messages": [ "Your order #12345 has shipped and will arrive tomorrow." ], "sandbox": false }, "required": [ "description", "agent_use_case", "display_name", "brand_color", "brand_name", "privacy_policy_url", "terms_and_conditions_url", "website_url", "logo_url", "banner_url", "brand_email", "customer_support_email", "brand_phone_number", "customer_support_phone_number", "contact_name_and_title", "company_ein", "entity_type", "official_address", "brief_company_description", "opt_in_process_description", "start_message", "help_message", "stop_message", "sample_messages" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddRcsChannelRequest_Properties", "type": "object", "description": "The RCS Agent Order Form, as a customer sends it.\n \nThe same form the admin side takes — POST /customers/{customerId}/rcs-senders and\nCreateRcsSenderRequest — rather than a reduced one. It was three fields for a while, which recorded\na hosting region and a logo into a config blob and left everything a carrier actually asks about to be\ncollected by hand later. A customer can answer all of this; nobody else can answer any of it.\n \nNamed in this API's own casing. Every v3 body is snake_case, so the fields are mapped rather\nthan shared: logo_url, banner_url, brand_color.\n \nNo customer_id. The internal form carries one because an admin names the customer it\nis acting for; here the key does, and accepting one from the body would let a caller file an agent against\nsomebody else.\n \nAll fields except opt_in_screenshot_url are required. The full order form must be\nsubmitted in one go so the carrier review has everything it needs.", "additionalProperties": false, "properties": { "display_name": { "type": "string", "description": "The name the agent shows in the messaging client.", "maxLength": 200, "nullable": false, "example": "Example Retail" }, "description": { "type": "string", "description": "What the agent is for, shown to recipients. Capped by the carriers, not by us.", "maxLength": 100, "minLength": 0, "nullable": false, "example": "Order and delivery notifications for Example Retail customers." }, "agent_use_case": { "type": "string", "description": "Which kind of traffic the agent carries. One of the accepted use cases; the error names the set.", "minLength": 1, "nullable": false, "example": "NOTIFICATIONS", "enum": [ "VERIFICATION", "NOTIFICATIONS", "MARKETING", "MULTI_USE" ], "x-enum-descriptions": { "VERIFICATION": "One-time passcodes and identity checks. Expects no reply, and is held to the strictest delivery review.", "NOTIFICATIONS": "Transactional updates the recipient asked for — orders, deliveries, appointments, account activity.", "MARKETING": "Promotional content. Requires the clearest opt-in evidence of the four, because the carriers review consent hardest here.", "MULTI_USE": "More than one of the above from a single agent. Vetted against the strictest use case it covers, so declare it only if you genuinely need one agent to do several jobs." } }, "brand_name": { "type": "string", "description": "The brand this agent presents over RCS.\n \nNot taken from your compliance.brand: a business may present a different brand on RCS than\nthe one its 10DLC registration is filed against, and the carriers vet this one.", "nullable": false, "example": "Example Retail" }, "privacy_policy_url": { "type": "string", "description": "Required by US carriers. Must be an absolute http(s) URL they can fetch.", "format": "uri", "nullable": false, "example": "https://example.com/privacy" }, "terms_and_conditions_url": { "type": "string", "format": "uri", "nullable": false, "example": "https://example.com/terms" }, "website_url": { "type": "string", "description": "The brand's own site.", "format": "uri", "nullable": false, "example": "https://example.com" }, "brand_color": { "type": "string", "description": "Primary brand colour, as #RRGGBB. Three-digit shorthand is refused: the value is submitted\nverbatim, so two spellings of one colour is only a way for the stored value to disagree with the form.", "pattern": "^#[0-9A-Fa-f]{6}$", "nullable": false, "example": "#1a73e8" }, "logo_url": { "type": "string", "description": "Publicly reachable logo. It has to be fetchable without authentication at review time, so a URL behind\na login passes this call and fails the review.", "format": "uri", "nullable": false, "example": "https://example.com/assets/logo-224x224.png" }, "banner_url": { "type": "string", "format": "uri", "nullable": false, "example": "https://example.com/assets/banner-1440x448.png" }, "brand_phone_number": { "type": "string", "description": "The brand's own number. Also becomes the agent's canonical sending number for routing, which is why it\nis normalised to E.164 rather than stored as sent.", "nullable": false, "example": "+12125550100" }, "customer_support_phone_number": { "type": "string", "nullable": false, "example": "+18005550100" }, "brand_email": { "type": "string", "format": "email", "nullable": false, "example": "hello@example.com" }, "customer_support_email": { "type": "string", "format": "email", "nullable": false, "example": "support@example.com" }, "contact_name_and_title": { "type": "string", "nullable": false, "example": "Jane Smith, Head of Marketing" }, "company_ein": { "type": "string", "nullable": false, "example": "12-3456789" }, "entity_type": { "type": "string", "nullable": false, "example": "PRIVATE_PROFIT" }, "official_address": { "nullable": false, "example": { "street": "123 Main St", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" }, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsRcsAddress" } ] }, "brief_company_description": { "type": "string", "nullable": false, "example": "Example Retail sells home goods across the US and ships to 48 states." }, "opt_in_process_description": { "type": "string", "description": "How recipients opt in, in prose. The carriers read this one.", "nullable": false, "example": "Customers opt in at checkout by checking the SMS/RCS notifications box." }, "opt_in_screenshot_url": { "type": "string", "description": "A screenshot of the opt-in, as a publicly fetchable URL.", "format": "uri", "nullable": true, "example": null }, "start_message": { "type": "string", "nullable": false, "example": "Welcome to Example Retail! Reply HELP for help or STOP to opt out." }, "help_message": { "type": "string", "nullable": false, "example": "For help, visit https://example.com/support or call 1-800-555-0100." }, "stop_message": { "type": "string", "nullable": false, "example": "You have been unsubscribed from Example Retail notifications." }, "sample_messages": { "type": "array", "description": "Examples of what the agent will send, for the review.", "nullable": false, "example": [ "Your order #12345 has shipped and will arrive tomorrow." ], "items": { "type": "string" } } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSmsMarketState": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSmsMarketState" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddSmsChannelRequest": { "type": "object", "example": { "country": "US", "number_type": "TEN_DLC", "area_codes": [ "415", "628" ], "compliance": { "brand": { "inherit": false, "legal_name": "Example Retail Inc", "entity_type": "PRIVATE_PROFIT", "country": "US", "website": "https://example.com" }, "campaign": { "inherit": false, "description": "Order and delivery updates for customers who opted in at checkout.", "message_flow": "Customers opt in at checkout by checking a consent box.", "use_cases": [ { "use_case": "DELIVERY_NOTIFICATION", "sample_messages": [ "Your order #1234 has shipped and will arrive tomorrow." ] } ] } }, "sandbox": false }, "required": [ "country", "number_type" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddSmsChannelRequest_Properties", "type": "object", "description": "Adds an SMS market — a country and a sender type — to a customer.\n \nThe same fields channels.sms takes on POST /v3/sender-profiles, because it is the same\nwork: create is \"make the profile, then add its first market\", and both run one provisioning path.\ncompliance is top-level and answers for the market this request concerns, exactly as it does\nthere.", "additionalProperties": false, "required": [ "number_type" ], "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country the sender operates in.", "maxLength": 2, "minLength": 1, "pattern": "^[A-Za-z]{2}$", "nullable": false, "example": "US" }, "number_type": { "type": "string", "description": "Sender type. Decides the provisioning flow and what compliance is asked for.\n \n[Required] so the published document says so. The validator has always demanded it, but\nrequiredness reached the schema by matching a rule to a property name — which works for country,\nwhose wire name is its camel-cased C# name, and silently does not for number_type. A client\ngenerating a request from our OpenAPI therefore sent what the document called sufficient and was\nanswered 400.", "minLength": 1, "nullable": false, "example": "TEN_DLC", "enum": [ "LOCAL", "TOLL_FREE", "SHORT_CODE", "ALPHANUMERIC", "TEN_DLC", "MOBILE", "10DLC" ], "x-enum-descriptions": { "LOCAL": "A geographic number for the country. The ordinary choice: recognisable to recipients, and available almost everywhere.", "TOLL_FREE": "A toll-free number. High throughput and no per-country registration, but US toll-free traffic goes through its own verification.", "SHORT_CODE": "A short code — five or six digits, leased rather than provisioned. Highest throughput, longest lead time, and the most expensive.", "ALPHANUMERIC": "A sender name rather than a number, up to 11 characters. Recipients cannot reply. Not available in every country, and several require it to be pre-registered with documents.", "TEN_DLC": "A US 10-digit long code registered with The Campaign Registry. The only sender type that registers with a compliance regime, so it is the only one whose market declares `compliance.brand` and `compliance.campaign`.", "MOBILE": "A mobile number. Where a country distinguishes it from a landline, some carriers treat mobile traffic differently.", "10DLC": "The industry's spelling of `TEN_DLC`, accepted so an integrator can send the term it knows. Resolves to the same market." } }, "sender_value": { "type": "string", "description": "The sender's identity where the caller chooses it. Required when number_type is\nALPHANUMERIC; optional for carrier-assigned types, which are procured afterwards.", "minLength": 1, "nullable": true, "example": null }, "area_codes": { "type": "array", "description": "The area codes to put this sender in, in your own order of preference, e.g. [\"415\", \"628\"]\nfor the US or [\"20\"] for London. Omit it and a number is claimed anywhere in the country.\n \nOrdered, and the order is the request. The claim tries each code in turn and stops at the\nfirst that yields a number. Nothing sorts the list and a code listed twice is refused.\n \nOne to fifty entries, each the area code as digits: 415, with the trunk prefix as\n020, or with the country's dialing prefix as +1415 (all are stored as the bare code). A\ndialing prefix from a different country than country is refused. Each code is checked against\nthe country's numbering plan: it must start real local or mobile numbers there, so toll-free and\npremium ranges, service codes and another country's codes are refused with a reason.\n \nLOCAL senders in any country, and US TEN_DLC senders. No other sender type\nhas a geographic area code, and the list is refused with one rather than accepted and dropped.\n \nHonoured exactly or not at all. Ask for 415 and you get a 415 number or you\nget none, never a neighbouring code you did not name. A miss leaves the market with no sender yet and\nthe codes recorded on it, so it is filled when stock appears rather than filled now from somewhere else.\nMany countries outside North America require address or business documents before a local number can\nbe bought, which can delay or prevent the fill.", "nullable": true, "example": [ "415", "628" ], "items": { "type": "string" } }, "numbers": { "type": "array", "description": "The numbers to assign, one entry per area code, e.g.\n[{\"area_code\": \"212\", \"quantity\": 2}, {\"area_code\": \"415\"}, {\"quantity\": 1}]: two numbers in 212,\none in 415 and one in any area code. quantity defaults to 1, and an entry without\narea_code means any area code. Omit numbers for one number.\n \nOnly with LOCAL or TEN_DLC, and not together with area_codes. Each area code is\nvalidated against country the same way area_codes is and may appear once, and at most one\nentry may leave area_code out. On a LOCAL market you already hold, this adds the numbers to\nit. US TEN_DLC numbers are assigned when the campaign is approved, not at request time. Not\navailable when the profile inherits the organization's campaign.", "nullable": true, "example": null, "items": { "$ref": "#/components/schemas/SentDmServicesCommonSenderProfilesContractsSmsNumberRequest" } }, "compliance": { "description": "What this market registers with. Its members are declared by the market itself — call `GET /v3/compliance/requirements?country=&type=` for the authoritative set.\n\n**US `TEN_DLC` is the only market that registers with a regime**, and the only one whose compliance carries `brand` and `campaign`; those are the members described here. Every other market's compliance is document keys, which come from configuration rather than from code and so cannot be listed in this document.", "allOf": [ { "$ref": "#/components/schemas/MarketCompliance" } ] } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberCreatedResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceNumberCreatedResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceNumberCreatedResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsVoiceNumberState" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceNumberCreatedResponse_Properties", "type": "object", "description": "A voice number as it was just turned on: the same facts GET /v3/channels reports, plus the one\nit never shows, the signing secret.", "additionalProperties": false, "properties": { "callback_secret": { "type": "string", "description": "The whsec_ secret every question to callback_url is signed with. Shown here and by\nPOST /v3/channels/voice/{number}/rotate-secret, nowhere else: store it now. Verify a question\nexactly as you verify a webhook, with X-Webhook-ID, X-Webhook-Timestamp and the body." } } } ] }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest_Properties", "type": "object", "description": "Turns phone calls on for a number: one you already hold, or a new one.\n \nVoice is per number the way SMS is per market: each number you hold can carry calls on its own,\nand each has its own callback URL, where Sent asks what to do with every call on it. The first number\nyou turn voice on for becomes the line app-originated calls are placed from when a voice token names no\nnumber.\n \nSend number to add calls to a number you already hold, or leave it out to be given a new\nUS number — optionally in a particular area_code. The two are alternatives, not a pair.", "additionalProperties": false, "required": [ "callback_url" ], "properties": { "number": { "type": "string", "description": "One of your phone numbers, in E.164 format. Leave the field out entirely to be given a new one\ninstead; sending it empty is a refused request rather than a request for a new number.", "nullable": true, "example": "+12125550100" }, "area_code": { "type": "string", "description": "The US area code a new number should be in, as 212. Only for a request that leaves\nnumber out — sending both says two different things about which number to use, and is\nrefused. Omit it too and the number comes from anywhere in the country.", "nullable": true, "example": null }, "callback_url": { "type": "string", "description": "Where Sent asks what to do with each call on this number: an absolute HTTP or HTTPS URL on a public\nhost. A signed question is POSTed here when a call arrives or a caller presses a key, and the answer\ndecides the call. Every question is signed with the callback_secret the response returns, the\nsame way your webhooks are signed. Turning the number on again with a different URL replaces it and\nkeeps the secret.", "minLength": 1, "example": "https://example.com/voice" }, "default_for_app_calls": { "type": "boolean", "description": "Make this the line app-originated calls are placed from when a voice token names no number.\nOmit it and your first voice number takes that role; a later one leaves it where it is.", "nullable": true, "example": false } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfWhatsappChannelState": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsWhatsappChannelState" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddWhatsappChannelRequest": { "type": "object", "example": { "waba_id": "102290129340398", "phone_number_id": "106540352242922", "sandbox": false }, "required": [ "waba_id" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddWhatsappChannelRequest_Properties", "type": "object", "description": "Connects a WhatsApp Business Account shared through a Multi-Partner Solution.\n \nThe same two fields channels.whatsapp takes on POST /v3/sender-profiles, so a block lifts\nverbatim between them and both resolve the rest the same way — the solution the account arrived through, the\nclient business portfolio that owns it, the access token and its expiry all come from the organization rather\nthan from the request.\n \nOnly these two cannot be inferred: the organization holds one account per client, so nothing but the\ncaller says which is meant, and the account's number is assigned to the profile only when the caller names\nit.", "additionalProperties": false, "properties": { "waba_id": { "type": "string", "description": "WhatsApp Business Account id — one of the accounts shared into your organization. Required: the\norganization holds one per client, and nothing but the caller says which is meant here.", "nullable": false, "example": "102290129340398" }, "phone_number_id": { "type": "string", "description": "The Meta phone-number id of the number on WabaId, which assigns it to this profile as the\nnumber it sends from. It is not checked against the account here, so name the account's number; it is\nrefused if another profile already uses it.\n \nOptional: omit it to connect the account and settle the number later. Nothing picks one on your\nbehalf.", "nullable": true, "example": "106540352242922" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceTokenResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceTokenResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceTokenResponse": { "type": "object", "description": "A short-lived token your app passes to the voice client SDK to register", "additionalProperties": false, "properties": { "token": { "type": "string", "description": "The signed token. Hand it to the client SDK unchanged." }, "identity": { "type": "string", "description": "The identity the token was minted for" }, "number": { "type": "string", "description": "The phone number this identity is now bound to, in E.164 format" }, "expires_at": { "type": "string", "description": "When the token expires (UTC)", "format": "date-time" } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsCreateVoiceTokenRequest": { "type": "object", "example": { "identity": "agent-42", "number": "+12025550123", "ttl": 600, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsCreateVoiceTokenRequest_Properties", "type": "object", "description": "Request to mint a voice token for one of your app users", "additionalProperties": false, "properties": { "identity": { "type": "string", "description": "Your identifier for the app user, such as an agent or account id. Letters, digits, hyphens and underscores only, up to 200 characters.", "example": "agent-42" }, "number": { "type": "string", "description": "One of your voice-enabled phone numbers in E.164 format. Calls placed by this identity are routed through that number. Omit to use your default app-call number.", "nullable": true, "example": "+12025550123" }, "ttl": { "type": "integer", "description": "Token lifetime in seconds. Defaults to 600 and cannot exceed 3600.", "format": "int32", "maximum": 3600.0, "minimum": 1.0, "nullable": true, "example": 600 } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfSenderProfileChannelsState": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSenderProfileChannelsState" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsGetChannelsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberState": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsVoiceNumberState" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsGetVoiceChannelRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfVoiceNumberState": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "array", "description": "The response data (null if error)", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsVoiceNumberState" } }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsPatchVoiceChannelRequest": { "type": "object", "example": { "default_for_app_calls": true, "callback_url": "https://example.com/voice", "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsPatchVoiceChannelRequest_Properties", "type": "object", "description": "Changes one of your voice numbers: turns it on or off, makes it the default line for app calls, or\nreplaces its callback URL.\n \nPartial. An omitted field is left alone, so one field can be corrected without restating the\nothers. A body that names none of the three is refused rather than answered 200 for a write that did\nnot happen.", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "ACTIVE turns calls on for the number again, INACTIVE turns them off. Matched\nignoring case. Turning the default line off is refused while other active voice numbers remain.", "nullable": true, "example": null, "enum": [ "ACTIVE", "INACTIVE" ], "x-enum-descriptions": { "ACTIVE": "Turns calls on for the number again. The callback URL and the signing secret it had are kept; send `callback_url` in the same call to replace the URL.", "INACTIVE": "Turns calls off for the number. Refused while the number is the default line for app calls and other active voice numbers remain; move the default first. The callback URL and the secret stay on the number." } }, "default_for_app_calls": { "type": "boolean", "description": "true makes this the line app-originated calls are placed from when a voice token names no\nnumber. false is refused: an account with active voice numbers always has exactly one\ndefault, so the default moves by giving it to another number.", "nullable": true, "example": true }, "callback_url": { "type": "string", "description": "A new callback URL for the number, active or not: an absolute HTTP or HTTPS URL on a public host,\nwhere Sent asks what to do with each call. The signing secret is kept.", "nullable": true, "example": "https://example.com/voice" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceSecretResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceSecretResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceSecretResponse": { "type": "object", "description": "A freshly rotated callback signing secret", "additionalProperties": false, "properties": { "callback_secret": { "type": "string", "description": "The new whsec_ secret. The previous one stopped signing the moment this was returned, so update\nyour backend before the next call reaches it. Shown once." } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsRotateVoiceSecretRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceCallbackTestResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestResponse": { "type": "object", "description": "The verdict of a test question sent to your callback URL", "additionalProperties": false, "properties": { "outcome": { "type": "string", "description": "What happened: ok, timeout, connection_failed, http_error or invalid_answer" }, "call_id": { "type": "string", "description": "The call id the test question carried. It does not exist anywhere else and cannot be looked up." }, "request": { "type": "object", "description": "What your endpoint received. Null when the callback URL was refused before anything was sent.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestRequestInfo" } ] }, "response": { "type": "object", "description": "What your endpoint answered. Null when no response arrived.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestResponseInfo" } ] }, "answer": { "type": "object", "description": "Your answer as Sent read it, with numbers in E.164 and a missing caller id filled in. Set only when the outcome is ok.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SystemTextJsonJsonElement" } ] }, "error": { "type": "object", "description": "What was wrong. Set only when the outcome is not ok.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestErrorInfo" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestRequestInfo": { "type": "object", "description": "The test question exactly as it was sent", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "The callback URL that was called" }, "headers": { "type": "object", "description": "Every header Sent added, the signature included, so you can compare against what your endpoint verified. The signing secret itself is never included.", "additionalProperties": { "type": "string" } }, "body": { "type": "string", "description": "The request body byte for byte. This is what the signature covers." } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestResponseInfo": { "type": "object", "description": "What your endpoint answered", "additionalProperties": false, "properties": { "status_code": { "type": "integer", "description": "The HTTP status your endpoint returned", "format": "int32" }, "body": { "type": "string", "description": "The start of the raw response body, capped at 2048 characters", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceCallbackTestErrorInfo": { "type": "object", "description": "Why the test did not end with ok", "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Machine-readable reason, such as timeout, http_error, malformed_json, missing_action or unknown_action" }, "path": { "type": "string", "description": "Dotted path of the answer field at fault, such as action.action, when one field is to blame", "nullable": true }, "message": { "type": "string", "description": "What to fix" } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsTestVoiceCallbackRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3ChannelsMarketMarketRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfSmsMarketState": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "array", "description": "The response data (null if error)", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSmsMarketState" } }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3ChannelsMarketMarketComplianceWriteRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3ChannelsMarketComplianceWriteRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3ChannelsMarketComplianceWriteRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" }, { "title": "SentDmServicesEndpointsCustomerAPIv3ChannelsMarketComplianceWriteRequest_Properties", "type": "object", "description": "Amends what a market declares for compliance.\n \nThe body is the market's, wrapped in compliance — the same wrapper\nPOST /v3/channels/sms takes and the same one GET on this path returns, so what comes back can\nbe sent back unchanged. There is no brand or campaign in the path to make the wrapper\nredundant: both halves are singletons of the market, and both are written here.\n \nPartial, at every level. An omitted key is left alone and an explicit null clears it —\nwhich is what PATCH means, and why this is not a PUT. A body naming nothing is refused rather\nthan silently accepted, and a nullable value cannot tell \"not sent\" from \"sent as null\", so the binder\nrecords which names the body carried.\n \nNothing here creates a second anything. Both halves are one slot, so a write is an upsert and\na replayed request lands on the row it already wrote. That is what makes this safe to sit behind a verb\nclients auto-retry — a collection would have put a paid TCR filing there instead.", "additionalProperties": { "nullable": true }, "properties": { "sandbox": { "type": "boolean", "example": false }, "compliance": { "description": "What this market registers with. Its members are declared by the market itself — call `GET /v3/compliance/requirements?country=&type=` for the authoritative set.\n\n**US `TEN_DLC` is the only market that registers with a regime**, and the only one whose compliance carries `brand` and `campaign`; those are the members described here. Every other market's compliance is document keys, which come from configuration rather than from code and so cannot be listed in this document.", "allOf": [ { "$ref": "#/components/schemas/MarketCompliance" } ] } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallResponse": { "type": "object", "description": "A call record", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The call id, the same one carried by the call.request question and every call webhook" }, "direction": { "type": "string", "description": "outbound for a call placed from your app, inbound for a call to one of your numbers" }, "from": { "description": "Who placed the call", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallParty" } ] }, "to": { "description": "Who the call was for", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallParty" } ] }, "number": { "type": "string", "description": "Your number that owns the call, in E.164 format: the dialed number for an inbound call, the caller's bound number for a call placed from your app" }, "status": { "type": "string", "description": "INITIATED, RINGING, ANSWERED, COMPLETED, FAILED, NO_ANSWER or REJECTED" }, "failure_reason": { "type": "string", "description": "Why the call did not complete: callback_timeout, invalid_answer, insufficient_balance, destination_blocked, callback_not_configured, rejected or no_answer. Null while the call is live, when it completed, and when it failed without a recorded reason", "nullable": true }, "started_at": { "type": "string", "description": "When the call was placed (UTC)", "format": "date-time" }, "answered_at": { "type": "string", "description": "When the call was answered (UTC). Null until then, and always null for a call between two of your app users", "format": "date-time", "nullable": true }, "ended_at": { "type": "string", "description": "When the call ended (UTC). Null while the call is live", "format": "date-time", "nullable": true }, "duration_seconds": { "type": "integer", "description": "Billable duration in seconds. Null while the call is live", "format": "int32", "nullable": true }, "price": { "type": "number", "description": "What the call cost. Null until it has been priced", "format": "decimal", "nullable": true }, "recording_available": { "type": "boolean", "description": "True once a recording of the call is available" }, "timeline": { "type": "array", "description": "When the call entered each status, oldest first. Only returned when reading one call", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallTimelineEntry" } } } }, "SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallParty": { "type": "object", "description": "One end of a call", "additionalProperties": false, "properties": { "kind": { "type": "string", "description": "user for one of your app users, number for a phone number, conference for a room, anonymous for a caller who withheld their number" }, "value": { "type": "string", "description": "The app user's identity, the phone number in E.164 format, or the room name. Null when the kind is anonymous", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallTimelineEntry": { "type": "object", "description": "When a call entered a status", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "INITIATED, RINGING, ANSWERED, COMPLETED, FAILED, NO_ANSWER or REJECTED" }, "timestamp": { "type": "string", "description": "When the call entered this status (UTC)", "format": "date-time" } } }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsAddCallParticipantRequest": { "type": "object", "example": { "to": { "kind": "number", "value": "+14155551234" }, "caller_id": "+12025550123", "sandbox": false }, "required": [ "to" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3CallsRequestsAddCallParticipantRequest_Properties", "type": "object", "description": "Request to add a participant to one of your live calls", "additionalProperties": false, "properties": { "to": { "description": "Who to add: one of your app users, or a phone number", "nullable": false, "example": { "kind": "number", "value": "+14155551234" }, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsRequestsCallParticipantTarget" } ] }, "caller_id": { "type": "string", "description": "The number shown to a phone participant as the caller, in E.164 format. Must be one of your numbers. The call's owning number when omitted", "nullable": true, "example": "+12025550123" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsCallParticipantTarget": { "type": "object", "description": "A participant to add to a call", "additionalProperties": false, "properties": { "kind": { "type": "string", "description": "user for one of your app users, number for a phone number" }, "value": { "type": "string", "description": "The app user's identity, or the phone number in E.164 format" } } }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsGetCallRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfCallParticipantResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "array", "description": "The response data (null if error)", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallParticipantResponse" } }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallParticipantResponse": { "type": "object", "description": "A participant of a conference call", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The participant's own call id: what the mute and remove endpoints take, and what GET /v3/calls/{id} accepts" }, "kind": { "type": "string", "description": "user for one of your app users, number for a phone number, anonymous for a caller who withheld their number" }, "value": { "type": "string", "description": "The app user's identity or the phone number in E.164 format. Null when the kind is anonymous", "nullable": true }, "muted": { "type": "boolean", "description": "True while the room mutes this participant" }, "duration_seconds": { "type": "integer", "description": "How long the participant has been connected to the room, in seconds", "format": "int32" } } }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsGetCallParticipantsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallRecordingsResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallRecordingsResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallRecordingsResponse": { "type": "object", "description": "The recordings of a call, each as a short-lived download link", "additionalProperties": false, "properties": { "recordings": { "type": "array", "description": "Every recording of the call, oldest first. Empty until the first call.recording_ready webhook has been sent, and for a call that was never recorded", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallRecordingResponse" } } } }, "SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallRecordingResponse": { "type": "object", "description": "A short-lived link to a call recording", "additionalProperties": false, "properties": { "recording_id": { "type": "string", "description": "The recording's id, the one the call.recording_ready webhook announced it under", "format": "uuid" }, "download_url": { "type": "string", "description": "A pre-signed link that downloads the recording as an MP3 file. Anyone holding it can download the recording until it expires" }, "url_expires_at": { "type": "string", "description": "When the link stops working (UTC). Request the recordings again for a fresh link", "format": "date-time" } } }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsGetCallRecordingsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallsListResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallsListResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallsListResponse": { "type": "object", "description": "Paginated list of calls", "additionalProperties": false, "properties": { "calls": { "type": "array", "description": "The calls on this page, most recent first", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3CallsResponsesCallResponse" } }, "pagination": { "description": "Pagination metadata", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsGetCallsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsHangupCallRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsPatchCallParticipantRequest": { "type": "object", "example": { "muted": true, "sandbox": false }, "required": [ "muted" ], "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3CallsRequestsPatchCallParticipantRequest_Properties", "type": "object", "description": "Request to change a participant of one of your conference calls: mute or unmute them", "additionalProperties": false, "properties": { "muted": { "type": "boolean", "description": "true to mute the participant, false to unmute them", "nullable": false, "example": true } } } ] }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsRecordCallRequest": { "type": "object", "example": { "action": "start", "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3CallsRequestsRecordCallRequest_Properties", "type": "object", "description": "Request to start or stop recording one of your live calls", "additionalProperties": false, "properties": { "action": { "type": "string", "description": "start to begin recording, stop to end it", "example": "start" } } } ] }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsRemoveCallParticipantRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3CallsRequestsRemoveCallParticipantsRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfBrandCampaignV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsResponsesBrandCampaignV3Response" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsResponsesBrandCampaignV3Response": { "type": "object", "description": "A 10DLC campaign registered for a brand.", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "Campaign type (for example KYC or App)." }, "name": { "type": "string" }, "description": { "type": "string" }, "brandId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsTcrCampaignStatus" } ] }, "tcrCampaignId": { "type": "string", "description": "The Campaign Registry identifier, once the campaign has been accepted.", "nullable": true }, "submittedToTCR": { "type": "boolean" }, "submittedAt": { "type": "string", "format": "date-time", "nullable": true }, "cost": { "type": "number", "format": "decimal", "nullable": true }, "billedDate": { "type": "string", "format": "date-time", "nullable": true }, "messageFlow": { "type": "string", "nullable": true }, "volume": { "type": "string", "description": "Expected messaging volume for this campaign — customer-supplied on create/update, and the\n input to both the TCR usecase classification (LOW_VOLUME vs MIXED/specific) and the campaign fee\n tier. Surfaced so customers can read back the value they set.", "nullable": true }, "privacyPolicyLink": { "type": "string", "nullable": true }, "termsAndConditionsLink": { "type": "string", "nullable": true }, "optinMessage": { "type": "string", "nullable": true }, "optoutMessage": { "type": "string", "nullable": true }, "helpMessage": { "type": "string", "nullable": true }, "optinKeywords": { "type": "string", "nullable": true }, "optoutKeywords": { "type": "string", "nullable": true }, "helpKeywords": { "type": "string", "nullable": true }, "dcaElectionsComplete": { "type": "boolean", "description": "True once every carrier has completed its DCA election and the campaign is\noperationally ready for traffic.", "nullable": true }, "dcaElectionsCompletedAt": { "type": "string", "format": "date-time", "nullable": true }, "tcrSyncError": { "type": "string", "description": "Surfaced so customers can see why a submission did not reach the registry.", "nullable": true }, "hasSubmissionTransaction": { "type": "boolean", "description": "True when the one-time campaign submission fee has already been charged." }, "useCases": { "type": "array", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsResponsesCampaignUseCaseV3Response" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SentDmServicesCommonEnumsTcrCampaignStatus": { "type": "string", "description": "", "x-enumNames": [ "SENT_CREATED", "ACTIVE", "EXPIRED" ], "enum": [ "SENT_CREATED", "ACTIVE", "EXPIRED" ] }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsResponsesCampaignUseCaseV3Response": { "type": "object", "description": "Customer-facing use-case representation for the public v3 campaign contract.\nExists for the same reason as BrandCampaignV3Response: nesting the\nTcrCampaignUseCase database entity in a public response means any column added to\nthat table silently becomes part of the customer-facing contract. This DTO is an explicit\nallowlist, so a new column stays invisible until it is added here on purpose.\nThis mirrors exactly the fields the entity already serialized, so it removes nothing from the\ncurrent response shape. It only closes the future-leak path.", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "campaignId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "messagingUseCaseUs": { "description": "The US messaging use case declared for this campaign.", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsMessagingUseCaseUS" } ] }, "sampleMessages": { "type": "array", "description": "Sample messages submitted to the registry for this use case.", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SentDmServicesCommonEnumsMessagingUseCaseUS": { "type": "string", "description": "", "x-enumNames": [ "MARKETING", "ACCOUNT_NOTIFICATION", "CUSTOMER_CARE", "FRAUD_ALERT", "TWO_FA", "DELIVERY_NOTIFICATION", "SECURITY_ALERT", "M2M", "MIXED", "HIGHER_EDUCATION", "POLLING_VOTING", "PUBLIC_SERVICE_ANNOUNCEMENT", "LOW_VOLUME" ], "enum": [ "MARKETING", "ACCOUNT_NOTIFICATION", "CUSTOMER_CARE", "FRAUD_ALERT", "TWO_FA", "DELIVERY_NOTIFICATION", "SECURITY_ALERT", "M2M", "MIXED", "HIGHER_EDUCATION", "POLLING_VOTING", "PUBLIC_SERVICE_ANNOUNCEMENT", "LOW_VOLUME" ] }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCreateBrandCampaignRequest": { "type": "object", "example": { "campaign": { "name": "Customer Notifications", "description": "Appointment reminders and account notifications", "type": "App", "useCases": [ { "messagingUseCaseUs": "ACCOUNT_NOTIFICATION", "sampleMessages": [ "Hi {name}, your appointment is confirmed for {date} at {time}.", "Your order #{order_id} has been shipped. Track at {url}" ] } ], "messageFlow": "User signs up on website and opts in to receive SMS notifications", "privacyPolicyLink": "https://acmecorp.com/privacy", "termsAndConditionsLink": "https://acmecorp.com/terms", "optinMessage": "You have opted in to Acme Corp notifications. Reply STOP to opt out.", "optoutMessage": "You have been unsubscribed. Reply START to opt back in.", "helpMessage": "Reply STOP to unsubscribe or contact support@acmecorp.com", "optinKeywords": "YES, START, SUBSCRIBE", "optoutKeywords": "STOP, UNSUBSCRIBE, END", "helpKeywords": "HELP, INFO, SUPPORT" }, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCreateBrandCampaignRequest_Properties", "type": "object", "description": "Request to create a campaign for a brand", "additionalProperties": false, "required": [ "campaign" ], "properties": { "campaign": { "description": "Campaign data", "example": { "name": "Customer Notifications", "description": "Appointment reminders and account notifications", "type": "App", "useCases": [ { "messagingUseCaseUs": "ACCOUNT_NOTIFICATION", "sampleMessages": [ "Hi {name}, your appointment is confirmed for {date} at {time}.", "Your order #{order_id} has been shipped. Track at {url}" ] } ], "messageFlow": "User signs up on website and opts in to receive SMS notifications", "privacyPolicyLink": "https://acmecorp.com/privacy", "termsAndConditionsLink": "https://acmecorp.com/terms", "optinMessage": "You have opted in to Acme Corp notifications. Reply STOP to opt out.", "optoutMessage": "You have been unsubscribed. Reply START to opt back in.", "helpMessage": "Reply STOP to unsubscribe or contact support@acmecorp.com", "optinKeywords": "YES, START, SUBSCRIBE", "optoutKeywords": "STOP, UNSUBSCRIBE, END", "helpKeywords": "HELP, INFO, SUPPORT" }, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCampaignData" } ] } } } ] }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCampaignData": { "type": "object", "description": "Campaign data for create or update operation", "additionalProperties": false, "required": [ "name", "description", "type", "useCases" ], "properties": { "name": { "type": "string", "description": "Campaign name", "minLength": 1 }, "description": { "type": "string", "description": "Campaign description", "minLength": 1 }, "type": { "type": "string", "description": "Campaign type (e.g., \"KYC\", \"App\").\n \nStill required of a caller, and consulted by nothing. It named the signup path that produced the\ncampaign, was written to a column no query filters on, no TCR payload carries and no fee or status\ndecision reads, and is now defaulted at the entity instead. It stays required so that a request which\nwas valid before is still valid — dropping it would be the client-visible change, not keeping it.", "minLength": 1 }, "useCases": { "type": "array", "description": "List of use cases with sample messages", "minItems": 1, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCampaignUseCaseData" } }, "volume": { "type": "string", "description": "Expected messaging volume for this campaign. Numeric string (e.g. \"1999\", \"5000\").\nValues below 2000 bill at the low-volume tier.", "nullable": true }, "messageFlow": { "type": "string", "description": "Description of how messages flow in the campaign", "nullable": true }, "privacyPolicyLink": { "type": "string", "description": "URL to privacy policy", "format": "uri", "nullable": true }, "termsAndConditionsLink": { "type": "string", "description": "URL to terms and conditions", "format": "uri", "nullable": true }, "optinMessage": { "type": "string", "description": "Message sent when user opts in", "nullable": true }, "optoutMessage": { "type": "string", "description": "Message sent when user opts out", "nullable": true }, "helpMessage": { "type": "string", "description": "Message sent when user requests help", "nullable": true }, "optinKeywords": { "type": "string", "description": "Comma-separated keywords that trigger opt-in (e.g., \"YES, START, SUBSCRIBE\")", "maxLength": 255, "nullable": true }, "optoutKeywords": { "type": "string", "description": "Comma-separated keywords that trigger opt-out (e.g., \"STOP, UNSUBSCRIBE, END\")", "maxLength": 255, "nullable": true }, "helpKeywords": { "type": "string", "description": "Comma-separated keywords that trigger help message (e.g., \"HELP, INFO, SUPPORT\")", "maxLength": 255, "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCampaignUseCaseData": { "type": "object", "description": "Campaign use case with sample messages", "additionalProperties": false, "required": [ "messagingUseCaseUs", "sampleMessages" ], "properties": { "messagingUseCaseUs": { "description": "US messaging use case category", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonEnumsMessagingUseCaseUS" } ] }, "sampleMessages": { "type": "array", "description": "Sample messages for this use case (1-5 messages, max 1024 characters each)", "maxItems": 5, "minItems": 1, "items": { "type": "string" } } } }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsDeleteBrandCampaignRequest": { "type": "object", "example": { "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfBrandCampaignV3Response": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "array", "description": "The response data (null if error)", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsResponsesBrandCampaignV3Response" } }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsGetBrandCampaignsRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedHeaderBaseRequest" } ] }, "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsUpdateBrandCampaignRequest": { "type": "object", "example": { "campaign": { "name": "Customer Notifications Updated", "description": "Updated appointment reminders and account notifications", "type": "App", "useCases": [ { "messagingUseCaseUs": "ACCOUNT_NOTIFICATION", "sampleMessages": [ "Hi {name}, your appointment is confirmed for {date} at {time}.", "Your order #{order_id} has been shipped. Track at {url}" ] } ], "messageFlow": "User signs up on website and opts in to receive SMS notifications" }, "sandbox": false }, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedMutationRequestBase" }, { "title": "SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsUpdateBrandCampaignRequest_Properties", "type": "object", "description": "Request to update an existing campaign", "additionalProperties": false, "required": [ "campaign" ], "properties": { "campaign": { "description": "Campaign data", "example": { "name": "Customer Notifications Updated", "description": "Updated appointment reminders and account notifications", "type": "App", "useCases": [ { "messagingUseCaseUs": "ACCOUNT_NOTIFICATION", "sampleMessages": [ "Hi {name}, your appointment is confirmed for {date} at {time}.", "Your order #{order_id} has been shipped. Track at {url}" ] } ], "messageFlow": "User signs up on website and opts in to receive SMS notifications" }, "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3BrandsCampaignsRequestsCampaignData" } ] } } } ] }, "SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfAccountResponse": { "type": "object", "description": "Standard API response envelope for all v3 endpoints", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was successful" }, "data": { "type": "object", "description": "The response data (null if error)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesAccountResponse" } ] }, "error": { "type": "object", "description": "Error details (null if successful)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiError" } ] }, "meta": { "description": "Metadata about the request and response", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3SharedApiMeta" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3AccountResponsesAccountResponse": { "type": "object", "description": "Account response for GET /v3/me endpoint.\nReturns organization (with profiles), user (standalone), or profile (child of an organization)\ndata depending on the API key type. Always includes messaging channel configuration.", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "Account type: \"organization\" (has profiles), \"user\" (no profiles), or \"profile\" (child of an organization)" }, "id": { "type": "string", "description": "Customer ID (organization, account, or profile)", "format": "uuid" }, "organization_id": { "type": "string", "description": "Organization ID (only for profile type — the parent organization)", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Account name" }, "short_name": { "type": "string", "description": "Short name / abbreviation (only for profile type)", "nullable": true }, "email": { "type": "string", "description": "Contact email address", "nullable": true }, "icon": { "type": "string", "description": "Account icon URL", "nullable": true }, "description": { "type": "string", "description": "Account description", "nullable": true }, "created_at": { "type": "string", "description": "When the account was created", "format": "date-time" }, "channels": { "description": "Messaging channel configuration", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesChannelsResponse" } ] }, "sending_phone_number": { "type": "string", "description": "The SMS sender this account sends from in the United States, in E.164 form. Null when the account has\nno US SMS sender.\n \nThe same value as channels.sms.phone_number, published under both names on purpose:\nsending_phone_number is what this value is already called on GET /v3/profiles, so the\nsame key answers the same question whichever of the two endpoints you ask. Neither name is preferred\nover the other and neither is deprecated.\n \nThe same value, not the same presence: this key is always written, including as null,\nwhereas channels.sms.phone_number is left out entirely when there is no sender.", "nullable": true }, "sending_phone_number_profile_id": { "type": "string", "description": "The account that holds sending_phone_number in number inventory: normally this account\nitself, and a different account when the number is held elsewhere. Null when there is no US\nsender, or when the sender is not a number drawn from inventory — an alphanumeric sender ID or a\nshort code.", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "Profile status (only for profile type): incomplete, pending_review, approved, etc.", "nullable": true }, "enable_template_auto_creation_for_sp": { "type": "boolean", "description": "Whether this account may mark a template for automatic creation on its sender profiles. Granted by\nSent per account and off by default, so it is what a template-create form reads to decide whether to\noffer the option at all — marking a template without it does nothing.\n \nTop-level rather than inside settings, which is written for type: \"profile\" only\nand so would never carry it to the account type that can act on it.\n \nThis is the capability, not the stored flag: a profile reports false whatever its\nown row holds. A sender profile owns no sender profiles, so a template it marked would have nothing\nto be created on and the fan-out would never read the flag. The admin GET /customers/{id}\nreports the stored value instead, because that is the one an operator granted." }, "settings": { "type": "object", "description": "Profile settings (only for profile type)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesProfileSettings" } ] }, "profiles": { "type": "array", "description": "List of profiles (populated for organization type, empty for user and profile types)", "items": { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesProfileResponse" } } } }, "SentDmServicesEndpointsCustomerAPIv3AccountResponsesChannelsResponse": { "type": "object", "description": "Messaging channel configuration. All three channels are always present.\nEach channel has a \"configured\" flag; configured channels expose additional details.", "additionalProperties": false, "properties": { "sms": { "description": "SMS channel", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesSmsChannelResponse" } ] }, "whatsapp": { "description": "WhatsApp Business channel", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesWhatsappChannelResponse" } ] }, "rcs": { "description": "RCS channel", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesRcsChannelResponse" } ] } } }, "SentDmServicesEndpointsCustomerAPIv3AccountResponsesSmsChannelResponse": { "type": "object", "description": "SMS channel configuration. When configured, includes the sending phone number.", "additionalProperties": false, "properties": { "configured": { "type": "boolean", "description": "Whether SMS is configured for this account" }, "phone_number": { "type": "string", "description": "Sending phone number in E.164 format", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3AccountResponsesWhatsappChannelResponse": { "type": "object", "description": "WhatsApp Business channel configuration. When configured, includes the WhatsApp phone number\nand business name.", "additionalProperties": false, "properties": { "configured": { "type": "boolean", "description": "Whether WhatsApp is configured for this account" }, "phone_number": { "type": "string", "description": "WhatsApp phone number in E.164 format", "nullable": true }, "business_name": { "type": "string", "description": "WhatsApp Business display name", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3AccountResponsesRcsChannelResponse": { "type": "object", "description": "RCS channel configuration. When configured, includes the RCS phone number.", "additionalProperties": false, "properties": { "configured": { "type": "boolean", "description": "Whether RCS is configured for this account" }, "phone_number": { "type": "string", "description": "RCS-enabled phone number in E.164 format", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3AccountResponsesProfileSettings": { "type": "object", "description": "Profile configuration settings", "additionalProperties": false, "properties": { "allow_contact_sharing": { "type": "boolean", "description": "Always false. A profile no longer shares contacts with sibling profiles — it sees only what\nit owns. Retained so existing v3 clients reading allow_contact_sharing keep deserializing; it\ncarries no information.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer share contacts; the flag it reported is gone.", "nullable": true }, "allow_template_sharing": { "type": "boolean", "description": "Always false. A profile no longer shares templates with sibling profiles. Retained so\nexisting v3 clients reading allow_template_sharing keep deserializing; it carries no\ninformation.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer share templates; the flag it reported is gone.", "nullable": true }, "inherit_contacts": { "type": "boolean", "description": "Always false. A profile no longer inherits its organization's contacts. Retained so existing\nv3 clients reading inherit_contacts keep deserializing; it carries no information.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer inherit contacts; the flag it reported is gone.", "nullable": true }, "inherit_templates": { "type": "boolean", "description": "Always false. A profile no longer inherits its organization's templates. Retained so existing\nv3 clients reading inherit_templates keep deserializing; it carries no information.", "deprecated": true, "x-deprecatedMessage": "Always false. Sender profiles no longer inherit templates; the flag it reported is gone.", "nullable": true }, "inherit_tcr_brand": { "type": "boolean", "description": "Whether this profile inherits TCR brand from the organization", "nullable": true }, "inherit_tcr_campaign": { "type": "boolean", "description": "Whether this profile inherits TCR campaign from the organization", "nullable": true }, "billing_model": { "type": "string", "description": "Billing model: profile, organization, or profile_and_organization", "nullable": true } } }, "SentDmServicesEndpointsCustomerAPIv3AccountResponsesProfileResponse": { "type": "object", "description": "Profile (sender profile) response for v3 API", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Profile unique identifier", "format": "uuid" }, "name": { "type": "string", "description": "Profile name" }, "icon": { "type": "string", "description": "Profile icon URL", "nullable": true }, "description": { "type": "string", "description": "Profile description", "nullable": true }, "short_name": { "type": "string", "description": "Profile short name (abbreviation)", "nullable": true }, "role": { "type": "string", "description": "User's role in this profile: admin, billing, developer (inherited from organization if not explicitly set)", "nullable": true }, "status": { "type": "string", "description": "Profile setup status: incomplete, pending_review, approved, rejected", "nullable": true }, "created_at": { "type": "string", "description": "When the profile was created", "format": "date-time" }, "settings": { "description": "Profile configuration settings", "oneOf": [ { "$ref": "#/components/schemas/SentDmServicesEndpointsCustomerAPIv3AccountResponsesProfileSettings" } ] } } }, "SentDmServicesCommonServicesWebhooksContractsWebhookEventOfMessageWebhookPayload": { "type": "object", "description": "The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and\nvaries only in Payload.", "additionalProperties": false, "properties": { "field": { "type": "string", "description": "The event family, for example message, templates or contact. Route on\nthis first, then on event for the specific change." }, "event": { "type": "string", "description": "The specific event within the family, for example message.delivered,\nmessage.received or contact.opt_out. Absent on events that have no subtype, so\ntreat it as optional.", "nullable": true }, "timestamp": { "type": "string", "description": "When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission\ntime, not the time the underlying change happened. Use the timestamp inside the payload for\nthe latter." }, "request_id": { "type": "string", "description": "The event-specific body.", "nullable": true }, "payload": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsMessageWebhookPayload" } ] } } }, "SentDmServicesCommonServicesWebhooksContractsMessageWebhookPayload": { "type": "object", "description": "Body of an outbound message lifecycle event. Delivered once per status change, so a single\nmessage produces several of these as it moves toward a terminal status.", "additionalProperties": false, "required": [ "message_status" ], "properties": { "updated_at": { "type": "string", "description": "When the message reached MessageStatus, in UTC\n(yyyy-MM-ddTHH:mm:ssZ)." }, "account_id": { "type": "string", "description": "The account the message belongs to.", "format": "uuid" }, "message_id": { "type": "string", "description": "The message this event describes. Stable across every event in the message's lifecycle, so\nuse it to correlate them.", "format": "uuid" }, "template_id": { "type": "string", "description": "The template the message was sent from, when it was sent from one.", "format": "uuid", "nullable": true }, "template_name": { "type": "string", "description": "Name of the template the message was sent from. Omitted when the message wasn't\ntemplate-based.", "nullable": true }, "outbound_number": { "type": "string", "description": "The recipient's number in E.164 format." }, "agent_id": { "type": "string", "description": "The agent attributed to the send, when the send was attributed to one.", "nullable": true }, "message_status": { "type": "string", "description": "The status the message just reached, for example SENT, DELIVERED, or\nFAILED. Sent means dispatched and delivered means confirmed, so treat them as\ndistinct outcomes." }, "channel": { "type": "string", "description": "The channel the message went out on, for example sms or whatsapp. A message\nthat falls back to another channel reports the channel actually used." }, "body": { "type": "string", "description": "The rendered message body, as plain text. Sent as null when we aren't asserting a\nbody for this event. The field is always present, so read it and check for null rather than\nchecking whether the key exists. Truncated to 3072 characters.", "nullable": true }, "scheduled_at": { "type": "string", "description": "message.scheduled and message.cancelled only, in UTC (yyyy-MM-ddTHH:mm:ssZ): on\nmessage.scheduled it is when the held message will be released for delivery, on\nmessage.cancelled the release instant that was called off — the same instant, before and after.\nA consumer that recorded a future send from the first event has what it needs to un-record it from the\nsecond. Omitted on every other event.", "nullable": true }, "schedule_reason": { "type": "string", "description": "message.scheduled only: why the message is held, either because you scheduled it or because\nthe recipient is inside a protected quiet-hours window. Omitted on every other event, including\nmessage.cancelled — that is a property of the hold, not of the cancellation, and repeating it\nthere would read as \"why was this cancelled\", which it does not answer.", "nullable": true }, "reason_code": { "type": "string", "description": "Why the message reached this status, as a stable platform code such as\nDELIVERY_007 or BUSINESS_003. Present on\nmessage.failed, message.filtered and message.blocked; omitted on every status that\nneeds no explanation. Switch on this rather than on Reason: the code is\nstable, the wording may be improved. It is the platform's classification of the outcome and never a\ncarrier or vendor code.", "nullable": true }, "reason": { "type": "string", "description": "A human-readable sentence for ReasonCode, for example \"The recipient is not registered on\nthis channel\". Omitted whenever reason_code is.", "nullable": true } } }, "SentDmServicesCommonServicesWebhooksContractsWebhookEventOfInboundMessageWebhookPayload": { "type": "object", "description": "The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and\nvaries only in Payload.", "additionalProperties": false, "properties": { "field": { "type": "string", "description": "The event family, for example message, templates or contact. Route on\nthis first, then on event for the specific change." }, "event": { "type": "string", "description": "The specific event within the family, for example message.delivered,\nmessage.received or contact.opt_out. Absent on events that have no subtype, so\ntreat it as optional.", "nullable": true }, "timestamp": { "type": "string", "description": "When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission\ntime, not the time the underlying change happened. Use the timestamp inside the payload for\nthe latter." }, "request_id": { "type": "string", "description": "The event-specific body.", "nullable": true }, "payload": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsInboundMessageWebhookPayload" } ] } } }, "SentDmServicesCommonServicesWebhooksContractsInboundMessageWebhookPayload": { "type": "object", "description": "Body of a message.received event. Delivered when a contact messages one of your numbers.", "additionalProperties": false, "required": [ "inbound_number", "received_at" ], "properties": { "message_id": { "type": "string", "description": "The inbound message.", "format": "uuid" }, "updated_at": { "type": "string", "description": "When the message was received, in UTC (yyyy-MM-ddTHH:mm:ssZ). Same value as\nReceivedAt, kept for envelope consistency with outbound events." }, "account_id": { "type": "string", "description": "The account the message belongs to.", "format": "uuid" }, "inbound_number": { "type": "string", "description": "The contact's number in E.164 format, meaning the number the message came from." }, "outbound_number": { "type": "string", "description": "Your number in E.164 format, meaning the number the message was addressed to." }, "text": { "type": "string", "description": "The message body. Sent as null when the inbound message carried no text, for\nexample a media-only message. The field is always present, so read it and check for null\nrather than checking whether the key exists.", "nullable": true }, "channel": { "type": "string", "description": "The channel the message arrived on, for example sms or mms." }, "media": { "type": "array", "description": "Attachments the contact sent, present only on channels that carry them (mms today) and\nomitted entirely otherwise.\n \nEach url points at the carrier's own copy of the file — sent.dm records where the\nattachment is, not the attachment itself. The link is unauthenticated and expires on the\ncarrier's schedule, which differs between them: assume days, not months. Download what you need\non receipt; re-reading the message through GET /v3/messages/{id} returns the same stored\nlink, not a fresh one, so once it lapses the entry remains with whatever the carrier declared\nabout the file but the file is no longer reachable.", "nullable": true, "items": { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsInboundMediaWebhookPayload" } }, "received_at": { "type": "string", "description": "When the message was received, in UTC (yyyy-MM-ddTHH:mm:ssZ)." } } }, "SentDmServicesCommonServicesWebhooksContractsInboundMediaWebhookPayload": { "type": "object", "description": "One attachment on an inbound message.", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "Where the carrier hosts the attachment.\n \nThis link expires and is not authenticated. sent.dm relays it rather than copying\nthe file, so how long it stays fetchable is the carrier's decision and differs between them —\nassume days, not months. Anyone holding the URL can fetch it until it lapses. Copy the file on\nreceipt if you need it to outlive that window; do not store this URL as a permanent reference.", "nullable": true }, "mime_type": { "type": "string", "description": "Content type as the carrier reported it, for example image/jpeg.", "nullable": true }, "size_bytes": { "type": "integer", "description": "Size in bytes as the carrier declared it. Absent when it declared none.", "format": "int64", "nullable": true }, "hash_sha256": { "type": "string", "description": "SHA-256 of the file as the carrier declared it, when it declares one. Verify what you download\nagainst this — sent.dm never reads the bytes, so it is the only integrity signal available.", "nullable": true } } }, "SentDmServicesCommonServicesWebhooksContractsWebhookEventOfTemplateWebhookPayload": { "type": "object", "description": "The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and\nvaries only in Payload.", "additionalProperties": false, "properties": { "field": { "type": "string", "description": "The event family, for example message, templates or contact. Route on\nthis first, then on event for the specific change." }, "event": { "type": "string", "description": "The specific event within the family, for example message.delivered,\nmessage.received or contact.opt_out. Absent on events that have no subtype, so\ntreat it as optional.", "nullable": true }, "timestamp": { "type": "string", "description": "When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission\ntime, not the time the underlying change happened. Use the timestamp inside the payload for\nthe latter." }, "request_id": { "type": "string", "description": "The event-specific body.", "nullable": true }, "payload": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsTemplateWebhookPayload" } ] } } }, "SentDmServicesCommonServicesWebhooksContractsTemplateWebhookPayload": { "type": "object", "description": "Body of a template status event. Delivered when a template's review outcome changes, so you can\nreact without polling.", "additionalProperties": false, "required": [ "whatsapp_template_id", "status" ], "properties": { "account_id": { "type": "string", "description": "The account the template belongs to.", "format": "uuid" }, "template_id": { "type": "string", "description": "The template in Sent.", "format": "uuid" }, "whatsapp_template_id": { "type": "string", "description": "The template's identifier with Meta, assigned when the template is submitted for review." }, "template_name": { "type": "string", "description": "The template's display name." }, "status": { "type": "string", "description": "The review status the template just reached, for example APPROVED or\nREJECTED." }, "language": { "type": "string", "description": "The template's language code, for example en_US." }, "category": { "type": "string", "description": "The template's category, for example UTILITY, MARKETING, or\nAUTHENTICATION." }, "channel": { "type": "string", "description": "The channel leg this decision is about, for example whatsapp, sms, or rcs.\nA template is reviewed per channel and the legs come back independently, so each one reports\nseparately.\n \nOmitted when the decision applies to the template as a whole rather than to one leg. That\nevent is the broader news: a template-wide rejection blocks every channel, whatever the\nindividual legs say.", "nullable": true }, "auto_reply_action": { "type": "string", "description": "Which consent keyword this template answers, when it is one of Sent's auto-replies:\nOPT_IN, OPT_OUT, HELP, or OTHER for a customer-defined keyword.\n \nOmitted for an ordinary template, so its presence is the answer to \"is this an\nauto-reply\". Sent creates the three compliance auto-replies at signup and they go through\nreview like any other template, so their events arrive mixed in with the customer's own with\nnothing else to tell them apart.\n \nNamed for the reader rather than after Template.OptAction, which it is mapped\nfrom. The MCP tool result deliberately keeps OptAction, OptKeywords and\nIsOpt: it mirrors the internal shape on purpose and publishes the keywords too, so\nrenaming one of the three there would leave a surface half in each vocabulary. Two names for\none concept, each consistent within its own surface, chosen over a rename that breaks MCP\nclients silently.", "nullable": true }, "reason": { "type": "string", "description": "Why the template reached Status, when a reason was given. Populated on a\nrejection.", "nullable": true } } }, "SentDmServicesCommonServicesWebhooksContractsWebhookEventOfChannelWebhookPayload": { "type": "object", "description": "The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and\nvaries only in Payload.", "additionalProperties": false, "properties": { "field": { "type": "string", "description": "The event family, for example message, templates or contact. Route on\nthis first, then on event for the specific change." }, "event": { "type": "string", "description": "The specific event within the family, for example message.delivered,\nmessage.received or contact.opt_out. Absent on events that have no subtype, so\ntreat it as optional.", "nullable": true }, "timestamp": { "type": "string", "description": "When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission\ntime, not the time the underlying change happened. Use the timestamp inside the payload for\nthe latter." }, "request_id": { "type": "string", "description": "The event-specific body.", "nullable": true }, "payload": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsChannelWebhookPayload" } ] } } }, "SentDmServicesCommonServicesWebhooksContractsChannelWebhookPayload": { "type": "object", "description": "Body of a channel event: where one of the customer's channels stands in provisioning and\ncompliance. Delivered when a milestone moves — a registration filed, a verdict returned, a\nresubmission asked for, a sender gone live — so a customer's own onboarding UI does not have to\npoll GET /v3/channels.\n \nThe subject is one item, never the account. A customer's \"SMS channel\" has no\nstatus; a market does. Country, NumberType and\nSenderValue name which one, so a customer terminating only to Kosovo never\nreceives an event about US 10DLC.\n \nStatus is the stable half of the contract. It is the same four-value\nset GET /v3/channels publishes, computed through the same code, so an event and a read of\nthe same market cannot disagree. A subscriber that reads nothing but the status and the subject\nfields is a correct subscriber. The sub-type on the envelope names the specific milestone and is\nadditive — that vocabulary comes from registries and carriers, which are parties Sent does not\ncontrol.\n \nStatus means provisioning and compliance are complete, not that a send\nwill succeed right now. An account can be suspended, or a destination blocked by a routing\nrule, without either showing up here. Those are separate surfaces and deliberately not modelled\non this payload.", "additionalProperties": false, "required": [ "country" ], "properties": { "channel": { "type": "string", "description": "The channel this market belongs to: sms, whatsapp, or rcs. Never\nsent — that value belongs to message events, where it names the smart-routing brand\nrather than a channel that can be provisioned." }, "status": { "type": "string", "description": "Where the market stands: PENDING_REVIEW, ACTION_NEEDED, PROVISIONING,\nACTIVE or INACTIVE. PENDING_REVIEW means a registry or a carrier holds it\nand the wait is theirs; ACTION_NEEDED means it is yours; PROVISIONING means the\nverdict is in and Sent is acquiring the sender; INACTIVE means it had a working sender\nand no longer does.\n \nEach event name is the transition into one of these, but the two are separate fields\nand may legitimately differ. A resubmission filed against a market whose sender is already\nlive is channel.submitted carrying ACTIVE: a correction is with the registry and\nthe sender keeps working. Read both." }, "account_id": { "type": "string", "description": "The account whose market this is, named as on every other family. When an organization\nreceives an event for one of its sender profiles this is the profile, so a reseller compares\nit with its own id and anything different is one of its profiles.\nMatches customer_id on GET /v3/channels and the sender profile's id.\nTogether with channel, country, and number_type, it identifies the market.", "format": "uuid" }, "country": { "type": "string", "description": "The market's destination country as an ISO 3166-1 alpha-2 code, for example XK. Always\npresent, and the property that identifies this payload among the delivered envelopes — see\nDeliveredWebhookEvents. Every event in this family reports one market, and a market has\na country." }, "number_type": { "type": "string", "description": "The kind of sender the market uses, for example TEN_DLC, LOCAL, or\nALPHANUMERIC. Omitted when the subject has no sender type of its own.", "nullable": true }, "sender_value": { "type": "string", "description": "The sender itself — a number in E.164, or an alphanumeric sender ID.\n \nAlways present, and null until a sender exists. The key is on every delivery so a\nsubscriber reads one shape rather than branching on whether the field arrived — the same choice\ntemplate_id makes on the message payload.\n \nIt can carry a value at any point in the lifecycle, not only once the market is live: a\nnumber ordered and not yet active at the carrier is already known during PROVISIONING,\nand an alphanumeric sender the customer chose themselves is known before anything is filed. It\nis null while the market is still waiting on a number, which for a US 10DLC registration is\nevery event up to channel.activated.", "nullable": true }, "compliance": { "type": "object", "description": "What this market has supplied for compliance, in the same shape as\nGET /v3/channels/sms/{country}/{type}. A US 10DLC market carries its brand and campaign\nwhen available, including their inheritance flags. Other markets carry their own documents,\nwithout a brand or campaign. Brand and campaign IDs are not exposed: the country and sender\ntype identify the market to read or amend.\n \nIncludes supplied tax identifiers and contact details, as on the market read.\n \nOmitted when no compliance data is available, including sender release and removal\nevents emitted after the market is deleted or cleared. Within the object, absent documents\nmeans they were not read, while an empty list means none were supplied.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonChannelsContractsSuppliedComplianceState" } ] }, "reason_code": { "type": "string", "description": "Why the market is not ACTIVE, as a stable code: an ErrorCodes CHANNEL_xxx value such\nas CHANNEL_001 (something you owe) or CHANNEL_002 (a correction was requested). The same code\nthe channels resource reports for the market. Switch on this rather than on reason. Omitted while\nACTIVE.", "nullable": true }, "reason": { "type": "string", "description": "Why the market reached this state, as a sentence to show a person: the specific explanation when one was\ngiven (a correction explained, a campaign lapse), otherwise what reason_code means for this market.\nNot a value to branch on.", "nullable": true }, "updated_at": { "type": "string", "description": "When the transition happened, in UTC (yyyy-MM-ddTHH:mm:ssZ)." } } }, "SentDmServicesCommonServicesWebhooksContractsWebhookEventOfContactWebhookPayload": { "type": "object", "description": "The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and\nvaries only in Payload.", "additionalProperties": false, "properties": { "field": { "type": "string", "description": "The event family, for example message, templates or contact. Route on\nthis first, then on event for the specific change." }, "event": { "type": "string", "description": "The specific event within the family, for example message.delivered,\nmessage.received or contact.opt_out. Absent on events that have no subtype, so\ntreat it as optional.", "nullable": true }, "timestamp": { "type": "string", "description": "When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission\ntime, not the time the underlying change happened. Use the timestamp inside the payload for\nthe latter." }, "request_id": { "type": "string", "description": "The event-specific body.", "nullable": true }, "payload": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsContactWebhookPayload" } ] } } }, "SentDmServicesCommonServicesWebhooksContractsContactWebhookPayload": { "type": "object", "description": "Body of a contact.opt_in, contact.opt_out, contact.help or\ncontact.custom_keyword event. Delivered when a contact signals a consent change, asks for\nhelp, or sends one of your own auto-reply keywords.\n \nThese events state the signal outright, so you do not have to recognise keywords in the\ntext of a message.received event. They also cover cases that produce no inbound message\nat all, such as a network handling an opt-out on your behalf.\n \nTwo of the four change consent and two do not: contact.help and\ncontact.custom_keyword report the state the contact already had. Read opt_out for\nthe state and the envelope's event for what happened, rather than inferring one from the\nother.\n \nFields are ordered identity → resulting state → provenance → join keys. The two\nparties are from and to. Note that the message family has not moved to those\nnames yet — message.received still calls the same two parties\ninbound_number and outbound_number. Nothing here restates the\nenvelope: which signal occurred is the envelope's event, and when it was emitted is its\ntimestamp. Retries carry the same X-Webhook-Event-ID header, which is what to\ndeduplicate on.", "additionalProperties": false, "required": [ "source", "opt_out" ], "properties": { "account_id": { "type": "string", "description": "The account the contact belongs to. Present so one endpoint can serve several accounts.", "format": "uuid" }, "contact_id": { "type": "string", "description": "The contact who raised the signal. Always populated, including for contact.help or\ncontact.custom_keyword from a number you have not messaged before — the contact is\ncreated if it does not exist yet, so this identifier is always resolvable against the\ncontacts API.", "format": "uuid" }, "from": { "type": "string", "description": "The contact's number, in E.164 format with the leading + — who raised the signal.\nThe same party message.received publishes as inbound_number." }, "to": { "type": "string", "description": "The number of yours that received the signal, in E.164 format with the leading +.\nTells a multi-number account which of its senders the contact acted on, which nothing else\non this payload answers.\n \nThis is your number, not the contact's. That is the opposite of what\nto means on POST /v3/messages, where it is the list of recipients you are\nsending to. Reply to From, not to this field, or the message goes back to\nyourself.\n \nSent as null when the signal did not arrive at a number of yours — an RCS\nsignal terminates at an agent rather than a number, and a provider-reported opt-out may\nname no receiving number at all. The field is always present, so read it and check for null\nrather than checking whether the key exists.", "nullable": true }, "agent_id": { "type": "string", "description": "The RCS agent the signal reached, when it reached one.\n \nOmitted entirely on channels that have no agent, rather than sent as null — an SMS\nor WhatsApp payload does not carry this key at all. On RCS it is the counterpart to\nTo: a contact reaches an agent rather than a number, so exactly one of the\ntwo is populated and never both. If you run more than one agent, this is what tells you\nwhich of them the contact acted on.", "nullable": true }, "opt_out": { "type": "boolean", "description": "Whether the contact is opted out after this signal — the state to write to your own record.\nSame meaning as opt_out on the contact resource. On contact.help and\ncontact.custom_keyword this reports the contact's existing state, which neither\nchanges.\n \nTwo signals from the same contact can arrive out of order, because each one is queued\non its own rather than against the contact. Compare the envelope's timestamp before\nyou overwrite a newer state with an older one. That timestamp is second-precision, so treat\ntwo signals stamped in the same second as unordered and read the contact resource to settle\nthem." }, "source": { "type": "string", "description": "How the signal reached us. INBOUND_KEYWORD means the contact sent a message whose\ntext matched one of the keywords; PROVIDER_SIGNAL means the network reported it.\nA provider signal usually carries no message_id or text, so read both for null\nrather than inferring them from this field." }, "channel": { "type": "string", "description": "The channel the signal arrived on, for example sms or whatsapp." }, "text": { "type": "string", "description": "The text the contact sent, for example STOP or UNSUBSCRIBE. Sent as\nnull when the signal did not arrive as text. The field is always present, so read it\nand check for null rather than checking whether the key exists.", "nullable": true }, "message_id": { "type": "string", "description": "The inbound message that carried the signal, matching message_id on the\ncorresponding message.received event so the two can be joined.\n \nSent as null when the signal did not arrive as a message — for example when a\nnetwork processed an opt-out on your behalf — and also when the message belongs to a\ndifferent account than this event, which can happen on a shared WhatsApp number. The field\nis always present, so read it and check for null rather than checking whether the key\nexists.", "format": "uuid", "nullable": true }, "template_id": { "type": "string", "description": "The auto-reply template whose keyword the contact matched, joinable against the templates\nAPI.\n \nThis is what identifies which signal arrived on\ncontact.custom_keyword: every custom template reports the same event name, so the\nevent alone cannot tell your booking keyword from your opening-hours one. One template holds\nas many keywords as you configured, so this is steadier to switch on than text.\n \nPopulated on the compliance sub-types too, where it names the template that replied.\nSent as null when no template was involved — a network-reported opt-out matches no\nkeyword. The field is always present, so read it and check for null.", "format": "uuid", "nullable": true } } }, "SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload": { "type": "object", "description": "The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and\nvaries only in Payload.", "additionalProperties": false, "properties": { "field": { "type": "string", "description": "The event family, for example message, templates or contact. Route on\nthis first, then on event for the specific change." }, "event": { "type": "string", "description": "The specific event within the family, for example message.delivered,\nmessage.received or contact.opt_out. Absent on events that have no subtype, so\ntreat it as optional.", "nullable": true }, "timestamp": { "type": "string", "description": "When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission\ntime, not the time the underlying change happened. Use the timestamp inside the payload for\nthe latter." }, "request_id": { "type": "string", "description": "The event-specific body.", "nullable": true }, "payload": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesWebhooksContractsLinkWebhookPayload" } ] } } }, "SentDmServicesCommonServicesWebhooksContractsLinkWebhookPayload": { "type": "object", "description": "Body of a link event: something happened to a tracked link Sent published on the customer's\nbehalf. A link points either at a URL the customer supplied or at a file Sent hosts for them;\nLinkKind says which. Delivered when an eligible request is served, or when a\npublished link reaches the end of its life.\n \nA click is a request, not a read receipt. link.clicked means the redirect\nwas served; link.downloaded means bytes went out. Neither proves a person saw anything —\nmessaging providers and link scanners fetch URLs on their own, which is what\nTrafficClass exists to tell apart. Filter on it before reporting a click-through\nrate; treat likely_human as a hint, never as delivery confirmation.\n \nRecordId identifies the link; the X-Webhook-Event-ID header\nidentifies the delivery. One link is hit many times, so those are the two keys a\nsubscriber needs: group by the first, deduplicate on the second — exactly as on every other\nfamily. The payload carries no event identifier of its own, for the same reason none of the\nothers do.\n \nNothing here identifies the visitor. No IP address and no visitor token crosses\nthis boundary. Country, Device and Browser are coarse\nbuckets derived at the edge and are absent whenever the request did not supply enough to derive\nthem.", "additionalProperties": false, "required": [ "record_id" ], "properties": { "customer_id": { "type": "string", "description": "The organization the link belongs to. Always the parent account, never a sender profile —\nread SenderProfileId for that.\n \nThis family publishes the owner as an explicit pair rather than the single\naccount_id the other families use. The pair says which organization and which\nprofile without the subscriber deriving either, which is the trade: one more key against\nnot having to know that account_id silently becomes the profile when one exists.", "format": "uuid" }, "sender_profile_id": { "type": "string", "description": "The sender profile that owns the link, or null when the organization owns it directly.\nAlways on the wire so a handler reads one shape rather than branching on whether the key\narrived.\n \nsender_profile_id, not profile_id: the API already publishes\nmessaging_profile_id and sending_phone_number_profile_id for provider-side\nprofiles, which are a different thing entirely. The unqualified name would read as one of\nthose.", "format": "uuid", "nullable": true }, "message_id": { "type": "string", "description": "The message the link was published in.\n \nThe event can arrive before the message is readable through GET /v3/messages:\na provider may fetch a link within milliseconds of the send, and nothing here waits for the\nmessage row. Retry the read rather than treating an unknown id as an error.", "format": "uuid", "nullable": true }, "record_id": { "type": "string", "description": "The link's public identifier — the eight-character code in the short URL, for example\nA78B2BU0. Unique across both kinds, and never reused, so it is the stable key to\ngroup one link's events by." }, "link_kind": { "type": "string", "description": "What the link points at: url for a destination the customer supplied, file for\nmedia Sent hosts. Always present, and implied by the event — link.clicked is always\nurl and link.downloaded always file — but published as its own field so\na subscriber can branch on the kind without parsing the event name, the same separation the\nchannel family keeps between its event and its status." }, "channel": { "type": "string", "description": "The channel the message carrying this link went out on: sms, whatsapp, or\nrcs.", "nullable": true }, "reference_key": { "type": "string", "description": "The caller-supplied label tying this link back to a position in the message, for example\nbody:0 for the first link in the body. Present when the link was created with one.", "nullable": true }, "occurred_at": { "type": "string", "description": "When the access or lifecycle change actually happened, in UTC\n(yyyy-MM-ddTHH:mm:ssZ). The envelope's timestamp is when Sent emitted the\nevent; this is when the thing occurred, and the two differ by the ingest delay." }, "request_method": { "type": "string", "description": "The HTTP method of the request that was served, for an access event. Omitted on\nlink.expired and link.revoked, which describe no request.", "nullable": true }, "status_code": { "type": "integer", "description": "The HTTP status Sent answered the request with: 302 for a link, 200 or\n206 for a file. Omitted on lifecycle events.", "format": "int32", "nullable": true }, "traffic_class": { "type": "string", "description": "A coarse guess at what made the request: likely_human, provider (a messaging\nplatform prefetching the link), bot, or unknown. Derived from the user agent,\nso it is a hint for filtering noise rather than a fact to bill or report on.", "nullable": true }, "access_country": { "type": "string", "description": "Where the request appeared to come from, as an ISO 3166-1 alpha-2 code. Named separately\nfrom the country on a channel event, which is a destination market the customer\nregistered for — this one is a property of a single visitor and is absent when the edge\ncould not resolve it.", "nullable": true }, "device": { "type": "string", "description": "The requesting device class: mobile, tablet, desktop or\nunknown. Derived from the user agent.", "nullable": true }, "browser": { "type": "string", "description": "The requesting browser family, for example chrome or safari, or\nunknown. Derived from the user agent.", "nullable": true }, "referrer_host": { "type": "string", "description": "The host of the page that linked here, when the request supplied one. The host only — never\na full referring URL.", "nullable": true }, "bytes_served": { "type": "integer", "description": "How many bytes were served, for a file access. A ranged request reports the bytes in that\nrange, not the size of the file, so several accesses of one file can each report a part.", "format": "int64", "nullable": true }, "access_outcome": { "type": "string", "description": "How the request was served, when the edge recorded it. Free text describing the outcome —\nshow it to a human rather than branching on it.", "nullable": true } } }, "SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload": { "type": "object", "description": "The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and\nvaries only in Payload.", "additionalProperties": false, "properties": { "field": { "type": "string", "description": "The event family, for example message, templates or contact. Route on\nthis first, then on event for the specific change." }, "event": { "type": "string", "description": "The specific event within the family, for example message.delivered,\nmessage.received or contact.opt_out. Absent on events that have no subtype, so\ntreat it as optional.", "nullable": true }, "timestamp": { "type": "string", "description": "When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission\ntime, not the time the underlying change happened. Use the timestamp inside the payload for\nthe latter." }, "request_id": { "type": "string", "description": "The event-specific body.", "nullable": true }, "payload": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SentDmServicesCommonServicesCallsContractsCallWebhookPayload" } ] } } }, "SentDmServicesCommonServicesCallsContractsCallWebhookPayload": { "type": "object", "description": "Body of a call.initiated, call.answered, call.completed, call.failed\nor call.recording_ready event. Which of them occurred is the envelope's event.\n \nShaped like the message, inbound, template and channel payloads: account_id names the\naccount the event is about, channel names the channel, and updated_at is when the change\nhappened on the call, in the same yyyy-MM-ddTHH:mm:ssZ form. duration_seconds and\nprice are added on call.completed, reason on call.failed and\nrecording_id on call.recording_ready; each is omitted rather than sent as null when it\ndoes not apply.\n \nCasing is snake_case because these ride the same webhook stream customers already parse\nmessage_id from; the question/answer contract is a separate surface and stays camelCase.\nNothing here is provider-shaped: no provider call id, no namespaced identity.", "additionalProperties": false, "required": [ "call_id" ], "properties": { "account_id": { "type": "string", "description": "The account the call belongs to: the key's own customer, or the sender profile it acted as.", "format": "uuid" }, "call_id": { "type": "string", "description": "Sent's call id, the same one the customer saw on the first question." }, "channel": { "type": "string", "description": "Always voice." }, "number": { "type": "string", "description": "The customer number that owns the call, in E.164 format." }, "updated_at": { "type": "string", "description": "When the change happened on the call, as opposed to when the event was emitted." }, "duration_seconds": { "type": "integer", "description": "How long the call lasted. Only on call.completed.", "format": "int32", "nullable": true }, "price": { "type": "number", "description": "What the call was charged. Only on call.completed, and omitted there until billing has\nrecorded the charge.", "format": "decimal", "nullable": true }, "reason": { "type": "string", "description": "The machine-readable reason the call did not complete. Only on call.failed, and omitted\nwhen no reason was recorded.", "nullable": true }, "recording_id": { "type": "string", "description": "The recording that became available, the same id GET /v3/calls/{id}/recordings lists it\nunder. Only on call.recording_ready, which is sent once per recording.", "format": "uuid", "nullable": true } } }, "MarketCompliance": { "type": "object", "description": "The compliance values a market registers with. `brand` and `campaign` apply to US `TEN_DLC`; other markets fill this map with the document keys their own requirements name.", "properties": { "brand": { "type": "object", "description": "Business identity. The identity the registration is filed against. Omit to have none; { \"inherit\": true } to register under your organization's.", "properties": { "inherit": { "type": "boolean", "description": "Run on the organization's brand. True to register under the parent organization's identity rather than one of this profile's own; every field below is then neither asked for nor accepted. Omitted, the brand is the organization's unless this block supplies identity fields, which says plainly enough that it wants one of its own." }, "legal_name": { "type": "string", "description": "Registered legal name. TCR companyName — the name on the incorporation documents, which is often not the name recipients would recognise. Required when `compliance.brand.inherit != true`." }, "business_name": { "type": "string", "description": "Public-facing name. TCR displayName — the name recipients would recognise. Named for what it holds rather than for TCR's field, which is why it is not `display_name`. Required when `compliance.brand.inherit != true`." }, "tax_id": { "type": "string", "description": "Tax identifier. TCR ein. TcrBrandSubmissionValidator refuses a submission without one, so it is wanted here rather than discovered at filing time. Required when `compliance.brand.inherit != true`." }, "tax_id_type": { "type": "string", "description": "Kind of tax identifier. Which kind of identifier `tax_id` is, e.g. us_ein. Derived onto the brand form, and not itself sent to TCR. Required when `compliance.brand.inherit != true`." }, "ein_issuing_country": { "type": "string", "description": "Country that issued the tax id. TCR einIssuingCountry — where the tax id was issued, which is not always where the business trades. Defaults to `country` when omitted, which is right for most. Takes the code or the country spelled out, as `country` does.", "format": "iso3166_alpha2" }, "entity_type": { "type": "string", "description": "Entity type. TCR entityType. Decides which vetting TCR applies and, for SOLE_PROPRIETOR, fixes the campaign fee regardless of volume. Also refused at submission if absent. Required when `compliance.brand.inherit != true`.", "enum": [ "PRIVATE_PROFIT", "PUBLIC_PROFIT", "NON_PROFIT", "SOLE_PROPRIETOR", "GOVERNMENT" ] }, "street": { "type": "string", "description": "Street address. Required when `compliance.brand.inherit != true`." }, "city": { "type": "string", "description": "City. Required when `compliance.brand.inherit != true`." }, "state": { "type": "string", "description": "State or region. TCR state. Two letters for a US registration. Required when `compliance.brand.inherit != true`." }, "postal_code": { "type": "string", "description": "Postal code. Required when `compliance.brand.inherit != true`." }, "country": { "type": "string", "description": "Country of registration. Two letters — US. The country spelled out in full is accepted too and stored as its code, which is what a read answers with and what is filed. Required when `compliance.brand.inherit != true`.", "format": "iso3166_alpha2" }, "website": { "type": "string", "description": "Website. TCR website. Optional, and worth sending: carriers weigh it when vetting, so a brand that has one and omits it is vetted on less than it could be.", "format": "url" }, "contact_name": { "type": "string", "description": "Responsible contact. Split into TCR's firstName/lastName on submission. BrandService refuses a blank one, so a missing name is reported here rather than thrown after the profile was written. Required when `compliance.brand.inherit != true`." }, "contact_email": { "type": "string", "description": "Contact email. TCR email. Required when `compliance.brand.inherit != true`.", "format": "email" }, "contact_phone": { "type": "string", "description": "Contact phone. TCR sends it as both phone and mobilePhone, so it is asked for once. Named for the contact it belongs to rather than as a bare `phone` on a block that also carries an address. Required when `compliance.brand.inherit != true`.", "format": "e164" } } }, "campaign": { "type": "object", "description": "Messaging campaign. What the programme sends and how recipients consented. Omit to run on your organization's; supplying it takes one of your own. { \"inherit\": true } says so outright. Required when `compliance.campaign.inherit != true`.", "properties": { "inherit": { "type": "boolean", "description": "Run on the organization's campaign. True to register under the parent organization's programme rather than one of this profile's own; every field below is then neither asked for nor accepted. Owning the identity and inheriting the campaign is refused — a campaign is filed against an identity registration, and chk_tcr_inheritance forbids that pairing outright." }, "description": { "type": "string", "description": "What this programme sends. TCR description: what recipients will get and why, in a sentence. The only one of these TCR takes verbatim as a description of the programme, which is why it is asked for rather than derived from the customer's name. Required when `compliance.campaign.inherit != true`." }, "message_flow": { "type": "string", "description": "Consent narrative. TCR messageFlow: how recipients opt in, in prose. Under 40 characters is refused, and carriers reject vague descriptions — say where opt-in happens, that the box is unchecked by default, and that consent is not a condition of purchase. Required when `compliance.campaign.inherit != true`.", "minLength": 40 }, "use_cases": { "type": "array", "description": "Use cases. What the campaign sends, and an example of each. One to five entries; how they register is decided by volume, never declared. Required when `compliance.campaign.inherit != true`.", "maxItems": 5, "items": { "type": "object", "required": [ "use_case", "sample_messages" ], "properties": { "use_case": { "type": "string", "description": "Use case. What this entry sends. MIXED and LOW_VOLUME are refused — volume decides those.", "enum": [ "MARKETING", "ACCOUNT_NOTIFICATION", "CUSTOMER_CARE", "FRAUD_ALERT", "2FA", "DELIVERY_NOTIFICATION", "SECURITY_ALERT", "M2M", "HIGHER_EDUCATION", "POLLING_VOTING", "PUBLIC_SERVICE_ANNOUNCEMENT" ] }, "sample_messages": { "type": "array", "description": "Sample messages. TCR sample1..sample5 for this use case. One to five, each carrying the brand name and an opt-out instruction.", "maxItems": 5 } } } }, "opt_in_message": { "type": "string", "description": "Opt-in confirmation. TCR optinMessage. Should state message frequency and that rates may apply. Its presence is what sets subscriberOptin. Required when `compliance.campaign.inherit != true`." }, "opt_out_message": { "type": "string", "description": "Opt-out confirmation. TCR optoutMessage. Its presence is what sets subscriberOptout. Required when `compliance.campaign.inherit != true`." }, "help_message": { "type": "string", "description": "Help reply. TCR helpMessage. Its presence is what sets subscriberHelp. Required when `compliance.campaign.inherit != true`." }, "opt_in_keywords": { "type": "string", "description": "Opt-in keywords. TCR optinKeywords, comma separated, e.g. START,YES. Required when `compliance.campaign.inherit != true`.", "format": "csv_keywords" }, "opt_out_keywords": { "type": "string", "description": "Opt-out keywords. TCR optoutKeywords, comma separated. STOP, END, CANCEL, UNSUBSCRIBE and QUIT are honoured regardless of what is declared. Required when `compliance.campaign.inherit != true`.", "format": "csv_keywords" }, "help_keywords": { "type": "string", "description": "Help keywords. TCR helpKeywords, comma separated, e.g. HELP,INFO. Required when `compliance.campaign.inherit != true`.", "format": "csv_keywords" }, "privacy_policy_link": { "type": "string", "description": "Privacy policy URL. TCR privacyPolicyLink. Required when `compliance.campaign.inherit != true`.", "format": "url" }, "terms_and_conditions_link": { "type": "string", "description": "Terms and conditions URL. TCR termsAndConditionsLink. Required when `compliance.campaign.inherit != true`.", "format": "url" }, "volume": { "type": "string", "description": "Expected monthly volume. Decides how the campaign registers and which fee tier applies: below the low-volume threshold it registers as LOW_VOLUME with sub-use-cases, above it as a single use case or MIXED. Omitting it registers the campaign at the higher-fee standard tier." } } } } } }, "securitySchemes": { "CustomerApiKey": { "type": "apiKey", "description": "Customer API key for authentication. Use `sk_live_*` keys for production and `sk_test_*` keys for sandbox/testing. Pass via the `x-api-key` header.", "name": "x-api-key", "in": "header" } } }, "tags": [ { "name": "Messages", "description": "Send a message and follow what happened to it.\n\nOne endpoint sends on any channel: pass `channel: \"sent\"` and we pick between SMS, WhatsApp and RCS per recipient using your routing rules, or name a channel to pin it. A send is accepted asynchronously — `POST /v3/messages` returns an id, and delivery is reported through `GET /v3/messages/{id}`, its activities, or a webhook.\n\n**A message needs a sender.** What you can send, where, and at what cost is decided by the markets under **Channels** — so a recipient in a country you hold no sender for is refused here rather than queued.\n\n**A message can be resent on its id.** `POST /v3/messages/{id}/resend` puts a finished message — typically one BLOCKED for insufficient balance — back through the send pipeline. It is a new attempt, not a free retry: every policy runs again, the message is billed again, and its status webhooks fire again. A FILTERED message is never resendable.\n\n**A scheduled message can be called off.** `POST /v3/messages/{id}/cancel` cancels a send you scheduled with `scheduled_at`, as long as it has not been released yet. Cancelling is free, fires `message.cancelled`, and is final — a cancelled message cannot be resent." }, { "name": "Channels", "description": "The senders you send from, one per channel.\n\n**SMS is a list of markets**, each keyed by `(country, number_type)` — a customer can hold `us/10dlc` and `gb/alphanumeric` at once, so a market is addressed by the pair rather than by country alone. **WhatsApp and RCS are single**: a customer has one business account and one agent. **Voice is per number**: each number you hold can carry phone calls on its own (`POST /v3/channels/voice`), each with the callback URL Sent asks what to do with its calls, one of them is the default line for calls placed from your app, and voice tokens are minted under `POST /v3/channels/voice/tokens`. Read your voice numbers with `GET /v3/channels/voice` and change one with `PATCH /v3/channels/voice/{number}`.\n\n## Compliance lives on the market\n\nAdding a market records everything that market registers with, in its `compliance` object. Only **US `TEN_DLC`** registers with a regime — The Campaign Registry — and it is the only market whose compliance carries `brand` and `campaign`. Everywhere else compliance is documents, and many markets ask for none at all.\n\n`GET` and `PATCH` on a market return and accept the same shape, so what comes back can be sent back: an omitted key is left alone, and a key reported in `requirements` is the path into the body that clears it.\n\nCall `GET /v3/compliance/requirements` first — it answers what a market demands before you hold it, with a body you can fill in and post." }, { "name": "Compliance", "description": "What a market demands, before you have it.\n\nRequirements vary enormously and change without notice. US `TEN_DLC` registers a brand and a campaign with The Campaign Registry and asks a substantial set of questions; an alphanumeric sender pre-registers with documents in one country and needs nothing in another.\n\nThis is the authoritative answer for whichever market you ask about, and it is generated from the same declaration that validates the calls themselves — so it cannot drift from what is actually enforced. The response includes the request body to send, with every key that market wants already present and blank.\n\nWhat you supplied, as opposed to what is asked of you, is reported on the market under **Channels**." }, { "name": "Templates", "description": "Reusable message bodies with named variables.\n\nA template is substituted at send time from the values you pass, so the copy lives here rather than in your application. WhatsApp templates additionally need Meta's approval before they can be sent, and a template's channel status reports where that stands — an approved SMS template and an unapproved WhatsApp one are the same template in two states." }, { "name": "Contacts", "description": "The people you message, and their channel identities.\n\nA contact holds one identity per channel — a phone number, a WhatsApp number — so routing can choose between them for the same person. Opt-out is recorded against the contact and honoured on every send, whichever channel it came through.\n\n`GET /v3/contacts/{id}/message-summary` is the per-contact view of what you have sent and what happened to it." }, { "name": "Conversations", "description": "Inbound and outbound messages, grouped by the person they are with.\n\nA conversation is the thread for one contact across every channel — a reply by SMS and one by WhatsApp belong to the same conversation, because they are the same person talking to you.\n\nRead-only. Sending is **Messages**; a reply arrives here and through your webhooks." }, { "name": "Numbers", "description": "What a phone number actually is, before you send to it.\n\nA lookup returns the number's country, line type and carrier, which is what decides whether it is reachable on a channel and what it costs. Worth doing on import rather than on send: a landline in a contact list is a message that can never be delivered." }, { "name": "Voice", "description": "Phone calls from the numbers you hold, driven by your own callback URL.\n\n`POST /v3/channels/voice` enables a number for calls, with the callback URL Sent asks what to do with each call on it, and `POST /v3/channels/voice/tokens` mints a short-lived token that lets a user of your app place and receive calls as that number. When a call arrives or a caller presses a key, a signed question is POSTed to the callback URL and the answer decides the call; `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need before a real call reaches it, and `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret. The call events themselves (`call.completed` and the rest) arrive through your webhooks.\n\nEvery call is a record under `/v3/calls`: read it, list its recordings once one is ready, hang it up, start or stop recording, and add, mute or remove conference participants while it is live. A leg to a phone number runs for at most what your balance affords at the destination's rate." }, { "name": "Sender Profiles", "description": "Your customers, each sending as itself.\n\nA sender profile is a tenant of yours: it has its own API key, its own balance, and can have its own identity and senders — so your customers send under their own brand and never see Sent. Depth is one; a profile cannot create profiles.\n\n**Everything is inherited unless the profile owns it.** `{ \"name\": \"…\" }` alone gives you a usable profile immediately, running on your identity, your inbox and your billing. Supply a capability's fields and the profile owns that one instead.\n\n**A sender is the exception.** A brand and a campaign can be inherited; a number cannot. A profile either has a sender of its own or terminates through your shared routes.\n\nTo act for a profile on any other resource, send `x-profile-id` with your organization key rather than looking for a parallel set of endpoints." }, { "name": "Profiles", "description": "**Deprecated — use Sender Profiles.**\n\nThe original profile resource, kept because it has live callers. It still works, and its replacement is `/v3/sender-profiles`, which takes the identity and the campaign in one call instead of across three.\n\nNew integrations should not start here." }, { "name": "Webhooks", "description": "Delivery reports and inbound messages, pushed to you.\n\nSubscribe an endpoint to the event types you care about — `GET /v3/webhooks/event-types` lists them — and we POST each one as it happens, retrying on failure. Polling `GET /v3/messages/{id}` works and does not scale.\n\n**Verify the signature.** Every delivery is signed with your endpoint's secret; an unverified endpoint is one anybody can post to. `rotate-secret` replaces it, `test` sends a specimen event, and `GET /v3/webhooks/{id}/events` shows what we tried to deliver and what your endpoint answered — which is the first place to look when something appears to be missing." }, { "name": "Users", "description": "The people who can sign in to your organization, and what each may do.\n\nUsers are dashboard access and nothing else — they do not send, and removing one does not affect traffic. An API key is not a user: it belongs to the organization or to a sender profile, so revoking a person's access leaves your integration running." }, { "name": "Accounts", "description": "Who the current key is.\n\n`GET /v3/me` answers with the account the key authenticates as, which is the quickest way to tell a live key from a test one, an organization key from a sender profile's, and to confirm `x-profile-id` resolved to the profile you meant." } ] }