Skip to main content
POST
Start pairing this assistant with a Brilo phone number

Body

application/json
client_name
string

What to call your assistant on the approval screen, e.g. "Grok". Shown to the owner as an UNVERIFIED claim, because anyone can send anything here — it helps a person recognise the request they just made, and it is not a credential. Omit it and the screen says "your assistant" instead, which is the honest fallback.

Maximum string length: 64
Example:

"Grok"

prefill
object

Your owner's details, if you know them, so the sign-up form arrives filled in. Every field is optional; invalid values are dropped silently and never fail the request. Brilo does not store or log these: they travel only in the #fragment of verification_url_complete, which the owner's browser keeps to itself.

Response

201 - application/json
action
string
required

What to do next, in plain English. Follow it: send owner_message as written, then poll.

device_code
string
required

Your half of the pairing. Returned ONCE and never again — only its hash is stored — so keep it until the pairing finishes or fails.

expires_in
number
required

Seconds until the code stops working.

Example:

900

interval
number
required

Seconds to wait between polls. Polling faster is throttled.

Example:

5

message
string
required

What just happened, in plain English.

Example:

"Pairing started. Your owner signs up, pays and approves on the link."

owner_message
string
required

Ready-to-send text for your owner, built from this pairing. It has the link with the code already in it, and the code on its own line. Send it as is, with the link tappable. Do not rebuild it from verification_url, which has no code in it. In the example, <user_code> stands for your real code; the response always carries the real one.

Example:

"Here's your link: https://dashboard.brilo.ai/agent-setup?code=<user_code>\nYour code: <user_code>\nSign up and pay on that page. The code should match. It lasts 15 minutes."

user_code
string
required

The short code to read out or show the user. They type it at verification_url. Eight characters in two groups of four joined by a hyphen, from an alphabet with no confusable characters, so it never contains O, I, L, U, 0 or 1. Always use the value in your own response; never make one up.

Example:

"<user_code>"

verification_url
string
required

The page without the code. Only for assistants that can only speak: read this out with user_code. If you can send a link, send verification_url_complete instead.

verification_url_complete
string
required

The same page with the code already filled in. This is the link to send (owner_message already contains it). Use verification_url only when you can only speak. Show the code either way: matching it against what you displayed is the check that stops someone being walked through this flow by an attacker.