PennyTone REST API

Fax + Voicemail + CDR + Recordings
API Version: v7
Format: JSON

Fax + Voicemail + CDR + Recordings REST API (v7)

This document describes the REST API endpoints for listing and retrieving fax files, voicemail messages, call detail records (CDRs), and call recordings.

Base URL: https://fqdn.tld/app/api/7 Auth: Authorization: Basic <TOKEN> Response: application/json

Base URL

All endpoints are relative to the following base URL:

https://fqdn.tld/app/api/7

Authentication

Authentication uses a raw token placed in the Authorization header and prefixed with Basic.

Header Value Notes
Authorization Basic <API_TOKEN> Token is used as-is (not base64-encoded in these examples). 
Authorization: Basic ${API_VALUE}
Security: Treat the token like a password. Don’t embed it in client-side code or public repos.

Common Query Parameters

All endpoints support the following optional query parameters:

Name Type Description Example
limit integer Maximum number of records to return. limit=50
offset integer Number of records to skip before starting the result set. offset=0
fields string Comma-separated list of fields to return. Any key present in the nested response object can be used as a field name. fields=domain_uuid,caller_id_number,start_stamp
Extra filters: Every field can also be used as a query parameter (server-side filtering), e.g. ?direction=inbound or ?caller_id_number=+12225551212.

Common Headers

Authorization: Basic ${API_VALUE}
Content-Type: application/json

File Downloads

All file downloads are returned in base64 format and must be base64-decoded to reconstruct the original bytes.

# macOS / Linux example:
# echo 'BASE64…' | base64 --decode > output.bin

Errors

Error response format may vary by endpoint. At minimum, use HTTP status codes to determine success/failure. When available, responses include fields like message and code.

200 OK 4xx Client Error 5xx Server Error
GET /fax_files
List fax files (received/transmitted). Use the returned fax_file_uuid to retrieve the file content.
200

Query Parameters

Name Type Description Example
fax_mode string Filter by fax direction. rx or tx
limit integer Max records to return. 50
offset integer Records to skip. 0
fields string Comma-separated fields. fax_file_uuid,fax_date,fax_file_type
fax_caller_id_number string Filter by caller id number (field-as-filter example). +12225551212
Behavior: This operation returns a list of fax file records. Extract fax_file_uuid and pass it to /get_fax.

Example Request

curl --request GET \
  --url 'https://fqdn.tld/app/api/7/fax_files?fax_mode=rx' \
  --header 'Authorization: Basic ${API_VALUE}' \
  --header 'Content-Type: application/json'

200 Response

{
  "fax_files": [
    {
      "domain_uuid": "179d8c66-db34-4fdb-90b3-dbc543ff5552",
      "fax_file_uuid": "aa0a10c0-6b6f-4a12-b126-96cfb8dec885",
      "fax_uuid": "4fd0d068-84a9-48c6-9c62-d9a57f036782",
      "fax_mode": "rx",
      "fax_recipient": null,
      "fax_destination": null,
      "fax_file_type": "tif",
      "fax_file_path": "/path/on/local/server/inbox/+12225551212-2026-01-30-00-38-11.tif",
      "fax_caller_id_name": "ABC Company",
      "fax_caller_id_number": "+12225551212",
      "fax_date": "2026-01-30 00:38:47+00",
      "fax_epoch": "1769733527",
      "fax_base64": null,
      "read_date": "2026-02-07 00:58:56.78131+00",
      "insert_date": null,
      "insert_user": null,
      "update_date": "2026-02-07 00:58:56.78131+00",
      "update_user": "1234556-cb5f-7747-8300-3232rf4ef533"
    }
  ]
}
GET /get_fax
Retrieve a fax file by UUID. The result field contains the file content as base64.
200

Query Parameters

Name Type Required Description
uuid string (UUID) Yes The fax_file_uuid returned by /fax_files.
Decoding: Base64-decode result to reconstruct the original file bytes.

Example Request

curl --request GET \
  --url 'https://fqdn.tld/app/api/7/get_fax?uuid=${fax_file_uuid}' \
  --header 'Authorization: Basic ${API_VALUE}' \
  --header 'Content-Type: application/json'

200 Response

[
  {
    "name": "get_fax",
    "message": "OK",
    "result": "BASE64_ENCODED_FILE_BYTES_HERE",
    "code": "200"
  }
]
GET /voicemail_message
List voicemail message records. Use voicemail_message_uuid to retrieve the audio via /get_voicemail.
200

Query Parameters

Name Type Description Example
limit integer Max records to return. 50
offset integer Records to skip. 0
fields string Comma-separated fields. voicemail_message_uuid,caller_id_number,created_epoch
caller_id_number string Filter by caller id number (field-as-filter example). +12225551212

Example Request

curl --request GET \
  --url 'https://fqdn.tld/app/api/7/voicemail_message' \
  --header 'Authorization: Basic ${API_VALUE}' \
  --header 'Content-Type: application/json'

200 Response

{
  "voicemail_messages": [
    {
      "domain_uuid": "179d8c66-db34-4fdb-90b3-dbc543ff5552",
      "voicemail_message_uuid": "507edc6f-a7d8-427a-8bb4-13b90fe1debe",
      "voicemail_uuid": "b30985e2-14b8-4d4d-922e-229d98ee6f3f",
      "created_epoch": "1768810477",
      "read_epoch": null,
      "caller_id_name": "ABC Company",
      "caller_id_number": "+12225551212",
      "message_length": "11",
      "message_status": "saved",
      "message_priority": null,
      "message_intro_base64": null,
      "message_base64": null,
      "message_transcription": null,
      "insert_date": null,
      "insert_user": null,
      "update_date": "2026-01-19 08:16:24.807309+00",
      "update_user": "7e9cf1a3-cc5e-4474-8300-0506d013f7a6"
    }
  ]
}
GET /get_voicemail
Retrieve voicemail audio by UUID. The result field contains base64-encoded audio bytes.
200

Query Parameters

Name Type Required Description
uuid string (UUID) Yes The voicemail_message_uuid returned by /voicemail_message.
Decoding: Base64-decode result to reconstruct the original audio bytes (often WAV).

Example Request

curl --request GET \
  --url 'https://fqdn.tld/app/api/7/get_voicemail?uuid=${voicemail_message_uuid}' \
  --header 'Authorization: Basic ${API_VALUE}' \
  --header 'Content-Type: application/json'

200 Response

[
  {
    "name": "get_voicemail",
    "message": "OK",
    "result": "BASE64_ENCODED_AUDIO_BYTES_HERE",
    "code": "200"
  }
]
GET /xml_cdr
Returns call detail records (CDRs). Supports standard query params, selective fields, and filtering by any field.
200

Query Parameters

Name Type Description Example
limit integer Max records to return. 100
offset integer Records to skip. 0
fields string Comma-separated fields. xml_cdr_uuid,caller_id_number,direction,start_stamp,status
direction string Filter by direction (field-as-filter example). inbound
caller_id_number string Filter by caller id number. +12225551212
caller_destination string Filter by the destination number the caller dialed (field-as-filter). +12225551212
hangup_cause string Filter by hangup cause (field-as-filter). NORMAL_CLEARING

Example Request

curl --request GET \
  --url 'https://fqdn.tld/app/api/7/xml_cdr?limit=50&offset=0&direction=inbound' \
  --header 'Authorization: Basic ${API_VALUE}' \
  --header 'Content-Type: application/json'

200 Response

{
  "xml_cdr": [
    {
      "xml_cdr_uuid": "02d4eaae-20a9-4be4-896b-f15cd3c8682f",
      "domain_uuid": "179d8c55-db43-4fbd-90b3-db77d55b201d",
      "provider_uuid": "590e627a-43d8-48a3-8a06-874cf78b5c45",
      "extension_uuid": null,
      "sip_call_id": "[email protected]",
      "domain_name": "dtcsb.lax.pennytone.com",
      "accountcode": null,
      "direction": "inbound",
      "default_language": null,
      "context": null,
      "caller_id_name": "+12225551212",
      "caller_id_number": "+12225551212",
      "caller_destination": "+12225551212",
      "source_number": null,
      "destination_number": "444",
      "start_epoch": "1769502577",
      "start_stamp": "2026-01-27 08:29:37+00",
      "answer_stamp": "1970-01-01 00:00:00+00",
      "answer_epoch": "0",
      "end_epoch": "1769502577",
      "end_stamp": "2026-01-27 08:29:37+00",
      "duration": "0",
      "mduration": "0",
      "billsec": "0",
      "billmsec": "0",
      "hold_accum_seconds": "0",
      "bridge_uuid": null,
      "read_codec": "PCMU",
      "read_rate": "8000",
      "write_codec": "PCMU",
      "write_rate": "8000",
      "remote_media_ip": "216.82.238.17",
      "network_addr": "216.82.238.158",
      "record_path": null,
      "record_name": null,
      "record_length": null,
      "record_transcription": null,
      "leg": "a",
      "originating_leg_uuid": null,
      "pdd_ms": "20",
      "rtp_audio_in_mos": "4.50",
      "last_app": "eval",
      "last_arg": "not_secure",
      "voicemail_message": false,
      "missed_call": null,
      "call_center_queue_uuid": null,
      "cc_side": null,
      "cc_member_uuid": null,
      "cc_queue_joined_epoch": null,
      "cc_queue": null,
      "cc_member_session_uuid": null,
      "cc_agent_uuid": null,
      "cc_agent": null,
      "cc_agent_type": null,
      "cc_agent_bridged": null,
      "cc_queue_answered_epoch": null,
      "cc_queue_terminated_epoch": null,
      "cc_queue_canceled_epoch": null,
      "cc_queue_canceled_reason": null,
      "cc_cancel_reason": null,
      "cc_cause": null,
      "waitsec": "0",
      "conference_name": null,
      "conference_uuid": null,
      "conference_member_id": null,
      "digits_dialed": null,
      "pin_number": null,
      "status": "no_answer",
      "hangup_cause": "NORMAL_CLEARING",
      "hangup_cause_q850": "16",
      "sip_hangup_disposition": "send_refuse",
      "ring_group_uuid": null,
      "ivr_menu_uuid": null,
      "call_flow": null,
      "xml": null,
      "json": null,
      "insert_date": "2026-01-28 17:33:42.553622+00",
      "insert_user": null,
      "update_date": null,
      "update_user": null
    }
  ]
}
GET /view_call_recordings
Returns calls that have a recording associated with them (recording metadata including UUID, filename, and path).
200

Query Parameters

Name Type Description Example
limit integer Max records to return. 50
offset integer Records to skip. 0
fields string Comma-separated fields. call_recording_uuid,call_recording_name,call_recording_date
caller_id_number string Filter by caller id number. +12225551212
caller_destination string Filter by the caller destination (field-as-filter). +12225551212

Example Request

curl --request GET \
  --url 'https://fqdn.tld/app/api/7/view_call_recordings?limit=50&offset=0' \
  --header 'Authorization: Basic ${API_VALUE}' \
  --header 'Content-Type: application/json'

200 Response

{
  "view_call_recordings": [
    {
      "domain_uuid": "179d8c55-db43-4fbd-90b3-db77d55b201d",
      "call_recording_uuid": "4fd042eb-175d-400d-8180-876dee6ffa26",
      "caller_id_name": "+12225551212",
      "caller_id_number": "+12225551212",
      "caller_destination": "+12225551212",
      "destination_number": "*411",
      "call_recording_name": "4fd042eb-175d-400d-8180-876dee6ffa26.mp3",
      "call_recording_path": "/var/lib/freeswitch/recordings/dtcsb.lax.pennytone.com/archive/2026/Feb/04",
      "call_recording_transcription": null,
      "call_recording_length": "3",
      "call_recording_date": "2026-02-04 02:57:43+00",
      "call_direction": "inbound"
    }
  ]
}
GET /call_recordings
Retrieve a call recording by UUID. Returns base64-encoded file bytes (decode to reconstruct the audio file).
200

Query Parameters

Name Type Required Description
uuid string (UUID) Yes The call_recording_uuid returned by /view_call_recordings.
Decoding: Base64-decode result to reconstruct the original file bytes (e.g. .mp3).

Example Request

curl --request GET \
  --url 'https://fqdn.tld/app/api/7/call_recordings?uuid=${call_recording_uuid}' \
  --header 'Authorization: Basic ${API_VALUE}' \
  --header 'Content-Type: application/json'

200 Response

[
  {
    "name": "call_recordings",
    "message": "OK",
    "result": "BASE64_ENCODED_AUDIO_FILE_BYTES_HERE",
    "code": "200"
  }
]

© PennyTone • Internal API reference • Single-file HTML + embedded CSS.