Appearance
SMS providers
Generated from
DialerDigital/corecommit0fc18008b3c8— specopenapi/dialer-v1.yamlv0.134.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.
What SMS is today
SMS sending through your own provider is available at the API level today; the complete collections messaging product is on the roadmap.
Per-tenant/region SMS routing registry.
Endpoints
| Method | Path | Summary |
|---|---|---|
GET | /v1/sms/providers | SMS provider registry |
POST | /v1/sms/providers | Register an SMS provider |
GET | /v1/sms/providers/{id} | Fetch one provider |
PATCH | /v1/sms/providers/{id} | Update a provider (scope immutable) |
POST | /v1/sms/providers/{id}/retire | Retire a provider (rows never delete) |
SMS provider registry
http
GET /v1/sms/providersResponses
200
Own rows + inherited empresa-wide rows.
| Field | Type | Required | Description |
|---|---|---|---|
sms_providers | array of SmsProvider | yes | |
sms_providers[].id | string (uuid) | no | |
sms_providers[].account_id | string (uuid) | no | |
sms_providers[].tenant_id | string (uuid) | null | no | null = empresa-wide (shared) provider inherited by every sede. |
sms_providers[].scope | empresa · sede | no | Derived from tenant_id. |
sms_providers[].adapter | http · telnyx · mock | no | |
sms_providers[].region | us · mx · eu | no | |
sms_providers[].name | string | no | |
sms_providers[].base_url | string | null | no | |
sms_providers[].default_from_e164 | string | null | no | Sender line used when POST /v1/sms/messages has no from; null = none (such a send is 422 from_required). |
sms_providers[].has_secret | boolean | no | The webhook secret NEVER rides the wire — this is the only signal a credential is stored. |
sms_providers[].status | active · disabled · retired | no | |
sms_providers[].created_at | string (date-time) | no | |
sms_providers[].updated_at | string (date-time) | no |
401 — Unauthorized
Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}429 — ApiKeyRateLimited
This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Register an SMS provider
http
POST /v1/sms/providersCarriers conventions: scope: "empresa" creates an account-wide row (tenant_id null) and requires an account_admin user (see User.role) — a member or a machine key gets 403; account_id/tenant_id are injected from the session, never the body; the scope of a row is immutable after creation. webhook_secret is WRITE-ONLY — responses carry has_secret, never the secret. For telnyx, webhook_secret holds the account's Ed25519 PUBLIC key (base64) and sends authenticate with the deployment-wide TELNYX_API_KEY bearer. The mock adapter (test/e2e harness) is refused with 400 unless the deployment allows it. Retire-only — no DELETE route exists.
Request body (JSON, required)
| Field | Type | Required | Description |
|---|---|---|---|
adapter | http · telnyx · mock | yes | |
region | us · mx · eu | yes | |
name | string | yes | |
default_from_e164 | string | null | no | Sender line used by POST /v1/sms/messages when the request has no from. E.164; anything else is 422. null = none declared. |
base_url | string | no | Internal-contract (http) adapter endpoint. MUST be an https:// URL on port 443 whose host resolves only to PUBLIC addresses — loopback, RFC1918, CGNAT (100.64/10), link-local (169.254/16, cloud metadata) and their IPv6 equivalents are refused 422 (SSRF guard), and the same check re-runs at send time against a fresh resolution. A port other than 443 is refused 422 even when the host is public: a public address is not a public service, and reaching an arbitrary port of it is reachability we do not grant. Reaching a destination that legitimately serves elsewhere needs an operator allowlist entry, not a tenant field. Blank means "use the deployment-wide endpoint". |
webhook_secret | string | no | Write-only. HMAC secret (http/mock) or Ed25519 public key, base64 (telnyx). |
status | active · disabled · retired | no | |
scope | sede · empresa | no | Request-only field; responses derive it from tenant_id. |
json
{
"adapter": "http",
"region": "us",
"name": "example-sms-provider",
"base_url": "",
"webhook_secret": "example-hmac-secret-not-a-real-one"
}Responses
201
Registered provider (has_secret, never the secret).
| Field | Type | Required | Description |
|---|---|---|---|
sms_provider | object (SmsProvider) | yes | |
sms_provider.id | string (uuid) | no | |
sms_provider.account_id | string (uuid) | no | |
sms_provider.tenant_id | string (uuid) | null | no | null = empresa-wide (shared) provider inherited by every sede. |
sms_provider.scope | empresa · sede | no | Derived from tenant_id. |
sms_provider.adapter | http · telnyx · mock | no | |
sms_provider.region | us · mx · eu | no | |
sms_provider.name | string | no | |
sms_provider.base_url | string | null | no | |
sms_provider.default_from_e164 | string | null | no | Sender line used when POST /v1/sms/messages has no from; null = none (such a send is 422 from_required). |
sms_provider.has_secret | boolean | no | The webhook secret NEVER rides the wire — this is the only signal a credential is stored. |
sms_provider.status | active · disabled · retired | no | |
sms_provider.created_at | string (date-time) | no | |
sms_provider.updated_at | string (date-time) | no |
400 — BadRequest
Malformed request (shape/type errors, invalid filters, bad timestamps).
json
{
"error": {
"code": "bad_request",
"message": "from must be RFC-3339"
}
}401 — Unauthorized
Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}422
default_from_e164 of a sede-scoped provider is not E.164 (code: sms_from_invalid) or not an ACTIVE number of the tenant (code: sms_from_not_owned; per-tenant knob sms_from_ownership_enforced, default true, core#2329). An empresa-wide row is not checked at write time: each send checks it against its own sede.
429 — ApiKeyRateLimited
This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Fetch one provider
http
GET /v1/sms/providers/{id}Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource UUID. Malformed or cross-tenant ids read as 404. |
Responses
200
The provider.
| Field | Type | Required | Description |
|---|---|---|---|
sms_provider | object (SmsProvider) | yes | |
sms_provider.id | string (uuid) | no | |
sms_provider.account_id | string (uuid) | no | |
sms_provider.tenant_id | string (uuid) | null | no | null = empresa-wide (shared) provider inherited by every sede. |
sms_provider.scope | empresa · sede | no | Derived from tenant_id. |
sms_provider.adapter | http · telnyx · mock | no | |
sms_provider.region | us · mx · eu | no | |
sms_provider.name | string | no | |
sms_provider.base_url | string | null | no | |
sms_provider.default_from_e164 | string | null | no | Sender line used when POST /v1/sms/messages has no from; null = none (such a send is 422 from_required). |
sms_provider.has_secret | boolean | no | The webhook secret NEVER rides the wire — this is the only signal a credential is stored. |
sms_provider.status | active · disabled · retired | no | |
sms_provider.created_at | string (date-time) | no | |
sms_provider.updated_at | string (date-time) | no |
401 — Unauthorized
Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}404 — NotFound
Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}429 — ApiKeyRateLimited
This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Update a provider (scope immutable)
http
PATCH /v1/sms/providers/{id}Editing an empresa-wide row (scope: "empresa", inherited by every sede of the account) takes an account_admin session, as creating it does: a member or a machine key gets 403. Switching to the mock adapter (test/e2e harness) is refused with 400 unless the deployment allows it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource UUID. Malformed or cross-tenant ids read as 404. |
Request body (JSON, required)
| Field | Type | Required | Description |
|---|---|---|---|
adapter | http · telnyx · mock | no | |
region | us · mx · eu | no | |
name | string | no | |
base_url | string | no | |
default_from_e164 | string | null | no | Sender line for sends without from; null clears it. |
webhook_secret | string | no | Write-only. |
status | active · disabled · retired | no |
json
{
"name": "postman-sms-renamed",
"status": "disabled"
}Responses
200
Updated provider.
| Field | Type | Required | Description |
|---|---|---|---|
sms_provider | object (SmsProvider) | yes | |
sms_provider.id | string (uuid) | no | |
sms_provider.account_id | string (uuid) | no | |
sms_provider.tenant_id | string (uuid) | null | no | null = empresa-wide (shared) provider inherited by every sede. |
sms_provider.scope | empresa · sede | no | Derived from tenant_id. |
sms_provider.adapter | http · telnyx · mock | no | |
sms_provider.region | us · mx · eu | no | |
sms_provider.name | string | no | |
sms_provider.base_url | string | null | no | |
sms_provider.default_from_e164 | string | null | no | Sender line used when POST /v1/sms/messages has no from; null = none (such a send is 422 from_required). |
sms_provider.has_secret | boolean | no | The webhook secret NEVER rides the wire — this is the only signal a credential is stored. |
sms_provider.status | active · disabled · retired | no | |
sms_provider.created_at | string (date-time) | no | |
sms_provider.updated_at | string (date-time) | no |
400 — BadRequest
Malformed request (shape/type errors, invalid filters, bad timestamps).
json
{
"error": {
"code": "bad_request",
"message": "from must be RFC-3339"
}
}401 — Unauthorized
Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}404 — NotFound
Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}422
default_from_e164 of a sede-scoped provider is not E.164 (code: sms_from_invalid) or not an ACTIVE number of the tenant (code: sms_from_not_owned; per-tenant knob sms_from_ownership_enforced, default true, core#2329).
429 — ApiKeyRateLimited
This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Retire a provider (rows never delete)
http
POST /v1/sms/providers/{id}/retireRetiring an empresa-wide row (scope: "empresa") takes an account_admin session: a member or a machine key gets 403.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource UUID. Malformed or cross-tenant ids read as 404. |
Responses
200
The retired provider.
| Field | Type | Required | Description |
|---|---|---|---|
sms_provider | object (SmsProvider) | yes | |
sms_provider.id | string (uuid) | no | |
sms_provider.account_id | string (uuid) | no | |
sms_provider.tenant_id | string (uuid) | null | no | null = empresa-wide (shared) provider inherited by every sede. |
sms_provider.scope | empresa · sede | no | Derived from tenant_id. |
sms_provider.adapter | http · telnyx · mock | no | |
sms_provider.region | us · mx · eu | no | |
sms_provider.name | string | no | |
sms_provider.base_url | string | null | no | |
sms_provider.default_from_e164 | string | null | no | Sender line used when POST /v1/sms/messages has no from; null = none (such a send is 422 from_required). |
sms_provider.has_secret | boolean | no | The webhook secret NEVER rides the wire — this is the only signal a credential is stored. |
sms_provider.status | active · disabled · retired | no | |
sms_provider.created_at | string (date-time) | no | |
sms_provider.updated_at | string (date-time) | no |
400 — BadRequest
Malformed request (shape/type errors, invalid filters, bad timestamps).
json
{
"error": {
"code": "bad_request",
"message": "from must be RFC-3339"
}
}401 — Unauthorized
Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}404 — NotFound
Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}429 — ApiKeyRateLimited
This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}