Phone Numbers

Provision and manage phone numbers

List phone numbers

get

Retrieves all phone numbers for the organization

Authorizations

BearerAuth

AuthorizationstringRequired

API key in format kros_live_xxxx for production or kros_test_xxxx for testing. Also accepts JWT tokens from Supabase Auth for dashboard sessions.

Header parameters

x-organization-idstring · uuidOptional

Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.

Responses

200

List of phone numbers

application/json

401

Unauthorized - Invalid or missing API key

application/json

get

/phone-numbers

HTTPcURLJavaScriptPython

GET /v1/phone-numbers HTTP/1.1
Host: api.krosai.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "e164": "[phone]",
    "country": "US",
    "type": "local",
    "status": "active",
    "allow_inbound": true,
    "allow_outbound": true,
    "endpoint_id": "660e8400-e29b-41d4-a716-446655440001",
    "sip_uri": "sip:[email protected]",
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Purchase a phone number

post

Purchases a new phone number from the inventory.

Authorizations

BearerAuth

AuthorizationstringRequired

API key in format kros_live_xxxx for production or kros_test_xxxx for testing. Also accepts JWT tokens from Supabase Auth for dashboard sessions.

Header parameters

x-organization-idstring · uuidOptional

Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.

Body

application/json

inventory_idstring · uuidRequired

ID of the phone number from inventory

Responses

201

Phone number purchased successfully

application/json

400

Bad request - Invalid parameters or request body

application/json

401

Unauthorized - Invalid or missing API key

application/json

402

Insufficient balance

application/json

403

Forbidden - Insufficient permissions or KYC required

application/json

post

/phone-numbers

HTTPcURLJavaScriptPython

POST /v1/phone-numbers HTTP/1.1
Host: api.krosai.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "inventory_id": "770e8400-e29b-41d4-a716-446655440002"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "e164": "[phone]",
  "country": "US",
  "type": "local",
  "status": "active",
  "endpoint_id": "123e4567-e89b-12d3-a456-426614174000",
  "allow_inbound": true,
  "allow_outbound": false,
  "sip_uri": "sip:[email protected]",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-02-03T20:23:27.709Z",
  "updated_at": "2026-02-03T20:23:27.709Z"
}

Get phone number details

get

Retrieves details including SIP credentials for routing

Authorizations

BearerAuth

AuthorizationstringRequired

API key in format kros_live_xxxx for production or kros_test_xxxx for testing. Also accepts JWT tokens from Supabase Auth for dashboard sessions.

Path parameters

idstring · uuidRequired

Phone number UUID

Header parameters

x-organization-idstring · uuidOptional

Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.

Responses

200

Phone number details with SIP credentials

application/json

404

Resource not found

application/json

get

/phone-numbers/{id}

HTTPcURLJavaScriptPython

GET /v1/phone-numbers/{id} HTTP/1.1
Host: api.krosai.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "e164": "[phone]",
  "country": "US",
  "type": "local",
  "status": "active",
  "endpoint_id": "123e4567-e89b-12d3-a456-426614174000",
  "allow_inbound": true,
  "allow_outbound": false,
  "sip_uri": "sip:[email protected]",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-02-03T20:23:27.709Z",
  "updated_at": "2026-02-03T20:23:27.709Z",
  "sip_credentials": {
    "sip_domain": "sip.krosai.com",
    "sip_port": 5060,
    "sip_username": "text",
    "sip_password": "text"
  },
  "inventory": {
    "monthly_cost_cents": 100,
    "setup_cost_cents": 0,
    "capabilities": {
      "voice": true,
      "sms": true,
      "fax": true
    }
  }
}

Release phone number

delete

Releases the phone number back to the inventory

Authorizations

BearerAuth

AuthorizationstringRequired

API key in format kros_live_xxxx for production or kros_test_xxxx for testing. Also accepts JWT tokens from Supabase Auth for dashboard sessions.

Path parameters

idstring · uuidRequired

Phone number UUID

Header parameters

x-organization-idstring · uuidOptional

Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.

Responses

204

Phone number released

404

Resource not found

application/json

delete

/phone-numbers/{id}

HTTPcURLJavaScriptPython

DELETE /v1/phone-numbers/{id} HTTP/1.1
Host: api.krosai.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update phone number settings

patch

Authorizations

BearerAuth

AuthorizationstringRequired

API key in format kros_live_xxxx for production or kros_test_xxxx for testing. Also accepts JWT tokens from Supabase Auth for dashboard sessions.

Path parameters

idstring · uuidRequired

Phone number UUID

Header parameters

x-organization-idstring · uuidOptional

Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.

Body

application/json

endpoint_idstring · uuid · nullableOptional

Endpoint to route calls to

allow_inboundbooleanOptional

Allow inbound calls

allow_outboundbooleanOptional

Allow outbound calls

statusstring · enumOptionalPossible values:

Responses

200

Phone number updated

application/json

400

Bad request - Invalid parameters or request body

application/json

404

Resource not found

application/json

patch

/phone-numbers/{id}

HTTPcURLJavaScriptPython

PATCH /v1/phone-numbers/{id} HTTP/1.1
Host: api.krosai.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "endpoint_id": "660e8400-e29b-41d4-a716-446655440001",
  "allow_inbound": true,
  "allow_outbound": true
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "e164": "[phone]",
  "country": "US",
  "type": "local",
  "status": "active",
  "endpoint_id": "123e4567-e89b-12d3-a456-426614174000",
  "allow_inbound": true,
  "allow_outbound": false,
  "sip_uri": "sip:[email protected]",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-02-03T20:23:27.709Z",
  "updated_at": "2026-02-03T20:23:27.709Z"
}