REST API

HTTP, signed.
Scoped. Audited.

Dials speaks HTTP. Every endpoint runs against a scoped session and writes a usage event. Pagination is consistent. Errors are typed. Versions are explicit.

Open the consoleBrowse SDKs

At a glance

The contract you can rely on.

Version
/v1
Stable v1. Deprecations announced 12 months in advance.
Auth
Bearer · scoped
OAuth 2.1 client credentials or platform-issued service tokens.
Errors
RFC 9457
Typed `problem+json` responses with `code`, `detail`, `instance`.
Rate limit
Per scope
Token-bucket with `X-RateLimit-*` headers on every reply.

Endpoint surface

Just enough verbs.

MethodPathDescription
GET/api/healthLiveness ping. Scoped session required.
GET/api/numbers/searchSearch the carrier inventory by NPA, NXX, LCA.
POST/api/numbers/holdAtomic hold against a DID before assignment.
POST/api/calls/outboundPlace a signed outbound call from a seat.
POST/api/calls/inbound/answerAnswer an incoming call under a route.
POST/api/messages/sendSend SMS, MMS, or RCS with a signed template + consent.
POST/api/agent/smokeRun the scoped smoke flow end-to-end.
GET/api/usage/eventsPaginated, signed usage events.
POST/api/webhooks/subscriptionsManage signed webhook subscriptions.

Idempotency

Retry without
dialing twice.

Pass an `Idempotency-Key` header on any unsafe request. Dials de-dupes on the key for 24 hours. Place an outbound call ten times in a row and the network sees one call.

  • 24-hour key window
  • Per-key replay safety
  • Returns prior response on hit
  • Audit event marks replay
HTTP · idempotent dial
POST /api/calls/outbound
Idempotency-Key: 01HQT4VX3KQK4Z…
{
  "to":   "+15125550100",
  "from": "+15125550199",
  "agent": "reception"
}
HTTP · 409 on conflict
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type":   "https://dials.com/errors/idempotency-mismatch",
  "title":  "Idempotency key reused with different body",
  "status": 409
}

Inspect the OpenAPI.

The full v1 OpenAPI document is generated from the running platform on every release.

Open the consoleChangelog