IllyVoIPdevelopers

Calls & Recordings

List calls

Returns historical calls for the account, including public `CALL-...` IDs. Treat each ID as an opaque value and use it unchanged for call and recording lookups.

Try in API Playground ↗Sign in to prepare and run this request.
GET/api/v1/calls

Before you start

Choose filters and a bounded page size for the call history you need.

Result

Use pagination.next_cursor while pagination.has_more is true.

Charges and safe retries

The default page is100 calls and the maximum 500. Treat cursors as opaque; do not build them yourself.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X GET "https://api.illyvoip.com/api/v1/calls?days=7&limit=100" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}"

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/calls?days=7&limit=100", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY
  }
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/calls?days=7&limit=100');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY')
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "GET",
    "https://api.illyvoip.com/api/v1/calls?days=7&limit=100",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"]
    },
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request parameters

Query parameters

sip_user_idstringoptional

Filter to one account-owned SIP identity. Defaults to the authenticated account main identity.

minLength 1maxLength 64pattern "^[A-Za-z0-9_.-]{1,64}$"
daysintegeroptional

UTC calendar-day window from 1 to 31 days, including today through request time. Defaults to 7.

default 7minimum 1maximum 31
limitintegeroptional

Calls per page from 1 to 500. Defaults to 100.

default 100minimum 1maximum 500
cursorstringoptional

Opaque continuation token returned by the previous page. Keep the original days, limit, and SIP identity unchanged.

minLength 1maxLength 4096pattern "^[A-Za-z0-9_-]+$"

Request behavior

Use this for CDR reporting, reconciliation, and recording lookups. Results are unique by call_id and use bounded cursor pagination: follow pagination.next_cursor while pagination.has_more is true. started_at is ISO-8601 UTC and the deprecated starttime alias remains a naive UTC string for v1 compatibility.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • calls: Call records or active calls matching the request.
  • pagination: Pagination state; follow the returned continuation values without constructing your own.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON
{
  "status": "success",
  "calls": [
    {
      "call_id": "CALL-71B25F2E91BB028B",
      "sip_user_id": "1051",
      "from": "1051",
      "to": "+49301234567",
      "direction": "outgoing",
      "status": "completed",
      "number": "+49301234567",
      "started_at": "2026-08-24T10:00:00Z",
      "starttime": "2026-08-24 10:00:00",
      "duration_seconds": 45,
      "hangup_cause": "NORMAL_CLEARING",
      "failure_reason_code": null,
      "failure_reason": null,
      "contact_id": 8,
      "contact_name": "Customer"
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": true,
    "next_cursor": "eyJvcGFxdWVfc2lnbmVkX2N1cnNvciI6InJlZGFjdGVkIn0"
  }
}
statusstringrequired
enum ["success"]
callsarray<object>required

Call records are unique by call_id.

View nested fields

Array items

call_idstringrequired

IllyVoIP public call identifier. Raw switch and CDR identifiers are not public.

pattern "^CALL-[A-F0-9]{16}(?:[A-F0-9]{8})?$"
sip_user_idstringrequired
nullable truepattern "^(?:\\+?[0-9]{3,32}|anonymous)$"
fromstringrequired
nullable truepattern "^(?:\\+?[0-9]{3,32}|anonymous)$"
tostringrequired
nullable truepattern "^(?:\\+?[0-9]{3,32}|anonymous)$"
directionstringrequired
enum ["incoming", "outgoing", "unknown"]
statusstringrequired
enum ["completed", "failed"]
numberstringrequired

Deprecated v1 peer-number alias; use from and to.

nullable truepattern "^(?:\\+?[0-9]{3,32}|anonymous)$"
started_atstringrequired

ISO-8601 timestamp in UTC.

format "date-time"nullable truepattern "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
starttimestringrequired

Deprecated v1 naive UTC timestamp alias; use started_at.

nullable truepattern "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$"
duration_secondsintegerrequired
minimum 0
hangup_causestringrequired

Stable public outcome token. Use this token to understand the call outcome.

nullable truepattern "^(?:NORMAL_CLEARING|ANSWER|ANSWERED|BUSY|USER_BUSY|NO_ANSWER|CHANUNAVAIL|CONGESTION|CALL_REJECTED|CANCEL|FAILED|UNKNOWN|SIP_[1-6][0-9]{2}|Q850_(?:[1-9]|[1-9][0-9]|1[01][0-9]|12[0-7]))$"
failure_reason_codestringrequired

Stable public failure category; null for completed calls.

enum ["call_failed", "busy", "no_answer", "unavailable", "congestion", "call_rejected", "destination_not_callable", "fraud_control_blocked_country", "fraud_control_blocked_prefix", "fraud_control_max_rate", "insufficient_balance", "invalid_cli", "invalid_cli_selected", "callerid_invalid", "callerid_blocked", "unauthorized_cli", "callerid_policy", "policy_request_failed", "policy_prerequisite_failed", "policy_evaluation_failed", null]nullable true
failure_reasonstringrequired

IllyVoIP public label derived from failure_reason_code; raw backend text is never returned.

nullable truemaxLength 180
contact_idintegerrequired
nullable trueminimum 1
contact_namestringrequired
nullable truemaxLength 160

Additional properties: not allowed.

paginationobjectrequired
View nested fields
limitintegerrequired
minimum 1maximum 500
has_morebooleanrequired
next_cursorstringrequired

Opaque signed continuation token; null on the final page.

nullable trueminLength 1maxLength 4096pattern "^[A-Za-z0-9_-]+$"

Additional properties: not allowed.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "calls",
    "pagination"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "calls": {
      "type": "array",
      "description": "Call records are unique by call_id.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "call_id",
          "sip_user_id",
          "from",
          "to",
          "direction",
          "status",
          "number",
          "started_at",
          "starttime",
          "duration_seconds",
          "hangup_cause",
          "failure_reason_code",
          "failure_reason",
          "contact_id",
          "contact_name"
        ],
        "properties": {
          "call_id": {
            "type": "string",
            "pattern": "^CALL-[A-F0-9]{16}(?:[A-F0-9]{8})?$",
            "description": "IllyVoIP public call identifier. Raw switch and CDR identifiers are not public."
          },
          "sip_user_id": {
            "type": "string",
            "nullable": true,
            "pattern": "^(?:\\+?[0-9]{3,32}|anonymous)$"
          },
          "from": {
            "type": "string",
            "nullable": true,
            "pattern": "^(?:\\+?[0-9]{3,32}|anonymous)$"
          },
          "to": {
            "type": "string",
            "nullable": true,
            "pattern": "^(?:\\+?[0-9]{3,32}|anonymous)$"
          },
          "direction": {
            "type": "string",
            "enum": [
              "incoming",
              "outgoing",
              "unknown"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "failed"
            ]
          },
          "number": {
            "type": "string",
            "nullable": true,
            "pattern": "^(?:\\+?[0-9]{3,32}|anonymous)$",
            "deprecated": true,
            "description": "Deprecated v1 peer-number alias; use from and to."
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$",
            "description": "ISO-8601 timestamp in UTC."
          },
          "starttime": {
            "type": "string",
            "nullable": true,
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$",
            "deprecated": true,
            "description": "Deprecated v1 naive UTC timestamp alias; use started_at."
          },
          "duration_seconds": {
            "type": "integer",
            "minimum": 0
          },
          "hangup_cause": {
            "type": "string",
            "nullable": true,
            "pattern": "^(?:NORMAL_CLEARING|ANSWER|ANSWERED|BUSY|USER_BUSY|NO_ANSWER|CHANUNAVAIL|CONGESTION|CALL_REJECTED|CANCEL|FAILED|UNKNOWN|SIP_[1-6][0-9]{2}|Q850_(?:[1-9]|[1-9][0-9]|1[01][0-9]|12[0-7]))$",
            "description": "Stable public outcome token. Use this token to understand the call outcome."
          },
          "failure_reason_code": {
            "type": "string",
            "nullable": true,
            "enum": [
              "call_failed",
              "busy",
              "no_answer",
              "unavailable",
              "congestion",
              "call_rejected",
              "destination_not_callable",
              "fraud_control_blocked_country",
              "fraud_control_blocked_prefix",
              "fraud_control_max_rate",
              "insufficient_balance",
              "invalid_cli",
              "invalid_cli_selected",
              "callerid_invalid",
              "callerid_blocked",
              "unauthorized_cli",
              "callerid_policy",
              "policy_request_failed",
              "policy_prerequisite_failed",
              "policy_evaluation_failed",
              null
            ],
            "description": "Stable public failure category; null for completed calls."
          },
          "failure_reason": {
            "type": "string",
            "nullable": true,
            "maxLength": 180,
            "description": "IllyVoIP public label derived from failure_reason_code; raw backend text is never returned."
          },
          "contact_id": {
            "type": "integer",
            "nullable": true,
            "minimum": 1
          },
          "contact_name": {
            "type": "string",
            "nullable": true,
            "maxLength": 160
          }
        }
      }
    },
    "pagination": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "limit",
        "has_more",
        "next_cursor"
      ],
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 500
        },
        "has_more": {
          "type": "boolean"
        },
        "next_cursor": {
          "type": "string",
          "nullable": true,
          "minLength": 1,
          "maxLength": 4096,
          "pattern": "^[A-Za-z0-9_-]+$",
          "description": "Opaque signed continuation token; null on the final page."
        }
      }
    }
  }
}
400 The SIP identity selector is missing or is not available on this account.

application/json

Response example
{
  "status": "error",
  "message": "The requested SIP identity is not available on this account.",
  "error_code": "invalid_request"
}
Response example
{
  "status": "error",
  "message": "`days` must be an integer from 1 to 31.",
  "error_code": "invalid_request"
}
Response example
{
  "status": "error",
  "message": "`limit` must be an integer from 1 to 500.",
  "error_code": "invalid_request"
}
Response example
{
  "status": "error",
  "message": "`cursor` is invalid or has expired.",
  "error_code": "invalid_request"
}
statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key is missing or invalid.

application/json

Response example
{
  "status": "error",
  "message": "Missing API key.",
  "error_code": "authentication_required"
}
statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 The account or API policy does not allow this call-history request.

application/json

Response example
{
  "status": "error",
  "message": "Only account owners can access call logs via API.",
  "error_code": "access_denied"
}
statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The API request rate limit was exceeded.

application/json

Response example
{
  "status": "error",
  "message": "Too many API requests. Please retry in a minute.",
  "error_code": "rate_limited"
}
statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected backend error occurred and an incident code was returned.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 Call history or a required account authority is temporarily unavailable.

application/json

Response example
{
  "status": "error",
  "message": "Call history is unavailable right now.",
  "error_code": "service_unavailable"
}
statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable

Try this operation in Sandbox · Environment setup and limitations

Play or download recording

Search API operations, parameters, SDK and webhooks.