CallableAI

Documentation

Phone Verification API

The REST API for one-time phone verification — the base URL, the key, the shape of the flow, and why the call belongs on your server.

Verify a phone number from your own signup form, checkout, or login flow. CallableAI calls or texts your user with a code, holds it, and tells you whether what they typed matches.

  • Base URL — https://api.callable.com.au
  • Auth — Authorization: Bearer ck_live_…
  • Content type — application/json on any request with a body

Before you start

  1. Create an API key. In the dashboard: Settings → Security → API keys → Create API key. The key is shown once, at creation.
  2. Store it as a server-side secret — an environment variable, or your secret manager.
  3. Check it works:
curl https://api.callable.com.au/v1/ping \
  -H "Authorization: Bearer $CALLABLE_API_KEY"

{ "ok": true, "workspace_id": "…", "key_name": "Signup form", "scopes": ["otp"] }

/v1/ping is free and has no side effects. Make it your first request — a misconfigured key is otherwise indistinguishable from a delivery problem, and you would be debugging two things at once.

Call this from your server, never from a browser

An API key carries your entire workspace's API access. A fetch() from your own website will fail on CORS, by design: a page that could call this API would be a page shipping your key to every visitor who opens dev tools.

The supported shape is:

your user's browser  ──▶  your backend  ──▶  Callable API
        ▲                      │
        └──── your session ────┘

Your backend holds the key. Your own endpoint talks to us.

How verification works

  1. Your user enters their phone number.
  2. Your backend calls POST /v1/otp/send and stores the returned id against their session.
  3. CallableAI calls or texts them with a 6-digit code.
  4. They type it in; your backend calls POST /v1/otp/check.
  5. verified: true — the number is confirmed.

Record the outcome yourself. CallableAI does not remember that a number is "verified" for your product. The verification is a single short-lived event; persisting the result against your user is your side of the contract.

Channels

ChannelNeedsWhat your user gets
voice (default)Any phone number on your workspaceA call that reads the code out twice, then hangs up
smsA mobile number on your workspaceA text ending in the code, so autofill picks it up

Both are available to every workspace. SMS needs a mobile number specifically — landlines and 1300 numbers cannot send SMS.

voice is the default because it works with any number, including the landlines many workspaces start with.

There is no automatic fallback between channels. If your workspace cannot use the one you asked for, you get a 409 naming the reason rather than a silent switch you would not discover until the bill.

Verification SMS is one-way

The code goes out. Replies are not collected, and there is no inbox to read them in — if a customer texts back, nothing happens.

Two-way SMS, with rep conversations and inbound threads in the dashboard, is part of CallableAI CloudPhone. Talk to us if you need it.

Where to go next

← Previous

Manage your team

Next →

Authentication