Phonebook

This page documents endpoints related to Phonebooks.

For shared REST API environment and authentication requirements, see REST API Overview.

Note

• The Phonebook owner implicitly owns all associated Contacts. Roles with permission to view all Phonebooks can access all Phonebooks without requiring explicit ownership. You can review role permissions here: https://portal.telsmart.eu/users/roles

Endpoints

Phonebooks

Base path: /v3/phonebook/phonebook/

Rate limit scope: "phonebook"

List phonebooks

GET /v3/phonebook/phonebook/?search={search}&ordering={ordering}&page={page}&page_size={page_size}

cURLPythonPHPC#.NETJavaJavaScript

curl --include --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer {token}" \
https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search={search}&ordering={ordering}&page={page}&page_size={page_size}

import requests

# Prepare headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}"
}

# Send the request
response = requests.get('https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search={search}&ordering={ordering}&page={page}&page_size={page_size}', headers=headers)

<?php
// Create a new cURL resource
$ch = curl_init();

// Prepare headers
$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer {token}';

// Set the header
curl_setopt($ch, CURL_HTTPHEADER, $headers);

// Indicate URL
curl_setopt($ch, CURLOPT_URL, 'https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search={search}&ordering={ordering}&page={page}&page_size={page_size}');

// Return the transfer as a string 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Indicate the method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Send the request
$result = curl_exec($ch);
curl_close($ch);

using (var httpClient = new HttpClient())
{
    // Prepare request
    using (var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search={search}&ordering={ordering}&page={page}&page_size={page_size}"))
    {
        // Prepare headers
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("Authorization", "Bearer {token}");

        // Send response
        var response = await httpClient.SendAsync(request);
    }
}

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search={search}&ordering={ordering}&page={page}&page_size={page_size}")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer {token}")
  .get();

const Http = new XMLHttpRequest();
Http.open("GET", "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search={search}&ordering={ordering}&page={page}&page_size={page_size}");

// Prepare headers
Http.setRequestHeader("Content-Type", "application/json");
Http.setRequestHeader("Authorization", "Bearer {token}");

// Send the request
Http.send();

// Handle the response
Http.onreadystatechange = (e) => {
    console.log(Http.responseText)
}

Concrete example

GET /v3/phonebook/phonebook/?search=john.doe@company.eu&ordering=-description&page=1&page_size=48

cURLPythonPHPC#.NETJavaJavaScript

curl --include --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer {token}" \
https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search=john.doe@company.eu&ordering=-description&page=1&page_size=48

import requests

# Prepare headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}"
}

# Send the request
response = requests.get('https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search=john.doe@company.eu&ordering=-description&page=1&page_size=48', headers=headers)

<?php
// Create a new cURL resource
$ch = curl_init();

// Prepare headers
$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer {token}';

// Set the header
curl_setopt($ch, CURL_HTTPHEADER, $headers);

// Indicate URL
curl_setopt($ch, CURLOPT_URL, 'https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search=john.doe@company.eu&ordering=-description&page=1&page_size=48');

// Return the transfer as a string 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Indicate the method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Send the request
$result = curl_exec($ch);
curl_close($ch);

using (var httpClient = new HttpClient())
{
    // Prepare request
    using (var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search=john.doe@company.eu&ordering=-description&page=1&page_size=48"))
    {
        // Prepare headers
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("Authorization", "Bearer {token}");

        // Send response
        var response = await httpClient.SendAsync(request);
    }
}

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search=john.doe@company.eu&ordering=-description&page=1&page_size=48")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer {token}")
  .get();

const Http = new XMLHttpRequest();
Http.open("GET", "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/?search=john.doe@company.eu&ordering=-description&page=1&page_size=48");

// Prepare headers
Http.setRequestHeader("Content-Type", "application/json");
Http.setRequestHeader("Authorization", "Bearer {token}");

// Send the request
Http.send();

// Handle the response
Http.onreadystatechange = (e) => {
    console.log(Http.responseText)
}

Query parameters

Parameter	Type	Description
search	string	Searchable fields: description, owners__username.
ordering	string	Orderable fields: priority, is_shared, description. Use ordering=description for ascending order and ordering=-description for descending order.
page	integer	Page number (1-based).
page_size	integer	Number of items per page. Default: 48.

Response format (example)

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "owners": [
        {
          "id": 10,
          "username": "john.doe@company.eu"
        },
        {
          "id": 11,
          "username": "jane.doe@company.eu"
        }
      ],
      "created": "2026-01-30T10:49:43.777103+01:00",
      "modified": "2026-02-02T13:53:08.219228+01:00",
      "description": "Test 2",
      "priority": 2,
      "is_shared": true
    }
  ]
}

Create a phonebook

POST /v3/phonebook/phonebook/

cURLPythonPHPC#.NETJavaJavaScript

curl --include --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer {token}" \
  -d '{"description": "My Phonebook", "priority": 1, "is_shared": true, "owners": [10, 11]}' \
https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/

import requests
import json

# Prepare headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}"
}

# Prepare data
myDict = {
    "description": "My Phonebook",
    "priority": 1,
    "is_shared": true,
    "owners": [
        10,
        11
    ]
}

# Send the request
response = requests.post('https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/', headers=headers, json=json.dumps(myDict))

<?php
// Create a new cURL resource
$ch = curl_init();

// Prepare headers
$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer {token}';

// Set the header
curl_setopt($ch, CURL_HTTPHEADER, $headers);

// Indicate URL
curl_setopt($ch, CURLOPT_URL, 'https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/');

// Return the transfer as a string 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Indicate the method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Prepare data
$data = array(
    "description" => "My Phonebook",
    "priority" => "1",
    "is_shared" => "True",
    "owners" => "[10, 11]",
};
$fields = json_encode($data);

// Set the body
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields);

// Send the request
$result = curl_exec($ch);
curl_close($ch);

using (var httpClient = new HttpClient())
{
    // Prepare request
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/"))
    {
        // Prepare headers
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("Authorization", "Bearer {token}");

        // Prepare body
        request.content = JsonContent.Create(new { 
            description = "My Phonebook"
            priority = "1"
            is_shared = "True"
            owners = "[10, 11]"
        });

        // Send response
        var response = await httpClient.SendAsync(request);
    }
}

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

// Prepare body
String jsonString = "{\"description\": \"My Phonebook\", \"priority\": 1, \"is_shared\": true, \"owners\": [10, 11]}";

Client client = ClientBuilder.newClient();
Response response = client.target("https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer {token}")
  .post(Entity.json(jsonString));

const Http = new XMLHttpRequest();
Http.open("POST", "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/");

// Prepare headers
Http.setRequestHeader("Content-Type", "application/json");
Http.setRequestHeader("Authorization", "Bearer {token}");

// Prepare data
const json = {
    "description": "My Phonebook",
    "priority": 1,
    "is_shared": true,
    "owners": [
        10,
        11
    ]
}

// Send the request
Http.send(JSON.stringify(json));

// Handle the response
Http.onreadystatechange = (e) => {
    console.log(Http.responseText)
}

Request body

Field	Type	Required	Description
description	string	Yes	Phonebook description. Validated for uniqueness.
priority	integer	Yes	Display/processing priority.
is_shared	boolean	Yes	Whether the phonebook is shared.
owners	integer[]	No	List of user IDs that own the phonebook.

Response format (example)

{
  "id": 1,
  "priority": 1,
  "description": "My Phonebook",
  "is_shared": true,
  "owners": [10, 11]
}

Error responses

400 Bad Request when a duplicate phonebook description exists in the same group:

{
  "type": "validation_error",
  "errors": [
    {
      "code": "invalid",
      "detail": "Phonebook with this name already exists.",
      "attr": "description.unique_description"
    }
  ]
}

Retrieve a phonebook

GET /v3/phonebook/phonebook/1/

cURLPythonPHPC#.NETJavaJavaScript

curl --include --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer {token}" \
https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/

import requests

# Prepare headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}"
}

# Send the request
response = requests.get('https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/', headers=headers)

<?php
// Create a new cURL resource
$ch = curl_init();

// Prepare headers
$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer {token}';

// Set the header
curl_setopt($ch, CURL_HTTPHEADER, $headers);

// Indicate URL
curl_setopt($ch, CURLOPT_URL, 'https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/');

// Return the transfer as a string 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Indicate the method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Send the request
$result = curl_exec($ch);
curl_close($ch);

using (var httpClient = new HttpClient())
{
    // Prepare request
    using (var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/"))
    {
        // Prepare headers
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("Authorization", "Bearer {token}");

        // Send response
        var response = await httpClient.SendAsync(request);
    }
}

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer {token}")
  .get();

const Http = new XMLHttpRequest();
Http.open("GET", "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/");

// Prepare headers
Http.setRequestHeader("Content-Type", "application/json");
Http.setRequestHeader("Authorization", "Bearer {token}");

// Send the request
Http.send();

// Handle the response
Http.onreadystatechange = (e) => {
    console.log(Http.responseText)
}

Response format (example)

{
  "id": 1,
  "owners": [
    {
      "id": 10,
      "username": "john.doe@company.eu"
    },
    {
      "id": 11,
      "username": "jane.doe@company.eu"
    }
  ],
  "created": "2026-01-30T10:49:43.777103+01:00",
  "modified": "2026-02-02T13:53:08.219228+01:00",
  "description": "My Phonebook",
  "priority": 1,
  "is_shared": true
}

Update a phonebook

PUT /v3/phonebook/phonebook/1/

cURLPythonPHPC#.NETJavaJavaScript

curl --include --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer {token}" \
  -d '{"description": "Updated Phonebook", "priority": 2, "is_shared": false, "owners": [10]}' \
https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/

import requests
import json

# Prepare headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}"
}

# Prepare data
myDict = {
    "description": "Updated Phonebook",
    "priority": 2,
    "is_shared": false,
    "owners": [
        10
    ]
}

# Send the request
response = requests.put('https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/', headers=headers, json=json.dumps(myDict))

<?php
// Create a new cURL resource
$ch = curl_init();

// Prepare headers
$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer {token}';

// Set the header
curl_setopt($ch, CURL_HTTPHEADER, $headers);

// Indicate URL
curl_setopt($ch, CURLOPT_URL, 'https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/');

// Return the transfer as a string 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Indicate the method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

// Prepare data
$data = array(
    "description" => "Updated Phonebook",
    "priority" => "2",
    "is_shared" => "False",
    "owners" => "[10]",
};
$fields = json_encode($data);

// Set the body
curl_setopt($ch, CURLOPT_PUTFIELDS, $fields);

// Send the request
$result = curl_exec($ch);
curl_close($ch);

using (var httpClient = new HttpClient())
{
    // Prepare request
    using (var request = new HttpRequestMessage(new HttpMethod("PUT"), "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/"))
    {
        // Prepare headers
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("Authorization", "Bearer {token}");

        // Prepare body
        request.content = JsonContent.Create(new { 
            description = "Updated Phonebook"
            priority = "2"
            is_shared = "False"
            owners = "[10]"
        });

        // Send response
        var response = await httpClient.SendAsync(request);
    }
}

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

// Prepare body
String jsonString = "{\"description\": \"Updated Phonebook\", \"priority\": 2, \"is_shared\": false, \"owners\": [10]}";

Client client = ClientBuilder.newClient();
Response response = client.target("https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer {token}")
  .put(Entity.json(jsonString));

const Http = new XMLHttpRequest();
Http.open("PUT", "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/");

// Prepare headers
Http.setRequestHeader("Content-Type", "application/json");
Http.setRequestHeader("Authorization", "Bearer {token}");

// Prepare data
const json = {
    "description": "Updated Phonebook",
    "priority": 2,
    "is_shared": false,
    "owners": [
        10
    ]
}

// Send the request
Http.send(JSON.stringify(json));

// Handle the response
Http.onreadystatechange = (e) => {
    console.log(Http.responseText)
}

Response format (example)

{
  "id": 1,
  "priority": 2,
  "description": "Updated Phonebook",
  "is_shared": false,
  "owners": [10]
}

Error responses

400 Bad Request when a duplicate phonebook description exists in the same group:

{
  "type": "validation_error",
  "errors": [
    {
      "code": "invalid",
      "detail": "Phonebook with this name already exists.",
      "attr": "description.unique_description"
    }
  ]
}

Delete a phonebook

DELETE /v3/phonebook/phonebook/1/

cURLPythonPHPC#.NETJavaJavaScript

curl --include --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer {token}" \
https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/

import requests

# Prepare headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}"
}

# Send the request
response = requests.delete('https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/', headers=headers)

<?php
// Create a new cURL resource
$ch = curl_init();

// Prepare headers
$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer {token}';

// Set the header
curl_setopt($ch, CURL_HTTPHEADER, $headers);

// Indicate URL
curl_setopt($ch, CURLOPT_URL, 'https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/');

// Return the transfer as a string 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Indicate the method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Send the request
$result = curl_exec($ch);
curl_close($ch);

using (var httpClient = new HttpClient())
{
    // Prepare request
    using (var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/"))
    {
        // Prepare headers
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("Authorization", "Bearer {token}");

        // Send response
        var response = await httpClient.SendAsync(request);
    }
}

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer {token}")
  .delete();

const Http = new XMLHttpRequest();
Http.open("DELETE", "https://api-eu-central-1.phoneserver.dev/v3/phonebook/phonebook/1/");

// Prepare headers
Http.setRequestHeader("Content-Type", "application/json");
Http.setRequestHeader("Authorization", "Bearer {token}");

// Send the request
Http.send();

// Handle the response
Http.onreadystatechange = (e) => {
    console.log(Http.responseText)
}

Note

A Phonebook cannot be deleted while it is assigned to a Device. It must first be unassigned.

Response

204 No Content

Error responses

400 Bad Request if the phonebook is used by devices:

{
  "type": "client_error",
  "errors": [
    {
      "code": "phonebook_in_use",
      "detail": "Phonebook is used in following devices: \"T42U - INT FW - 44dbd2f85d24\".",
      "attr": null
    }
  ]
}