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.

Download, bulk add, and clear one phone book

Use /phonebooks/{id}/entries to work with all stored contacts in one selected tenant phone book. Replace {id} with the phone book ID and supply the tenant code or name through tenant. A global API key must also select a tenant for these operations.

Method	Operation	API key
GET	Download every stored entry and its field values as JSON, without pagination.	Full or read-only
POST	Append 1–500 entries in one request.	Full
DELETE	Delete all entries and their details from the selected phone book.	Full

The download covers database contacts. Automatically included extensions and short numbers are not synthesized into the export. Deleting entries preserves the phone book definition, its layout, and its phone assignments. Other phone books and tenants are unchanged. To delete the phone book itself, use the separate DELETE /phonebooks/{id} operation.

Download all contacts

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

The response includes the phone book ID and name, a contact count, and an entries array. Each contact has its entry ID, a values object keyed by phone book field codes, and the stored detail records. An empty phone book returns "count": 0 and "entries": [].

{
  "phonebook_id": 8,
  "name": "Customers",
  "count": 1,
  "entries": [{
    "id": 101,
    "values": {"NAME": "Alice Smith", "PHONE1": "00123456789"},
    "details": [
      {"id": 201, "item_id": 1, "code": "NAME", "value": "Alice Smith"},
      {"id": 202, "item_id": 2, "code": "PHONE1", "value": "00123456789"}
    ]
  }]
}

The IDs in these examples are illustrative. Existing field codes and item IDs can be inspected with GET /phonebooks/8?tenant=CANISTRACCI in the related.available_items data.

Add several contacts

Send an object containing an entries array. Each entry contains a values object. Use configured field codes such as NAME, PHONE1, PHONE2, and EMAIL; field codes are case-insensitive. Values can be strings, numbers, or null. Keep phone numbers as strings to preserve leading zeros and plus signs. Null and empty values are omitted, and each contact must contain at least one non-empty value. Unknown or duplicate field codes are rejected.

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries":[
    {"values":{"NAME":"Alice Smith","PHONE1":"00123456789"}},
    {"values":{"NAME":"Bob Jones","PHONE1":"+390212345678","EMAIL":"bob@example.com"}}
  ]}' \
  "https://pbx.example.com/pbx/openapi.php/phonebooks/8/entries?tenant=CANISTRACCI"

A successful request returns HTTP 201 with IDs in request order:

{"phonebook_id":8,"created":2,"ids":[101,102]}

Missing database fields use the applicable New Item Defaults, as with other creation APIs. Tenant and phone book ownership always come from the authenticated scope and URL. Send larger imports in batches of at most 500 contacts. POST appends contacts; repeating a successful request creates additional entries.

To reuse a download as input, build a new object containing entries with only each contact's values. Do not submit exported IDs, detail records, or the download's name/count fields.

Clear the selected phone book

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

{"phonebook_id":8,"deleted":true,"deleted_entries":2,"deleted_details":5}

No body is required. Clearing an already empty phone book succeeds with zero counts.

Transactions and failures

Each bulk POST or DELETE uses one checked database transaction. The phone book, entry, and detail tables must use InnoDB. If a contact cannot be inserted, the complete batch is rolled back, including entries inserted earlier in the request. Database truncation warnings also cause a rollback. A clear request followed by an import is two separate transactions.

Errors use the usual error.code and error.message response. Database failures include an error number and affected column when available, without exposing SQL or contact values. Transaction failures also include error.rolled_back (true if rollback completed, false if it could not be confirmed, null if no transaction started) and error.entry_index (the one-based entry position when available). Validation before a transaction can return the standard error shape without those additional fields.

{"error":{"code":"phonebook_bulk_failed","message":"Database error 1406 (column pd_pi_value) while saving entry 2 details. The transaction was rolled back.","rolled_back":true,"entry_index":2}}

If activity logging fails after the database commit, the response remains successful and includes a warning; the contacts have already been saved or deleted.

Alternative query-string routing

For installations that do not accept path information, use the same methods with:

https://pbx.example.com/pbx/openapi.php?object=phonebook&action=entries&id=8&tenant=CANISTRACCI