Skip to main content
POST
/
v1
/
phone-numbers
Import phone number
curl --request POST \
  --url https://api.nixflex.com/v1/phone-numbers

Documentation Index

Fetch the complete documentation index at: https://docs.nixflex.com/llms.txt

Use this file to discover all available pages before exploring further.

Imports an existing Twilio number under one of your agents. Configures all webhooks (voice, SMS, recording status) to point at Nixflex automatically.

​
Request

curl -X POST https://api.nixflex.com/v1/phone-numbers \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+447446466847",
    "twilio_sid":   "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "twilio_token": "your_twilio_auth_token",
    "agent_id":     "agent_125207e452f8714a"
  }'

​
Body parameters

FieldTypeRequiredNotes
phone_numberstringYesE.164 format (+44...). Must already exist in your Twilio account
twilio_sidstringYesCustomer’s Twilio Account SID, format AC + 32 hex chars
twilio_tokenstringYesCustomer’s Twilio Auth Token
agent_idstringYesMust be an agent you own
camelCase versions also work: phoneNumber, twilioSid, twilioToken, agentId.

​
Response

201 Created: 
{
  "phone_number": {
    "phone_number": "+447446466847",
    "agent_id": "agent_125207e452f8714a",
    "twilio_number_sid": "PN451e0ddf654327e36baab58dfbcd30d6",
    "inbound_enabled": true,
    "outbound_enabled": true
  }
}

​
What this does

  1. Validates phone format and Twilio SID format
  2. Verifies the number exists in your Twilio account using the credentials
  3. Confirms the agent belongs to your Nixflex account
  4. Overwrites Twilio’s webhooks on that number (voice, SMS, status callbacks) to point at Nixflex
  5. Inserts a phone_numbers row linking number → agent → API key
Importing replaces all existing webhooks on the Twilio number. If you have other systems using this number, they will stop receiving calls or SMS.

​
Errors

CodeHTTPCause
missing_field400One of the 4 required fields is empty
invalid_phone_format400Phone number not in E.164 format
invalid_twilio_sid400SID doesn’t match ^AC[a-f0-9]{32}$
agent_not_found404agent_id doesn’t exist
agent_not_owned403Agent exists but belongs to a different API key
number_not_in_twilio404Number not in customer’s Twilio account
twilio_invalid_credentials401SID + token combination rejected by Twilio
twilio_auth_failed401Twilio error code 20003
number_already_imported409Number already attached to another agent

​
Use case: reseller onboarding

// 1. Buy a Twilio number from your Twilio account
const twilio = require('twilio')(YOUR_TWILIO_SID, YOUR_TWILIO_TOKEN);
const available = await twilio.availablePhoneNumbers('GB').local.list({ limit: 1 });
const purchased = await twilio.incomingPhoneNumbers.create({
  phoneNumber: available[0].phoneNumber
});

// 2. Attach it to your Nixflex agent
await fetch('https://api.nixflex.com/v1/phone-numbers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${NIXFLEX_KEY_ID}:${NIXFLEX_KEY_SECRET}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: purchased.phoneNumber,
    twilio_sid: YOUR_TWILIO_SID,
    twilio_token: YOUR_TWILIO_TOKEN,
    agent_id: 'agent_your_template'
  })
});