> ## 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.

# Check whether the user has finished, and collect the API key

> Call this every `interval` seconds with the `device_code` from /start.

`status` is one of: `pending` (they have not finished yet), `payment_failed` (card declined, the same code still works), `approved` or `provisioning` (paid, the number is being set up), `completed` (done — this response carries `api_key`, `phone_number` and `agent_id`), `denied`, `expired` or `failed` (stop polling).

Every response says what it means and what to do next, in `message` and `action`. The API key is only ever returned on `completed`: before then there is no phone number behind it.

Polling faster than `interval` returns 429 with `code: slow_down` and `retry_after` (also sent as a `Retry-After` header). Wait that long, then poll again.



## OpenAPI

````yaml /api-reference/openapi.json post /agent/onboarding/poll
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/poll:
    post:
      tags:
        - Agent pairing
      summary: Check whether the user has finished, and collect the API key
      description: >-
        Call this every `interval` seconds with the `device_code` from /start.


        `status` is one of: `pending` (they have not finished yet),
        `payment_failed` (card declined, the same code still works), `approved`
        or `provisioning` (paid, the number is being set up), `completed` (done
        — this response carries `api_key`, `phone_number` and `agent_id`),
        `denied`, `expired` or `failed` (stop polling).


        Every response says what it means and what to do next, in `message` and
        `action`. The API key is only ever returned on `completed`: before then
        there is no phone number behind it.


        Polling faster than `interval` returns 429 with `code: slow_down` and
        `retry_after` (also sent as a `Retry-After` header). Wait that long,
        then poll again.
      operationId: AgentPairingController_poll
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollPairingDto'
        required: true
      responses:
        '201':
          description: ''
      security: []
components:
  schemas:
    PollPairingDto:
      properties:
        device_code:
          description: >-
            The device_code returned by /start. Send it on every poll. It is a
            bearer secret: it is what collects the API key, so keep it on the
            machine that asked for it and never show it to the user — the short
            user_code is the one they read.
          type: string
      required:
        - device_code
      type: object

````