Docs/API reference/Telephone numbers

List telephone numbers

List confirmed active telephone numbers available to the customer.

GET/v1/numbers

Required permission: numbers.readRead only

Start with Sandbox

Every example on this page uses https://sandbox.voycedconnect.eu/v1. After Voyced enables Live access, change the base URL to https://api.voycedconnect.eu/v1, use the separate Live API key and secret, request a new Live bearer token, then run GET /v1/test and GET /v1/capabilities again. Sandbox credentials and tokens never work in Live. See the complete go-live steps.

Example request

cURL

curl --request GET \
  --url 'https://sandbox.voycedconnect.eu/v1/numbers' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

PHP

<?php
$token = (string) getenv('VOYCED_BEARER_TOKEN');
if ($token === '') {
    throw new RuntimeException('Set VOYCED_BEARER_TOKEN.');
}

$curl = curl_init('https://sandbox.voycedconnect.eu/v1/numbers');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer ' . $token,
    ],
]);

$response = curl_exec($curl);
$status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($response === false) {
    $error = curl_error($curl);
    curl_close($curl);
    throw new RuntimeException($error);
}
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException('Voyced API HTTP ' . $status . ': ' . $response);
}
echo $response . PHP_EOL;

Node.js

const token = process.env.VOYCED_BEARER_TOKEN;
if (!token) throw new Error('Set VOYCED_BEARER_TOKEN.');

const response = await fetch('https://sandbox.voycedconnect.eu/v1/numbers', {
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${token}`,
  },
  redirect: 'error',
  signal: AbortSignal.timeout(20_000),
});
const result = await response.json();
if (!response.ok) {
  throw new Error(result.error?.message || `Voyced API HTTP ${response.status}`);
}
console.log(result);

Python

import os
import requests

token = os.environ["VOYCED_BEARER_TOKEN"]
response = requests.get(
    "https://sandbox.voycedconnect.eu/v1/numbers",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {token}",
    },
    timeout=20,
    allow_redirects=False,
)
response.raise_for_status()
print(response.json())

Example response

200 JSON

{
  "success": true,
  "environment": "sandbox",
  "request_id": "req_example1234567890",
  "data": {
    "items": [
      {
        "number": "+442012345678",
        "display_name": "Main line",
        "status": "active",
        "product_name": "Voyced Hosted IPPBX",
        "follow_me_available": true,
        "voicemail_available": true
      }
    ],
    "count": 1
  }
}

Response fields

Field	Description
`items`	List of active telephone-number records.
`items[].number`	Telephone number used in number-specific endpoint paths.
`items[].display_name`	Friendly name when available.
`items[].status`	Current public status of the number.
`items[].product_name`	Voyced service name when available.
`items[].follow_me_available`	Whether Follow-Me appears available for the number.
`items[].voicemail_available`	Whether voicemail appears available for the number.
`count`	Number of returned items.

Use the returned number

Copy items[].number into number-specific endpoint paths. Do not invent or convert it into another identifier.

Get a token
Request a temporary Sandbox bearer token.

Prepare the request
Select the endpoint and add a number when required.

Run and check
Review the HTTP status, response time and JSON.

Use a bearer token onlyThe page sends the token through the protected documentation proxy to Voyced Sandbox for this request. It is not saved. Reset or leave the page to clear the field.

The documentation proxy accepts approved Sandbox GET requests only. It cannot call Live. It does not place credentials in cookies, browser storage or URLs.

Common errors

HTTP	Code	Meaning
401	`invalid_token`	The token is invalid or expired.
403	`scope_denied`	The key does not have the required permission.
429	`rate_limited`	Too many requests were sent.
502	`request_failed`	Voyced could not complete the request.

All protected endpoints may also return missing_token, invalid_token, inactive_api_key or rate_limited. See the full error reference.