Quick Start

From zero to an active number in a few steps: contract in the dashboard or API, wait for activation, and use the number as the origin for calls and SMS.

In short

Contract a number in the dashboard or with POST /v1/phone-numbers/orders.
Copy the id or number to use as origin (from) in voice and SMS.
Configure inbound — what to do when someone calls that number.

Before you start

Item	Required?
API Key with the right scopes	Yes — see Scopes
Authentication	`Authorization: Bearer sk_live_...` or `x-api-key`
Base URL	`https://api.notifique.dev`

1. Contract a number

Via dashboard

Settings → Phone numbers: search by country and area code, select the number, and pay the monthly fee. When payment confirms, the number becomes active and you can dial.

Via API (`phone_numbers:create`)

Creates an order with PIX or card payment:

POST /v1/phone-numbers/orders
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "phoneE164": "+5511987654321",
  "countryCode": "BR",
  "phoneNumberType": "local",
  "features": ["voice", "sms"],
  "billingType": "PIX",
  "label": "Atendimento SP",
  "customer": {
    "name": "Empresa Exemplo LTDA",
    "email": "financeiro@exemplo.com.br",
    "cpfCnpj": "12345678000199",
    "mobilePhone": "5511999887766"
  },
  "regulatory": {
    "endUserType": "BUSINESS",
    "contactName": "Maria Silva",
    "contactPhone": "5511999887766",
    "cpfCnpj": "12345678000199",
    "businessName": "Empresa Exemplo LTDA",
    "street": "Av. Paulista",
    "addressNumber": "1000",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310100"
  }
}

Response (201), example

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_abc",
      "phoneE164": "+5511987654321",
      "status": "PENDING_PAYMENT",
      "monthlyPriceBrlCents": 2990
    },
    "payment": {
      "id": "pay_xyz",
      "status": "PENDING",
      "billingType": "PIX",
      "pixCopyPaste": "00020126..."
    },
    "reservedUntil": "2026-08-31T15:30:00.000Z"
  }
}

Track with GET /v1/phone-numbers/orders/:orderId. After payment → webhook phone_number.activated. Regulated countries may require documents — see .../regulatory/* routes in the OpenAPI reference.

2. Search available numbers

Before contracting, list what’s in the catalog:

GET /v1/phone-numbers/available?countryCode=BR&areaCode=11
Authorization: Bearer sk_live_xxxxx

Optional parameters:

Parameter	Description
`countryCode`	Country (default `US`)
`phoneNumberType`	e.g. `local`, `mobile`
`areaCode`	Area code
`contains`	Digits the number must contain

Response (200), example

{
  "success": true,
  "data": [
    {
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "region": "SP",
      "locality": "São Paulo",
      "monthlyPriceBrlCents": 2990
    }
  ]
}

3. List workspace numbers

See the numbers you’ve already contracted:

GET /v1/phone-numbers
Authorization: Bearer sk_live_xxxxx

Released numbers (RELEASED) don’t appear in the list. Response (200), example

{
  "success": true,
  "data": [
    {
      "id": "clxx_phone_1",
      "workspaceId": "clxx_ws",
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "status": "ACTIVE",
      "monthlyPriceBrlCents": 2990,
      "renewsAt": "2026-07-11T00:00:00.000Z",
      "label": "Atendimento SP",
      "inboundVoiceAction": "WEBHOOK_CONTROL",
      "forwardToE164": null,
      "inboundTtsText": null,
      "inboundTtsVoice": null,
      "recordingEnabled": false,
      "createdAt": "2026-06-11T12:00:00.000Z",
      "updatedAt": "2026-06-11T12:00:00.000Z"
    }
  ]
}

Use id or phoneE164 as from in calls and SMS.

4. Get a number

GET /v1/phone-numbers/clxx_phone_1
Authorization: Bearer sk_live_xxxxx

5. Configure what happens when someone calls

When a customer calls your number, you define the behavior:

PATCH /v1/phone-numbers/clxx_phone_1
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

Example — forward to another number:

{
  "label": "Suporte comercial",
  "inboundVoiceAction": "FORWARD",
  "forwardToE164": "+5511999887766",
  "recordingEnabled": true
}

Inbound options

Option	What happens when someone calls
`WEBHOOK_CONTROL`	Your system receives the event and controls the call (default)
`FORWARD`	Forwards to `forwardToE164`
`TTS_HANGUP`	Speaks text (`inboundTtsText`) and hangs up
`REJECT`	Rejects the call
`VOICEMAIL`	Records a message

For spoken message: inboundTtsText + optional inboundTtsVoice (female-natural, male-natural, etc.).

6. Lifecycle webhooks

When the number status changes (payment, suspension, release):

phone_number.activated — number is active, can dial
phone_number.past_due — renewal overdue
phone_number.suspended — suspended
phone_number.released — returned to catalog

Details: Webhook events. For call events (voice.call.*), see Voice — webhooks.

Quick summary

Goal	Path
Search available	`GET /v1/phone-numbers/available`
List contracted	`GET /v1/phone-numbers`
Detail	`GET /v1/phone-numbers/:id`
Configure inbound	`PATCH /v1/phone-numbers/:id`
Origin for calls / SMS	`id` or `phoneE164` in `POST /v1/voice/calls` or `POST /v1/sms/messages`
Contract via API	`POST /v1/phone-numbers/orders`

Voice

Voice: Chamadas

Voice: Fluxos IVR

Phone numbers

Números de Telefone

Phone Numbers

In short

Before you start

1. Contract a number

Via dashboard

Via API (`phone_numbers:create`)

2. Search available numbers

3. List workspace numbers

4. Get a number

5. Configure what happens when someone calls

Inbound options

6. Lifecycle webhooks

Quick summary

Next steps

​In short

​Before you start

​1. Contract a number

​Via dashboard

​Via API (phone_numbers:create)

​2. Search available numbers

​3. List workspace numbers

​4. Get a number

​5. Configure what happens when someone calls

​Inbound options

​6. Lifecycle webhooks

​Quick summary

​Next steps

In short

Before you start

1. Contract a number

Via dashboard

Via API (`phone_numbers:create`)

2. Search available numbers

3. List workspace numbers

4. Get a number

5. Configure what happens when someone calls

Inbound options

6. Lifecycle webhooks

Quick summary

Next steps