IllyVoIPdevelopers

SIP & browser tokens

List SIP identities

Returns the account’s active primary, agent, and extra-line SIP identities.

Try in API Playground ↗Sign in to prepare and run this request.
GET/api/v1/sip/identities

Before you start

Use the account API key from a trusted server.

Result

Select an identity and use available_actions to choose its supported setup flow.

Charges and safe retries

Keep identity information within your authorized application.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X GET "https://api.illyvoip.com/api/v1/sip/identities" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}"

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/sip/identities", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY
  }
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/sip/identities');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY')
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "GET",
    "https://api.illyvoip.com/api/v1/sip/identities",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"]
    },
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request behavior

Each identity includes the connection mode and the actions your application can use. ip_address is present only for an IP-authenticated identity.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • identities: SIP identities and the actions available for each identity.
  • main_sip_user_id: The main SIP identity for the account.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON
{
  "status": "success",
  "identities": [
    {
      "sip_user_id": "1051",
      "display_name": "Main account",
      "is_main": true,
      "purpose": "primary",
      "auth_mode": "password",
      "available_actions": [
        "password_bootstrap",
        "browser_token"
      ]
    }
  ],
  "main_sip_user_id": "1051"
}
statusstringrequired
enum ["success"]
identitiesarray<object>required
View nested fields

Array items

sip_user_idstringrequired
display_namestringrequired
is_mainbooleanrequired
purposestringrequired
enum ["primary", "agent", "sip_line", "unknown"]
auth_modestringrequired

Current customer-selected SIP registration method.

enum ["password", "ip", "disabled", "unknown"]
available_actionsarray<string>required

Public SIP actions currently available for this identity.

View nested fields

Array items

Type: string

Constraints
{
  "enum": [
    "password_bootstrap",
    "browser_token"
  ]
}
ip_addressstringoptional

Present only for an authenticated owner when the identity uses IP authentication.

nullable true

Additional properties: not allowed.

main_sip_user_idstringrequired

The account primary SIP identity, or null when none is available.

nullable true

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "identities": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "sip_user_id": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "is_main": {
            "type": "boolean"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "primary",
              "agent",
              "sip_line",
              "unknown"
            ]
          },
          "auth_mode": {
            "type": "string",
            "description": "Current customer-selected SIP registration method.",
            "enum": [
              "password",
              "ip",
              "disabled",
              "unknown"
            ]
          },
          "available_actions": {
            "type": "array",
            "uniqueItems": true,
            "description": "Public SIP actions currently available for this identity.",
            "items": {
              "type": "string",
              "enum": [
                "password_bootstrap",
                "browser_token"
              ]
            }
          },
          "ip_address": {
            "type": "string",
            "nullable": true,
            "description": "Present only for an authenticated owner when the identity uses IP authentication."
          }
        },
        "required": [
          "sip_user_id",
          "display_name",
          "is_main",
          "purpose",
          "auth_mode",
          "available_actions"
        ]
      }
    },
    "main_sip_user_id": {
      "type": "string",
      "nullable": true,
      "description": "The account primary SIP identity, or null when none is available."
    }
  },
  "required": [
    "status",
    "identities",
    "main_sip_user_id"
  ]
}
400 The authenticated owner account no longer exists.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 Only an authenticated account owner may list SIP identities.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The API request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected backend error occurred and an incident code was returned.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 SIP connection setup is temporarily unavailable. Retry later; contact support if it persists.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable

Try this operation in Sandbox · Environment setup and limitations

Get SIP bootstrap dataCreate browser tokenGet browser bootstrap from token

Search API operations, parameters, SDK and webhooks.