Phone Numbers

Provision and manage phone numbers

List phone numbers

get

Retrieves all phone numbers for the organization or available inventory numbers for purchase. Supports filtering:

• action=assigned → Returns numbers owned by the organization (default behavior)

• action=available → Returns inventory numbers available for purchase

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.

Alternative: You can also use the x-api-key header instead of Authorization Bearer.

Query parameters

actionstring · enumOptional

Filter phone numbers by status.

• assigned → Numbers owned by the organization
• available → Inventory numbers available for purchase

Default: assignedPossible values:

countrystringOptional

ISO 3166-1 alpha-2 country code (required when action=available)

Example: NG

typestring · enumOptional

Number type filter (only applies when action=available)

Possible values:

limitinteger · min: 1 · max: 100Optional

Number of results (default 20, max 100)

Default: 20

offsetintegerOptional

Pagination offset

Default: 0

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.

Alternative: You can also use the x-api-key header instead of Authorization Bearer.

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

Supports two purchase flows:

• API flow: Provide inventory_id only. The system resolves e164, country, and type from inventory.
• Dashboard flow: Provide e164, country, and type explicitly. At least one flow's required fields must be present.

inventory_idstring · uuidOptional

ID of the phone number from inventory (API flow)

e164stringOptional

E.164 formatted phone number (Dashboard flow)

Example: [phone]

countrystringOptional

ISO 3166-1 alpha-2 country code (Dashboard flow)

Example: NG

typestring · enumOptional

Number type (Dashboard flow)

Possible values:

endpointIdstring · uuidOptional

Endpoint to attach immediately after purchase

totalCostCentsintegerOptional

Total cost in cents (setup + first month)

setupCostCentsintegerOptional

One-time setup cost in cents

monthlyCostCentsintegerOptional

Recurring monthly cost in cents

Responses

201

Phone number purchased successfully

application/json

idstring · uuidOptional

e164stringOptional

E.164 formatted phone number

Example: [phone]

countrystringOptional

ISO 3166-1 alpha-2 country code

Example: US

typestring · enumOptionalPossible values:

statusstring · enumOptionalPossible values:

endpoint_idstring · uuid · nullableOptional

allow_inboundbooleanOptionalDefault: true

allow_outboundbooleanOptionalDefault: false

sip_uristringOptional

SIP URI for inbound routing

Example: sip:[email protected]

organization_idstring · uuidOptional

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

400

Bad request. Possible error codes:

• MISSING_FIELDS — Neither inventory_id nor e164/country/type provided
• KYC_NOT_SUBMITTED — KYC verification not yet submitted
• KYC_INITIATED — KYC submitted but not yet reviewed
• KYC_DECLINED — KYC verification was declined
• KYC_PENDING — KYC verification is still pending
• NUMBER_NOT_AVAILABLE — The requested number is no longer available

application/json

401

Unauthorized - Invalid or missing API key

application/json

402

Insufficient balance (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"
}

API flow (inventory_id only)Dashboard flow (e164 + country + type)

{
  "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-03-20T17:14:19.138Z",
  "updated_at": "2026-03-20T17:14:19.138Z"
}

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.

Alternative: You can also use the x-api-key header instead of Authorization Bearer.

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-03-20T17:14:19.138Z",
  "updated_at": "2026-03-20T17:14:19.138Z",
  "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 or delete phone number

delete

Removes a phone number from the organization.

Two modes:

• Hard delete (default, no query param): Permanently removes the phone number record and frees the inventory slot.

• Soft release (?action=release): Marks the number as inactive and frees the inventory slot, but keeps the record for audit purposes.

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.

Alternative: You can also use the x-api-key header instead of Authorization Bearer.

Path parameters

idstring · uuidRequired

Phone number UUID

Query parameters

actionstring · enumOptional

Set to release to soft-release the number (marks inactive, keeps record). Omit for hard delete (removes record entirely).

Possible values:

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 soft-released (when ?action=release)

application/json

204

Phone number hard-deleted (default)

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: */*

{
  "success": true,
  "action": "released"
}

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.

Alternative: You can also use the x-api-key header instead of Authorization Bearer.

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

endpointIdstring · uuid · nullableOptional

Endpoint to route calls to

allowInboundbooleanOptional

Allow inbound calls

allowOutboundbooleanOptional

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: 94

{
  "endpointId": "660e8400-e29b-41d4-a716-446655440001",
  "allowInbound": true,
  "allowOutbound": 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-03-20T17:14:19.138Z",
  "updated_at": "2026-03-20T17:14:19.138Z"
}