Skip to content
Esc
↑↓navigate↵open⌘Jpreview

List voicemails

Returns the phone system’s voicemails, newest first (ordered by createdAt descending with id as the tiebreak, so paging is deterministic). Filter by an inclusive createdAt window (dateFrom/dateTo). Each row carries the recordingSid of its audio; fetch the audio through the recording signed-URL operation, which requires the recordings scope. Requires the voicemails scope.

GET/customer/phone-systems/{phoneSystemId}/voicemails
Authorization
X-API-KeyAPI key · headerrequired
API key (sk_phones_* prefix) for programmatic access
Path parameters
phoneSystemIdstring<uuid>required
Phone system identifier, discoverable via the accessible phone systems operation.
Query parameters
pageinteger
1-indexed page number.
min 1 · default: 1
pageSizeinteger
Rows per page; at most 100.
min 1 · max 100 · default: 25
dateFromstring<date-time>
Inclusive lower bound (ISO 8601 UTC) on the row creation time.
dateTostring<date-time>
Inclusive upper bound (ISO 8601 UTC) on the row creation time.
Responses
200One page of voicemails with the total row count for the filter.
dataobject[]required
Show properties
Array of object
archivedbooleanrequired
Whether the voicemail has been archived.
callGroupIdstring<uuid> | anyrequired
Call group mailbox that received the voicemail, when group-addressed.
Show properties
Any of:
string<uuid>
string<uuid>
any
any
callSidstringrequired
Call identifier of the call that left the voicemail, as delivered in webhook payloads.
createdAtstring<date-time>required
When the voicemail was left; lists are ordered by this, descending.
durationintegerrequired
Voicemail duration in seconds.
extensionIdstring<uuid> | anyrequired
Extension mailbox that received the voicemail, when extension-addressed.
Show properties
Any of:
string<uuid>
string<uuid>
any
any
fromstringrequired
Calling party.
fromNamestring | anyrequired
Caller name, when known.
Show properties
Any of:
string
string
any
any
idstring<uuid>required
Voicemail identifier — the voicemailId carried by webhook payloads.
listenedbooleanrequired
Whether the voicemail has been listened to.
phoneSystemIdstring<uuid>required
Phone system this voicemail belongs to.
recordingSidstringrequired
Recording identifier of the voicemail audio — fetch via the signed-URL operation.
pageintegerrequired
min 1
pageSizeintegerrequired
min 1 · max 100
totalintegerrequired
min 0
totalPagesintegerrequired
min 0
400Validation failure: an unknown query parameter, a malformed date, or a pageSize above 100. Field problems are itemized in errors[].
codestringrequired
Stable machine identifier to branch on.
correlationIdstringrequired
Request identifier to quote to support.
detailstringrequired
User-safe explanation. Display it if you must; never match on it.
errorsobject[]
Field-level validation problems. Present on validation failures.
Show properties
Array of object
codestringrequired
Per-field machine code (REQUIRED, TOO_SMALL, …).
detailstringrequired
Human-readable description of the field problem.
pointerstringrequired
JSON Pointer to the offending request field.
paramsobject
Extra primitive detail about the condition, such as a limit that was hit.
retry_afterinteger
Seconds to wait before retrying, when a meaningful delay exists.
retryablebooleanrequired
Whether this condition is transient. Derived from code.
statusintegerrequired
Mirrors the HTTP status code.
titlestringrequired
Short human summary of the problem type.
typestringrequired
URL identifying the problem type. An identifier to match, not a link.
401The API key is missing, malformed, expired, or revoked.
codestringrequired
Stable machine identifier to branch on.
correlationIdstringrequired
Request identifier to quote to support.
detailstringrequired
User-safe explanation. Display it if you must; never match on it.
errorsobject[]
Field-level validation problems. Present on validation failures.
Show properties
Array of object
codestringrequired
Per-field machine code (REQUIRED, TOO_SMALL, …).
detailstringrequired
Human-readable description of the field problem.
pointerstringrequired
JSON Pointer to the offending request field.
paramsobject
Extra primitive detail about the condition, such as a limit that was hit.
retry_afterinteger
Seconds to wait before retrying, when a meaningful delay exists.
retryablebooleanrequired
Whether this condition is transient. Derived from code.
statusintegerrequired
Mirrors the HTTP status code.
titlestringrequired
Short human summary of the problem type.
typestringrequired
URL identifying the problem type. An identifier to match, not a link.
403The key lacks the voicemails:read scope, or is not a tenant API key.
codestringrequired
Stable machine identifier to branch on.
correlationIdstringrequired
Request identifier to quote to support.
detailstringrequired
User-safe explanation. Display it if you must; never match on it.
errorsobject[]
Field-level validation problems. Present on validation failures.
Show properties
Array of object
codestringrequired
Per-field machine code (REQUIRED, TOO_SMALL, …).
detailstringrequired
Human-readable description of the field problem.
pointerstringrequired
JSON Pointer to the offending request field.
paramsobject
Extra primitive detail about the condition, such as a limit that was hit.
retry_afterinteger
Seconds to wait before retrying, when a meaningful delay exists.
retryablebooleanrequired
Whether this condition is transient. Derived from code.
statusintegerrequired
Mirrors the HTTP status code.
titlestringrequired
Short human summary of the problem type.
typestringrequired
URL identifying the problem type. An identifier to match, not a link.
404The phone system does not exist or is not covered by the key.
codestringrequired
Stable machine identifier to branch on.
correlationIdstringrequired
Request identifier to quote to support.
detailstringrequired
User-safe explanation. Display it if you must; never match on it.
errorsobject[]
Field-level validation problems. Present on validation failures.
Show properties
Array of object
codestringrequired
Per-field machine code (REQUIRED, TOO_SMALL, …).
detailstringrequired
Human-readable description of the field problem.
pointerstringrequired
JSON Pointer to the offending request field.
paramsobject
Extra primitive detail about the condition, such as a limit that was hit.
retry_afterinteger
Seconds to wait before retrying, when a meaningful delay exists.
retryablebooleanrequired
Whether this condition is transient. Derived from code.
statusintegerrequired
Mirrors the HTTP status code.
titlestringrequired
Short human summary of the problem type.
typestringrequired
URL identifying the problem type. An identifier to match, not a link.
Request
curl -X GET "https://api.steerphones.com/v1/customer/phone-systems/%3Cuuid%3E/voicemails" \
  -H "X-API-Key: YOUR_API_KEY"
Response
{
  "data": [
    {
      "archived": true,
      "callGroupId": "<uuid>",
      "callSid": "string",
      "createdAt": "2024-01-01T00:00:00Z",
      "duration": 0,
      "extensionId": "<uuid>",
      "from": "string",
      "fromName": "string",
      "id": "<uuid>",
      "listened": true,
      "phoneSystemId": "<uuid>",
      "recordingSid": "string"
    }
  ],
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "totalPages": 0
}