Phone Book

The Phone Book object is supported by the MiRTA PBX OpenAPI endpoint. This object is tenant-scoped. Tenant API keys must include tenant=CANISTRACCI; writes require a writable API key.

Object Summary

Property	Value
Object	phonebook
Primary path	/phonebooks
ID field	pb_id
Label field	pb_name
Primary source table	pb_phonebooks
Required on create	pb_name
Path aliases	/phonebook, /phonebooks, /phone_book, /phone_books

Endpoint Patterns

Action	Example pattern
List	GET https://pbx.example.com/pbx/openapi.php/phonebooks?tenant=CANISTRACCI
Get by ID	GET https://pbx.example.com/pbx/openapi.php/phonebooks/OBJECT_ID?tenant=CANISTRACCI
Create	POST https://pbx.example.com/pbx/openapi.php/phonebooks?tenant=CANISTRACCI
Update	PATCH https://pbx.example.com/pbx/openapi.php/phonebooks/OBJECT_ID?tenant=CANISTRACCI
Delete	DELETE https://pbx.example.com/pbx/openapi.php/phonebooks/OBJECT_ID?tenant=CANISTRACCI

Accepted Field Aliases

Request field	Source field
name	pb_name
include_extensions	pb_includeext
includeext	pb_includeext
include_short_numbers	pb_includeshortnum
includeshortnum	pb_includeshortnum
layout	pl_phonebooklayouts
items	pl_phonebooklayouts

Important Notes

• The layout field replaces the phone book field layout. Values can be phone book item codes such as NAME, PHONE1, EMAIL, and ROUTING, or pi_phonebookitems IDs.
• When layout is omitted on create, the API creates the default layout NAME, PHONE1, PHONE2, EMAIL, ROUTING.
• Deleting a phone book removes its layout rows, entries, entry details, and phone assignment rows.

Examples

List Phone Books

Returns the phone books visible to the key and scope.

curl -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/phonebooks?tenant=CANISTRACCI"

Get Phone Book

Reads one object by its internal ID.

curl -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/phonebooks/OBJECT_ID?tenant=CANISTRACCI"

Create Phone Book

Creates a new object. Use the short aliases shown above or the source field names.

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs API Phone Book",
  "include_extensions": "no",
  "include_short_numbers": "no",
  "layout": [
    "NAME",
    "PHONE1",
    "PHONE2",
    "EMAIL",
    "ROUTING"
  ]
}' \
  "https://pbx.example.com/pbx/openapi.php/phonebooks?tenant=CANISTRACCI"

Edit Phone Book

Updates only the supplied fields.

curl -X PATCH \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs API Phone Book Updated",
  "layout": [
    "NAME",
    "PHONE1",
    "EMAIL",
    "ROUTING"
  ]
}' \
  "https://pbx.example.com/pbx/openapi.php/phonebooks/OBJECT_ID?tenant=CANISTRACCI"

Delete Phone Book

Deletes the object. Check references before deleting configuration used by routing or reporting.

curl -X DELETE \
  -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/phonebooks/OBJECT_ID?tenant=CANISTRACCI"

Replace Phone Book Layout

Replaces the pl_phonebooklayouts rows for the selected phone book.

curl -X PATCH \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "layout": [
    "NAME",
    "PHONE1",
    "EMAIL",
    "ROUTING"
  ]
}' \
  "https://pbx.example.com/pbx/openapi.php/phonebooks/OBJECT_ID?tenant=CANISTRACCI"

Common Errors

Error	Meaning
missing_api_key	No API key was supplied in the query string, X-API-Key, or bearer token.
invalid_api_key	The supplied key does not match the tenant or global API key.
tenant_required	A tenant code is required for tenant-scoped writes or tenant-key reads.
read_only_api_key	The key can read data but cannot create, update, or delete objects.
missing_required_field	A required create field is missing.