Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dialbird.io/llms.txt

Use this file to discover all available pages before exploring further.

Every endpoint except GET /health requires an OAuth 2.0 bearer access token, obtained through the Authorization Code flow against Dialbird’s OIDC provider. The token is a signed JWT with aud: "public-api", which the API verifies against the issuer’s JWKS.

​
OAuth 2.0 endpoints

PurposeURL
Authorizationhttps://api.dialbird.com/oidc/auth
Token / Refreshhttps://api.dialbird.com/oidc/token
The flow is Authorization Code (PKCE supported). After the user authorizes your client, exchange the authorization code at the token endpoint for an access token and refresh token.

​
Sending the token

Send the access token as a bearer token on every request: 
curl https://api.dialbird.com/api/v1/me \
  -H "Authorization: Bearer <access_token>"
Access tokens must never be passed as a ?access_token= query parameter. Requests that do are rejected with 401 invalid_token.

​
Scopes

Request only the scopes your integration needs. Each endpoint documents the scope it requires.
ScopeGrants
api:meRead the authenticated business, user, and granted scopes.
api:contacts:readRead contacts.
api:contacts:writeCreate and update contacts.
api:messages:readRead messages.
api:messages:writeSend messages.
api:calls:readRead calls.
api:webhooksManage webhook subscriptions.
A token missing the required scope for an endpoint receives 403 insufficient_scope.

​
Verifying a token

Call GET /me to confirm a token is valid and see what it resolves to. Zapier and other OAuth clients use this as their “Test Authentication” URL. 
curl https://api.dialbird.com/api/v1/me \
  -H "Authorization: Bearer <access_token>"

{
  "business": { "id": "biz_123", "name": "Acme Co" },
  "user": { "id": "usr_456" },
  "client_id": "zapier",
  "scopes": ["api:me", "api:messages:write"]
}

​
Token errors

StatusCodeMeaning
401missing_tokenNo Authorization header was sent.
401invalid_tokenThe token is malformed or failed verification.
401expired_tokenThe token is past its expiry — refresh it.
403insufficient_scopeThe token is valid but lacks the required scope.
403business_suspendedThe business is suspended or not associated.
When a token is expired, use the refresh token against the token endpoint to obtain a new access token rather than re-running the full authorization flow.