> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start pairing this assistant with a Brilo phone number

> Returns a short code to show the user and a link they can open. They sign up, pay and approve on that page; you call /poll until it says `completed`, and that response carries your API key.

Read the user the `user_code`, or open `verification_url_complete` if you can open a link — and show the code either way. Codes last 15 minutes. Nothing is charged until the user approves it themselves.

Pass `prefill` with your owner's name, email and phone if you know them, so their sign-up form arrives filled in.



## OpenAPI

````yaml /api-reference/openapi.json post /agent/onboarding/start
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Public REST API for Brilo. Authenticate by sending your API key as a Bearer
    token in the `Authorization` header.
  title: Brilo API
  version: '2025-03-02'
servers:
  - description: Production
    url: https://api.brilo.ai/v1
security: []
tags: []
paths:
  /agent/onboarding/start:
    post:
      tags:
        - Agent pairing
      summary: Start pairing this assistant with a Brilo phone number
      description: >-
        Returns a short code to show the user and a link they can open. They
        sign up, pay and approve on that page; you call /poll until it says
        `completed`, and that response carries your API key.


        Read the user the `user_code`, or open `verification_url_complete` if
        you can open a link — and show the code either way. Codes last 15
        minutes. Nothing is charged until the user approves it themselves.


        Pass `prefill` with your owner's name, email and phone if you know them,
        so their sign-up form arrives filled in.
      operationId: AgentPairingController_start
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartPairingDto'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartPairingResponseDto'
          description: ''
      security: []
components:
  schemas:
    StartPairingDto:
      properties:
        client_name:
          description: >-
            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.
          example: Grok
          maxLength: 64
          type: string
        prefill:
          allOf:
            - $ref: '#/components/schemas/PairingPrefillDto'
          description: >-
            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.
      type: object
    StartPairingResponseDto:
      properties:
        device_code:
          description: >-
            Your half of the pairing. Returned ONCE and never again — only its
            hash is stored — so keep it until the pairing finishes or fails.
          type: string
        expires_in:
          description: Seconds until the code stops working.
          example: 900
          type: number
        interval:
          description: Seconds to wait between polls. Polling faster is throttled.
          example: 5
          type: number
        user_code:
          description: >-
            The short code to read out or show the user. They type it at
            verification_url. Drawn from an alphabet with no confusable
            characters, so it never contains O, I, L, U, 0 or 1.
          example: 7FK9-BHDQ
          type: string
        verification_url:
          description: Where the user goes to type the code themselves.
          type: string
        verification_url_complete:
          description: >-
            The same page with the code already filled in. Use this when you can
            open a link for the user; use verification_url 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.
          type: string
      required:
        - device_code
        - user_code
        - verification_url
        - verification_url_complete
        - expires_in
        - interval
      type: object
    PairingPrefillDto:
      properties:
        email:
          example: maya@example.com
          maxLength: 128
          type: string
        first_name:
          example: Maya
          maxLength: 128
          type: string
        last_name:
          example: Chen
          maxLength: 128
          type: string
        name:
          description: >-
            Used only when first_name and last_name are both absent; split on
            the first space.
          example: Maya Chen
          maxLength: 128
          type: string
        phone:
          description: Normalised to E.164, with the US as the default region.
          example: '+14155550123'
          maxLength: 128
          type: string
      type: object

````