{ "openapi": "3.0.3", "info": { "title": "Get Started", "version": "1.0.0", "description": "### Overview\n\nWelcome to the didlogic public API documentation. Our API ecosystem is designed to give you programmatic control over global voice and messaging infrastructure. Whether you are automating SIP trunking, managing international DIDs, or pulling real-time CDRs, our API provides the tools to scale your communications.\n\n### API Versions\n\nWe currently maintain two API versions. These versions are **interoperable** and should be used together to access the full range of didlogic services.\n\n#### API v1: Core Infrastructure\n\nThe v1 API handles the foundational elements of your account and legacy connectivity services. Use this for:\n\n- **Billing & Finance:** Account balance, transaction history, and CSV exports.\n- **Voice Logs:** Call Detail Records (CDR) with advanced filtering.\n- **Messaging:** Standard SMS messaging services.\n- **Provisioning:** Basic SIP account management and ASR (Answer-Seizure Ratio) reporting.\n\n#### API v2: Enhanced DID Management\n\nThe v2 API provides a more modern, granular interface for managing your global number inventory. Use this for:\n\n- **Number Purchase:** Search, browse, and purchase numbers by country, region, or city.\n- **Inventory Control:** Browse your purchased numbers.\n- **Compliance:** Upload and manage regulatory documents required for specific jurisdictions.\n- **Number Reputation Control:** Request risk checks for specific numbers to see whether they have any spam/scam flags and access risk check reports.\n\n### Identifier interoperability (v1 ↔ v2)\n\nThe same DID is addressable two ways: by its **phone number** on the v1\nnumber-keyed endpoints, and by its numeric **inventory id** on v2 `GET /api/v2/numbers`.\nSo you don't get a 404 when you carry an id learned from v2 back to a v1 path,\nthe v1 number-keyed endpoints now **also accept the inventory id**:\n\n- `GET/POST /api/v1/purchases/{purchase_id}/destinations` and\n `PUT/DELETE /api/v1/purchases/{purchase_id}/destinations/{id}` — `purchase_id`\n accepts the DID phone number (e.g. `43800327987`) **or** the v2 inventory id\n (e.g. `21869`).\n- `GET/PUT/DELETE /api/v1/sipaccounts/{id}` and\n `GET/POST/DELETE /api/v1/sipaccounts/{sipaccount_id}/allowed_ips` — the identifier\n accepts the SIP account **name** (e.g. `97653`) **or** its numeric **id** (e.g. `73`).\n\nBoth forms resolve the same record; nothing about the existing name/number calls\nchanges. A value that matches neither returns the standard `404` error envelope\n(`{\"errors\":{\"base\":[\"data not found\"]}}`).\n\nRegulatory **documents** under v2 are the one exception — they stay split by\ndesign: the collection is addressed by the DID number\n(`GET /api/v2/numbers/documents?number=`) and a single document by its own id\n(`.../documents/{id}`). A number cannot pick one of many documents, and a document\nid cannot stand in for the collection, so dual-accept does not apply there.\n\n### Authentication\n\nTo ensure the security of your account, all requests to both v1 and v2 endpoints must be authenticated using **Bearer Token Authentication**.\nInclude your token in the `Authorization` header of every HTTP request.\n\n> **Header Format:** `Authorization: Bearer YOUR_TOKEN`\n\n| | |\n|---|---|\n| **Security Scheme Type** | HTTP |\n| **HTTP Authorization Scheme** | bearer |\n| **Transport** | HTTPS (Required) |\n\nPlease contact your account manager to access your API key.\n\n#### Example\n\n```bash\ncurl -X GET \"https://api.didlogic.com/v2/numbers\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\"\n```\n" }, "servers": [ { "url": "https://app.didlogic.com", "description": "Production" } ], "paths": { "/api/v1/balance": { "get": { "summary": "Get account balance", "description": "Retrieve the current account balance for the authenticated user.\n\n**Balance Representation:**\n- Returns balance in account currency (typically USD)\n- Value is rounded to 2 decimal places\n- Supports both JSON and plain text formats\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Account Balance" ], "responses": { "200": { "description": "Successfully returns account balance in JSON format with 2 decimal places", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "number", "format": "float", "example": 123.45, "description": "Current account balance rounded to 2 decimal places" } }, "required": [ "balance" ] }, "examples": { "successfully_returns_account_balance_as_plain_text_string": { "summary": "Successfully returns account balance as plain text string", "value": "123.45" }, "successfully_returns_account_balance_in_json_format_with_2_decimal_places": { "summary": "Successfully returns account balance in JSON format with 2 decimal places", "value": { "balance": 123.45 } } } }, "text/plain": { "schema": { "type": "string" }, "example": "123.45" } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/calls": { "get": { "summary": "Retrieve call detail records", "description": "Retrieve a list of call detail records (CDR) with filtering and pagination options.\n\n**Important notes:**\n- Results can be filtered by date range, call type, phone numbers, and SIP account\n- Supports both JSON and CSV export formats\n- Use pagination for large result sets\n- Statistics include total count, duration, and cost\n\n**When to use:**\n- Generating call history reports\n- Analyzing call patterns and costs\n- Exporting billing data\n- Monitoring SIP account usage\n", "tags": [ "Calls" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "description": "Filter by call type (sip = outbound SIP calls, web = outbound web calls, api = outbound API calls, incoming = received calls)", "required": false, "schema": { "type": "string", "enum": [ "sip", "web", "incoming", "api" ] }, "example": "sip" }, { "name": "missed", "in": "query", "description": "Include missed calls in results (0 = exclude, 1 = include)", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] }, "example": "1" }, { "name": "from_search", "in": "query", "description": "Filter by caller phone number (partial match supported)", "required": false, "schema": { "type": "string" }, "example": "1221" }, { "name": "to_search", "in": "query", "description": "Filter by destination phone number (partial match supported)", "required": false, "schema": { "type": "string" }, "example": "1800" }, { "name": "filter", "in": "query", "description": "Filter by phone number (alphanumeric, spaces, hyphens, underscores)", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9 \\-_]+$" }, "example": "+14155551234" }, { "name": "sip_account", "in": "query", "description": "Filter by SIP account/device identifier", "required": false, "schema": { "type": "string" }, "example": "36465" }, { "name": "from", "in": "query", "description": "Start date for filtering (inclusive). Format YYYY-MM-DD", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2025-01-01" }, { "name": "to", "in": "query", "description": "End date for filtering (inclusive). Format YYYY-MM-DD", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2025-01-31" }, { "name": "all", "in": "query", "description": "Return all records (ignores pagination). Use with caution for large datasets.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "page", "in": "query", "description": "Page number to retrieve (1-based)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Number of records per page (max 1000)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "example": 100 } ], "responses": { "200": { "description": "Successfully retrieved CDR records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdrListResponse" }, "example": { "calls": [ { "timestamp": "2024-01-15T10:30:00Z", "type": "sip", "amount": 0.05, "duration": 120, "from": "100", "to": "+14155551234", "destination_name": "United States", "sip_account": "john@sip.provider.com", "per_minute": 0.025 }, { "timestamp": "2024-01-15T10:30:00Z", "type": "incoming", "amount": 0.02, "duration": 90, "from": "+14155551234", "to": "100", "did_number": "+18005551234" }, { "timestamp": "2024-01-15T10:35:00Z", "type": "incoming", "amount": 0, "duration": 0, "from": "+14155559999", "to": "100", "did_number": "+18005551234" }, { "timestamp": "2024-01-15T10:30:00Z", "type": "web", "amount": 0.03, "duration": 60, "from": "web_user_123", "to": "+14155551234" } ], "pagination": { "page": 1, "per_page": 10, "total_pages": 325, "total_records": 3248 } } }, "text/csv": { "schema": { "type": "string", "description": "CSV formatted call detail records.\n\nColumns: Date, Time, SIP ID, Type, From, To, Destination name, Duration, DID inc. fee, Termination, Charge, Balance\n" }, "example": "Date,Time,SIP ID,Type,From,To,Destination name,Duration,DID inc. fee,Termination,Charge,Balance\n01/15/24,10:30:00 am,john@sip.com,SIP TERM,100,+14155551234,United States,120,0.00000,0.02500,0.05000,99.95000\n" } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "Forbidden - Valid token but user is blocked or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } } } } }, "/api/v1/calls/statistics": { "get": { "summary": "Get call statistics", "description": "Retrieve aggregated call statistics including totals and counts.\n\n**Response includes:**\n- Placed calls: total cost and count\n- Received calls: total cost and count\n- Missed calls: count only\n- All calls: combined total cost and count\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Calls" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2024-01-01", "description": "Start date for filtering (YYYY-MM-DD)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2024-12-31", "description": "End date for filtering (YYYY-MM-DD)" }, { "name": "sipfriend", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 458, "description": "Filter by SIP friend ID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1234567890, "description": "Search term for filtering calls" } ], "responses": { "200": { "description": "returns call statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "placed": { "type": "object", "properties": { "total": { "type": "string", "example": "$15.0000", "description": "Total cost of placed calls" }, "count": { "type": "integer", "example": 0, "description": "Number of placed calls" } }, "required": [ "total", "count" ], "description": "Statistics for placed (outgoing) calls" }, "received": { "type": "object", "properties": { "total": { "type": "string", "example": "$20.0000", "description": "Total cost of received calls" }, "count": { "type": "integer", "example": 0, "description": "Number of received calls" } }, "required": [ "total", "count" ], "description": "Statistics for received (incoming) calls" }, "missed": { "type": "object", "properties": { "count": { "type": "integer", "example": 0, "description": "Number of missed calls" } }, "required": [ "count" ], "description": "Statistics for missed calls" }, "all": { "type": "object", "properties": { "total": { "type": "string", "example": "$35.0000", "description": "Total cost of all calls" }, "count": { "type": "integer", "example": 0, "description": "Total number of all calls" } }, "required": [ "total", "count" ], "description": "Combined statistics for all calls" } }, "required": [ "placed", "received", "missed", "all" ] }, "example": { "placed": { "total": "$15.0000", "count": 0 }, "received": { "total": "$20.0000", "count": 0 }, "missed": { "count": 0 }, "all": { "total": "$35.0000", "count": 0 } } } } }, "403": { "description": "returns forbidden error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } } } }, "/api/v1/calls/recording/{callid}": { "get": { "summary": "Download call recordings", "description": "Retrieves a single call recording file by its Call ID.\n\n> ⚠️ **Important:** this endpoint is a fallback mechanism designed for\n> recovering missing recordings when a delivery webhook failed or its\n> short-lived URL expired. For production workflows, always use\n> [Call Recording Webhooks](https://docs.didlogic.com/docs/guides/apps-developer-tools/webhooks)\n> instead of polling this API.\n\nThe Call ID is all you need — the recording is searched for across the\nwhole period your account retains recordings, so a client that stored only\nthe Call ID can download the file.\n\n### Rate limits & quotas\n\nTo prevent system overload, strict limits are enforced per user:\n\n- **Request frequency:** max 1 request per second.\n- **Recording lookups:** max 1 lookup per minute.\n\nThe per-minute quota is consumed by every search query, regardless of\nwhether a recording is found or the request returns `404 Not Found` —\nsearching for the file is the operation that costs resources.\n\n### Authentication\n\nRequires a Bearer token in the Authorization header:\n`Authorization: Bearer `\n", "tags": [ "Calls" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "callid", "in": "path", "required": true, "schema": { "type": "string" }, "example": "raw.call-id-1@example.com", "description": "Call ID of the recording (required). Inbound callids are the encrypted webhook value." } ], "responses": { "302": { "description": "Redirects to a short-lived AWS S3 pre-signed URL for the recording (`.mp3`). Follow the redirect — for example with `curl -L` — to download the file.", "content": { "text/html": { "schema": { "type": "string" }, "example": "" } } }, "403": { "description": "The API token is missing or invalid, or call recording is not enabled for this account.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] }, "examples": { "Unauthorized": { "value": { "error": "Unauthorized" } }, "Recording disabled": { "value": { "errors": { "base": [ "call recording is not enabled for your account" ] } } } } } } }, "404": { "description": "No recording matches this Call ID. The call does not exist, belongs to another account, or is older than the account's recording retention period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } }, "429": { "description": "A rate limit was exceeded — either the one-request-per-second frequency limit or the one-lookup-per-minute quota. Carries `Retry-After` with the seconds to wait, alongside `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Lookup quota exceeded": { "value": { "errors": { "base": [ "Recording lookup limit reached. Maximum 1 lookup per minute is allowed. Please use a webhook for production workflows." ] } } }, "Too many requests": { "value": { "errors": { "base": [ "Recording lookup limit reached. Maximum 1 request per second is allowed." ] } } } } } } } } } }, "/api/v1/asr_report": { "get": { "summary": "Get ASR (Answer-Seizure Ratio) report", "description": "Retrieve the Answer-Seizure Ratio (ASR) report in CSV format for specified date range.\n\n**ASR Metrics:**\n- Number of calls\n- Talk time in minutes\n- ASR: Percentage of calls successfully connected\n- Average call duration (ACD)\n\n**Requirements:**\n- Date range is required (start_date and end_date)\n- Dates must be in YYYY-MM-DD format\n- On success returns CSV; 400 and 403 errors return JSON\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Reports" ], "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string" }, "example": "2024-01-01", "description": "Report start date (YYYY-MM-DD format)" }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string" }, "example": "2024-12-31", "description": "Report end date (YYYY-MM-DD format)" } ], "responses": { "200": { "description": "Successfully returns ASR metrics report in CSV format", "content": { "text/csv": { "schema": { "type": "string" }, "example": "Country,Minutes,Calls,ASR,ACD\n" } } }, "400": { "description": "Returns 400 error when end_date or start_date parameter is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "start_date and end_date are required" ] } } } } }, "403": { "description": "Returns 403 error when the API token is incorrect or the account is not permitted to export the ASR report", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] }, "examples": { "returns_403_error_when_the_api_token_is_incorrect": { "summary": "Returns 403 error when the API token is incorrect", "value": { "error": "Unauthorized" } }, "returns_403_error_when_the_api_token_is_incorrect_or_the_account_is_not_permitted_to_export_the_asr_report": { "summary": "Returns 403 error when the API token is incorrect or the account is not permitted to export the ASR report", "value": { "errors": { "base": [ "ASR report export is not permitted for this account" ] } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/transactions": { "get": { "summary": "Export transaction history", "description": "Export account transaction history as a CSV file for a date range and\ntransaction type(s).\n\n**Requirements:**\n- start_date, end_date and type are all required\n- Dates must be in YYYY-MM-DD format\n- `type` accepts one or more comma-separated values from the list below\n\n**Transaction types:** adjustments, paypal_in, paypal_out, cc_in, stripe_in,\ngoogle_pay_in, apple_pay_in, wire_transfer, call, call_fix_fee, connection,\nsip, webcall, sms, inbound_sms, activation, month, subscription, porting,\nsurcharge, risk_check, call_recording, hlr_lookup, amd, channel\n\n**Response:** The caller receives the generated CSV payload. The internal\nredirect used to fetch that file is an implementation detail and is not\npart of the public contract.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Reports" ], "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-01-01" }, "example": "2024-01-01", "description": "Start of the reporting period (YYYY-MM-DD)" }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-01-31" }, "example": "2024-01-31", "description": "End of the reporting period (YYYY-MM-DD)" }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "example": "call" }, "example": "call", "description": "Comma-separated transaction type(s); see the operation description for the full list of accepted values." } ], "responses": { "200": { "description": "Returns the generated transactions CSV file", "content": { "text/csv": { "schema": { "type": "string" }, "example": "Date,Time,Transaction type,Comment,Amount,Balance,Status\n2024-01-15,10:30,call,Sample call charge,-1.23,98.77,completed\n" } } }, "400": { "description": "Returns 400 with the JSON error envelope when required params are missing or malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "start_date, end_date and type are required" ] } } } } }, "403": { "description": "Returns 403 error when the API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/purchases": { "get": { "summary": "List purchased DID numbers", "description": "Retrieve a paginated list of DID numbers purchased by the authenticated user.\n\n**Features:**\n- Ordered by most recent first\n- Pagination: 100 DIDs per page (max 1000)\n- Available in JSON and CSV formats\n\n**Returned Information:**\n- DID number and status\n- Purchase and expiration dates\n- Monthly cost and features\n- SMS/voice capabilities\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Purchases" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1, "description": "Page number for pagination (starts from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 10, "description": "Number of items per page" } ], "responses": { "200": { "description": "Successfully returns paginated list of purchased DID numbers in JSON format", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "example": "1234567890", "description": "DID phone number" }, "channels": { "type": "integer", "example": 1, "description": "Number of channels" }, "country": { "type": "string", "example": "Fake country for 1234567890", "description": "DID country" }, "area": { "type": "string", "example": "Fake city for 1234567890", "description": "DID area" }, "codec": { "nullable": true, "description": "Audio codec" }, "activation": { "type": "number", "format": "float", "example": 1.17, "description": "Activation fee" }, "monthly_fee": { "type": "number", "format": "float", "example": 1.17, "description": "Monthly cost for the DID" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per minute rate" }, "check_state": { "type": "string", "example": "active", "description": "DID status" }, "free_minutes": { "type": "integer", "example": 0, "description": "Free minutes included" } }, "required": [ "number", "channels", "country", "area", "codec", "activation", "monthly_fee", "per_minute", "check_state", "free_minutes" ] }, "description": "List of purchased DID numbers" }, "pagination": { "type": "object", "properties": { "pages": { "type": "integer" }, "page": { "type": "integer" }, "total_records": { "type": "integer" }, "per_page": { "type": "integer" } }, "required": [ "pages", "page", "total_records", "per_page" ] } }, "required": [ "purchases", "pagination" ] }, "examples": { "returns_list_of_purchased_dids_in_csv_format_for_spreadsheet_import": { "summary": "Returns list of purchased DIDs in CSV format for spreadsheet import", "value": "Number,Channels,Country,Area,Check state,Codec,Free minutes,Activation,Monthly fee,Per minute,Paid until,Minutes,Destination\n1234567890,1,Fake country for 1234567890,Fake city for 1234567890,active,,0,1.1700,1.1700,0.1170,,00:00,\"\"\n" }, "successfully_returns_paginated_list_of_purchased_did_numbers_in_json_format": { "summary": "Successfully returns paginated list of purchased DID numbers in JSON format", "value": { "purchases": [ { "number": "1234567890", "channels": 1, "country": "Fake country for 1234567890", "area": "Fake city for 1234567890", "codec": null, "check_state": "active", "free_minutes": 0, "activation": 1.17, "monthly_fee": 1.17, "per_minute": 0.117 } ], "pagination": { "pages": 1, "page": 1, "total_records": 1, "per_page": 10 } } } } }, "text/csv": { "schema": { "type": "string" }, "example": "Number,Channels,Country,Area,Check state,Codec,Free minutes,Activation,Monthly fee,Per minute,Paid until,Minutes,Destination\n1234567890,1,Fake country for 1234567890,Fake city for 1234567890,active,,0,1.1700,1.1700,0.1170,,00:00,\"\"\n" } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/purchases/{purchase_id}/destinations": { "get": { "summary": "List destinations", "description": "Retrieve the list of inbound destinations configured for a specific DID number.\n\n**Destinations** define where incoming calls to a DID should be routed (SIP addresses, phone numbers, etc.).\n\n**Features:**\n- Returns only current (non-deleted) destinations\n- Each destination includes active status and its dialing mode (`dialing_type`, with the legacy `callhunt` mirror)\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Inbound Destinations" ], "parameters": [ { "name": "purchase_id", "in": "path", "required": true, "schema": { "type": "string", "example": "43800327987" }, "example": "43800327987", "description": "DID identifier — the phone **number** (e.g. `43800327987`) or the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g. `21869`). Both resolve the same DID." } ], "responses": { "200": { "description": "Successfully returns all current destinations for the specified DID", "content": { "application/json": { "schema": { "type": "object", "properties": { "destination": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 287, "description": "Destination ID" }, "destination": { "type": "string", "example": "sip:test@example.com", "description": "Forwarding target" }, "priority": { "type": "integer", "example": 1, "description": "Destination priority" }, "callhunt": { "type": "boolean", "description": "Whether callhunt is enabled" }, "active": { "type": "boolean", "example": true, "description": "Whether destination is active" }, "transport": { "type": "integer", "enum": [ 1, 4, 5, 10 ], "example": 1, "description": "Transport type" }, "ai_agent_id": { "nullable": true, "type": "integer", "description": "Linked AI agent ID (null when the destination is not an AI agent)" }, "ai_agent_name": { "nullable": true, "type": "string", "description": "Linked AI agent name (null when the destination is not an AI agent)" }, "dialing_type": { "type": "string", "enum": [ "sequence", "ring_all", "random" ], "example": "sequence", "description": "Dialing mode of the group this destination belongs to: `sequence` tries it alone, `ring_all` dials the whole group at once, `random` picks group members in a random order. Mirrors `callhunt` (`ring_all` maps to true)." } }, "required": [ "id", "destination", "priority", "callhunt", "active", "transport", "ai_agent_id", "ai_agent_name" ] }, "description": "List of destinations" } }, "required": [ "destination" ] }, "example": { "destination": [ { "id": 287, "transport": 1, "destination": "sip:test@example.com", "priority": 1, "callhunt": false, "dialing_type": "sequence", "active": true, "ai_agent_id": null, "ai_agent_name": null } ] } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the DID phone number nor its inventory id matches a DID you own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "summary": "Create destination", "description": "Add a new inbound destination for a DID number.\n\n**Destination Types:**\n- SIP addresses (e.g., `sip:user@domain.com`)\n- Phone numbers (e.g., `18005551234`)\n- Extensions (SIP accounts created within didlogic)\n\n**Parameters:**\n- `destination` - The forwarding target (SIP URI or phone number)\n- `dialing_type` - Dialing mode: `sequence`, `ring_all` or `random`\n- `callhunt` - Legacy two-state mirror of `dialing_type` (boolean); ignored when `dialing_type` is sent\n- `active` - Enable/disable this destination (boolean)\n- `transport` - Transport type code (1 = SIP URI, 4 = Phone number, 5 = SIP device, 10 = Webphone)\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Inbound Destinations" ], "parameters": [ { "name": "purchase_id", "in": "path", "required": true, "schema": { "type": "string", "example": "43800327987" }, "example": "43800327987", "description": "DID identifier — the phone **number** (e.g. `43800327987`) or the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g. `21869`). Both resolve the same DID." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "destination[destination]": { "type": "string", "description": "Forwarding target (SIP URI or phone number)", "example": "sip:test@example.com" }, "destination[callhunt]": { "type": "string", "description": "Enable callhunt (ring all). Ignored when `destination[dialing_type]` is sent.", "example": "false" }, "destination[active]": { "type": "string", "description": "Activate this destination", "example": "true" }, "destination[transport]": { "type": "string", "description": "Transport type (1=SIP URI, 4=Phone number, 5=SIP device, 10=Webphone)", "enum": [ "1", "4", "5", "10" ], "example": "1" }, "destination[dialing_type]": { "type": "string", "description": "Dialing mode of the group this destination belongs to: `sequence` tries it alone, `ring_all` dials the whole group at once, `random` picks group members in a random order. Mirrors `callhunt` (`ring_all` maps to true). Takes precedence over `callhunt`.", "enum": [ "sequence", "ring_all", "random" ] } }, "required": [ "destination[destination]" ] } } } }, "responses": { "200": { "description": "Successfully creates destination and returns destination details", "content": { "application/json": { "schema": { "type": "object", "properties": { "did_destination": { "type": "object", "properties": { "id": { "type": "integer", "example": 290, "description": "Destination ID" }, "destination": { "type": "string", "example": "sip:test@example.com", "description": "Forwarding target" }, "priority": { "type": "integer", "example": 1, "description": "Destination priority" }, "callhunt": { "type": "boolean", "description": "Whether callhunt is enabled" }, "active": { "type": "boolean", "example": true, "description": "Whether destination is active" }, "transport": { "type": "integer", "enum": [ 1, 4, 5, 10 ], "example": 1, "description": "Transport type" }, "ai_agent_id": { "nullable": true, "type": "integer", "description": "Linked AI agent ID (null when the destination is not an AI agent)" }, "ai_agent_name": { "nullable": true, "type": "string", "description": "Linked AI agent name (null when the destination is not an AI agent)" }, "dialing_type": { "type": "string", "enum": [ "sequence", "ring_all", "random" ], "example": "sequence", "description": "Dialing mode of the group this destination belongs to: `sequence` tries it alone, `ring_all` dials the whole group at once, `random` picks group members in a random order. Mirrors `callhunt` (`ring_all` maps to true)." } }, "required": [ "id", "destination", "priority", "callhunt", "active", "transport", "ai_agent_id", "ai_agent_name" ], "description": "Created destination details" } }, "required": [ "did_destination" ] }, "example": { "did_destination": { "id": 290, "destination": "sip:test@example.com", "priority": 1, "callhunt": false, "active": true, "transport": 1, "dialing_type": "sequence", "ai_agent_id": null, "ai_agent_name": null } } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the DID phone number nor its inventory id matches a DID you own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } }, "422": { "description": "Returns 422 error with validation messages when destination is incorrect", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "destination": [ "can't be blank" ] } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/purchases/{purchase_id}/destinations/{id}": { "patch": { "summary": "Update destination", "description": "Update an existing inbound destination for a DID number.\n\n**Updatable Fields:**\n- `dialing_type` - Dialing mode: `sequence`, `ring_all` or `random`\n- `callhunt` - Legacy two-state mirror of `dialing_type`; ignored when `dialing_type` is sent\n- `active` - Enable/disable this destination\n\n**Note:** The destination address and transport protocol cannot be changed. To change these, delete and create a new destination.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Inbound Destinations" ], "parameters": [ { "name": "purchase_id", "in": "path", "required": true, "schema": { "type": "string", "example": "43800327987" }, "example": "43800327987", "description": "DID identifier — the phone **number** (e.g. `43800327987`) or the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g. `21869`). Both resolve the same DID." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 296, "description": "Destination ID to update" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "destination[callhunt]": { "type": "string", "description": "Enable callhunt (ring all). Ignored when `destination[dialing_type]` is sent.", "example": "true" }, "destination[active]": { "type": "string", "description": "Activate/deactivate this destination", "example": "false" }, "destination[dialing_type]": { "type": "string", "description": "Dialing mode of the group this destination belongs to: `sequence` tries it alone, `ring_all` dials the whole group at once, `random` picks group members in a random order. Mirrors `callhunt` (`ring_all` maps to true). Takes precedence over `callhunt`.", "enum": [ "sequence", "ring_all", "random" ] } } } } } }, "responses": { "200": { "description": "Successfully updates destination settings and returns updated destination", "content": { "application/json": { "schema": { "type": "object", "properties": { "did_destination": { "type": "object", "properties": { "id": { "type": "integer", "example": 294, "description": "Destination ID" }, "destination": { "type": "string", "example": "sip:test@example.com", "description": "Forwarding target" }, "priority": { "type": "integer", "example": 1, "description": "Destination priority" }, "callhunt": { "type": "boolean", "example": true, "description": "Whether callhunt is enabled" }, "active": { "type": "boolean", "description": "Whether destination is active" }, "transport": { "type": "integer", "enum": [ 1, 4, 5, 10 ], "example": 1, "description": "Transport type" }, "ai_agent_id": { "nullable": true, "type": "integer", "description": "Linked AI agent ID (null when the destination is not an AI agent)" }, "ai_agent_name": { "nullable": true, "type": "string", "description": "Linked AI agent name (null when the destination is not an AI agent)" }, "dialing_type": { "type": "string", "enum": [ "sequence", "ring_all", "random" ], "example": "ring_all", "description": "Dialing mode of the group this destination belongs to: `sequence` tries it alone, `ring_all` dials the whole group at once, `random` picks group members in a random order. Mirrors `callhunt` (`ring_all` maps to true)." } }, "required": [ "id", "destination", "priority", "callhunt", "active", "transport", "ai_agent_id", "ai_agent_name" ], "description": "Updated destination details" } }, "required": [ "did_destination" ] }, "example": { "did_destination": { "id": 294, "destination": "sip:test@example.com", "priority": 1, "callhunt": true, "active": false, "transport": 1, "dialing_type": "ring_all", "ai_agent_id": null, "ai_agent_name": null } } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the DID phone number nor its inventory id matches a DID you own.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] }, "examples": { "returns_404_error_when_destination_does_not_exist_or_belongs_to_another_user": { "summary": "Returns 404 error when destination does not exist or belongs to another user", "value": { "error": "destination not found" } }, "returns_the_404_error_envelope_errors_base_data_not_found_when_neither_the_did_phone_number_nor_its_inventory_id_matches_a_did_you_own": { "summary": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the DID phone number nor its inventory id matches a DID you own.", "value": { "errors": { "base": [ "data not found" ] } } } } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "summary": "Delete destination", "description": "Delete an existing inbound destination from a DID number.\n\n**Important:**\n- Destination is permanently removed from the DID configuration\n- Deletion is logged for audit purposes\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Inbound Destinations" ], "parameters": [ { "name": "purchase_id", "in": "path", "required": true, "schema": { "type": "string", "example": "43800327987" }, "example": "43800327987", "description": "DID identifier — the phone **number** (e.g. `43800327987`) or the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g. `21869`). Both resolve the same DID." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 293, "description": "Destination ID to delete" } ], "responses": { "204": { "description": "Successfully deletes destination and returns 204 No Content" }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the DID phone number nor its inventory id matches a DID you own.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] }, "examples": { "returns_404_error_when_destination_does_not_exist_or_belongs_to_another_user": { "summary": "Returns 404 error when destination does not exist or belongs to another user", "value": { "error": "destination not found" } }, "returns_the_404_error_envelope_errors_base_data_not_found_when_neither_the_did_phone_number_nor_its_inventory_id_matches_a_did_you_own": { "summary": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the DID phone number nor its inventory id matches a DID you own.", "value": { "errors": { "base": [ "data not found" ] } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/sipaccounts": { "get": { "summary": "List SIP accounts", "description": "Retrieve list of SIP accounts (trunks) configured for the authenticated user.\n\n**SIP Accounts** allow making/receiving calls through the platform using SIP protocol.\n\n**Returned Information:**\n- Account credentials and settings\n- Call routing configuration\n- Usage limits and restrictions\n- Allowed IP addresses (if configured)\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "responses": { "200": { "description": "Successfully returns list of SIP accounts with configuration details", "content": { "application/json": { "schema": { "type": "object", "properties": { "sipaccounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 459, "description": "Unique SIP account identifier" }, "name": { "type": "string", "example": "21491", "description": "SIP account username" }, "callerid": { "type": "string", "example": "", "description": "Caller ID" }, "label": { "type": "string", "example": "some-label-351", "description": "Account label" }, "host": { "type": "string", "example": "dynamic", "description": "SIP server host" }, "rewrite_enabled": { "type": "boolean", "description": "Whether number rewriting is enabled" }, "rewrite_cond": { "type": "string", "example": "", "description": "Rewrite condition pattern (regular expression)" }, "rewrite_prefix": { "type": "string", "example": "", "description": "Prefix to add when rewriting numbers" }, "didinfo_enabled": { "type": "boolean", "example": true, "description": "Whether DID info is included in SIP headers" }, "ip_restrict": { "type": "boolean", "description": "Whether access is restricted by IP address" }, "call_restrict": { "type": "boolean", "description": "Whether per-call cost limits are enabled" }, "call_limit": { "type": "integer", "example": 60, "description": "Maximum cost per call in cents" }, "channels_restrict": { "type": "boolean", "description": "Whether concurrent channel limits are enabled" }, "max_channels": { "type": "integer", "example": 1, "description": "Maximum number of concurrent channels allowed" }, "cost_limit": { "type": "boolean", "description": "Whether maximum call cost limit is enabled" }, "max_call_cost": { "type": "string", "example": "0.0", "description": "Maximum allowed cost per call" }, "created_at": { "type": "string", "example": "2026-04-10 11:11:10 UTC", "description": "Account creation timestamp" }, "low_balance": { "type": "boolean", "description": "Whether account has low balance" }, "allowed_ips": { "type": "array", "items": {}, "description": "List of IP addresses allowed to authenticate" }, "charge": { "type": "string", "example": "0.0", "description": "Total charges accumulated on this account" }, "talk_time": { "type": "integer", "example": 0, "description": "Total talk time in seconds" }, "spend_limit": { "type": "string", "example": "0.0", "description": "Maximum total spend amount" }, "spend_limit_enabled": { "type": "boolean", "description": "Whether spending limit is enabled" }, "available_amount": { "type": "string", "example": "0.0", "description": "Amount available for spending" }, "call_recording_enabled": { "type": "boolean" } }, "required": [ "id", "name", "callerid", "label", "host", "rewrite_enabled", "rewrite_cond", "rewrite_prefix", "didinfo_enabled", "ip_restrict", "call_restrict", "call_limit", "channels_restrict", "max_channels", "cost_limit", "max_call_cost", "created_at", "low_balance", "allowed_ips", "charge", "talk_time", "spend_limit", "spend_limit_enabled", "available_amount" ] }, "description": "List of SIP accounts" } }, "required": [ "sipaccounts" ] }, "example": { "sipaccounts": [ { "id": 11, "name": "01121", "callerid": "", "label": "some-label-211", "host": "dynamic", "rewrite_enabled": false, "rewrite_cond": "", "rewrite_prefix": "", "didinfo_enabled": true, "ip_restrict": false, "call_restrict": false, "call_limit": 60, "channels_restrict": false, "max_channels": 1, "cost_limit": false, "max_call_cost": "0.0", "created_at": "2026-08-12 11:39:35 UTC", "charge": "0.0", "talk_time": 0, "low_balance": false, "spend_limit": "0.0", "spend_limit_enabled": false, "available_amount": "0.0", "call_recording_enabled": false, "allowed_ips": [] } ] } } } }, "403": { "description": "Returns 403 error when SIP accounts are disabled for this user", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] }, "examples": { "returns_403_error_when_api_token_is_incorrect": { "summary": "Returns 403 error when API token is incorrect", "value": { "error": "Unauthorized" } }, "returns_403_error_when_sip_accounts_are_disabled_for_this_user": { "summary": "Returns 403 error when SIP accounts are disabled for this user", "value": { "errors": { "base": [ "Access denied" ] } } } } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "summary": "Create SIP account", "description": "Create a new SIP account (trunk) for making/receiving calls.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "sipaccount[label]": { "type": "string", "description": "Account label/name", "example": "Test SIP Account" }, "sipaccount[password]": { "type": "string", "description": "SIP password", "example": "SecurePass123" }, "sipaccount[callerid]": { "type": "string", "description": "Caller ID to display on outbound calls", "example": "1234567890" }, "sipaccount[rewrite_enabled]": { "type": "string", "description": "Enable number rewriting", "example": "false" }, "sipaccount[rewrite_cond]": { "type": "string", "description": "Rewrite condition pattern (regular expression)" }, "sipaccount[rewrite_prefix]": { "type": "string", "description": "Prefix to add when rewriting numbers" }, "sipaccount[didinfo_enabled]": { "type": "string", "description": "Enable DID info in SIP headers", "example": "true" }, "sipaccount[ip_restrict]": { "type": "string", "description": "Restrict access by IP address (requires allowed IPs)", "example": "false" }, "sipaccount[call_restrict]": { "type": "string", "description": "Enable per-call cost limits", "example": "true" }, "sipaccount[call_limit]": { "type": "string", "description": "Maximum cost per call in cents", "example": "1000" }, "sipaccount[channels_restrict]": { "type": "string", "description": "Enable concurrent channel limits", "example": "true" }, "sipaccount[max_channels]": { "type": "string", "description": "Maximum concurrent channels allowed", "example": "5" }, "sipaccount[cost_limit]": { "type": "string", "description": "Enable maximum call cost limit", "example": "false" }, "sipaccount[max_call_cost]": { "type": "string", "description": "Maximum allowed cost per call in cents" }, "sipaccount[spend_limit_enabled]": { "type": "string", "description": "Enable total spending limit", "example": "false" }, "sipaccount[spend_limit]": { "type": "string", "description": "Maximum total spend amount in cents" }, "sipaccount[reset_available_amount]": { "type": "string", "description": "Amount available for spend limit reset in cents" }, "sipaccount[call_recording_enabled]": { "type": "string", "description": "Enable or disable recording of outbound calls made via a selected SIP account" } }, "required": [ "sipaccount[label]", "sipaccount[password]" ] } } } }, "responses": { "200": { "description": "Successfully creates SIP account and returns credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "sipaccount": { "type": "object", "properties": { "id": { "type": "integer", "example": 466, "description": "SIP account ID" }, "name": { "type": "string", "example": "61737", "description": "SIP account username" }, "callerid": { "type": "string", "example": "", "description": "Caller ID" }, "label": { "type": "string", "example": "Test SIP Account", "description": "Account label" }, "host": { "type": "string", "example": "dynamic", "description": "SIP server host" }, "rewrite_enabled": { "type": "boolean", "description": "Whether number rewriting is enabled" }, "rewrite_cond": { "type": "string", "example": "", "description": "Rewrite condition pattern (regular expression)" }, "rewrite_prefix": { "type": "string", "example": "", "description": "Prefix to add when rewriting numbers" }, "didinfo_enabled": { "type": "boolean", "example": true, "description": "Whether DID info is included in SIP headers" }, "ip_restrict": { "type": "boolean", "description": "Whether access is restricted by IP address" }, "call_restrict": { "type": "boolean", "example": true, "description": "Whether per-call cost limits are enabled" }, "call_limit": { "type": "integer", "example": 1000, "description": "Maximum cost per call in cents" }, "channels_restrict": { "type": "boolean", "example": true, "description": "Whether concurrent channel limits are enabled" }, "max_channels": { "type": "integer", "example": 5, "description": "Maximum number of concurrent channels allowed" }, "cost_limit": { "type": "boolean", "description": "Whether maximum call cost limit is enabled" }, "max_call_cost": { "type": "string", "example": "0.0", "description": "Maximum allowed cost per call" }, "created_at": { "type": "string", "example": "2026-04-10 11:11:15 UTC", "description": "Creation timestamp" }, "low_balance": { "type": "boolean", "description": "Whether account has low balance" }, "allowed_ips": { "type": "array", "items": {}, "description": "List of IP addresses allowed to authenticate" }, "charge": { "type": "string", "example": "0.0", "description": "Total charges accumulated on this account" }, "talk_time": { "type": "integer", "example": 0, "description": "Total talk time in seconds" }, "spend_limit": { "type": "string", "example": "0.0", "description": "Maximum total spend amount" }, "spend_limit_enabled": { "type": "boolean", "description": "Whether spending limit is enabled" }, "available_amount": { "type": "string", "example": "0.0", "description": "Amount available for spending" }, "call_recording_enabled": { "type": "boolean" } }, "required": [ "id", "name", "callerid", "label", "host", "rewrite_enabled", "rewrite_cond", "rewrite_prefix", "didinfo_enabled", "ip_restrict", "call_restrict", "call_limit", "channels_restrict", "max_channels", "cost_limit", "max_call_cost", "created_at", "low_balance", "allowed_ips", "charge", "talk_time", "spend_limit", "spend_limit_enabled", "available_amount" ], "description": "Created SIP account details" }, "warnings": { "type": "array", "description": "Non-fatal notices for parts of the request that were accepted but silently skipped (e.g. an unverified caller ID). Present only when non-empty.", "items": { "$ref": "#/components/schemas/Warning" } } }, "required": [ "sipaccount" ] }, "example": { "sipaccount": { "id": 466, "name": "61737", "callerid": "", "label": "Test SIP Account", "host": "dynamic", "rewrite_enabled": false, "rewrite_cond": "", "rewrite_prefix": "", "didinfo_enabled": true, "ip_restrict": false, "call_restrict": true, "call_limit": 1000, "channels_restrict": true, "max_channels": 5, "cost_limit": false, "max_call_cost": "0.0", "created_at": "2026-04-10 11:11:15 UTC", "low_balance": false, "allowed_ips": [], "charge": "0.0", "talk_time": 0, "spend_limit": "0.0", "spend_limit_enabled": false, "available_amount": "0.0", "call_recording_enabled": false }, "warnings": [ { "resource": "caller_id", "identifier": "1234567890", "code": "not_an_owned_or_verified_caller_id", "message": "is not an owned or verified caller ID and was ignored" } ] } } } }, "403": { "description": "Returns 403 error when SIP account creation is disabled", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] }, "examples": { "returns_403_error_when_api_token_is_incorrect": { "summary": "Returns 403 error when API token is incorrect", "value": { "error": "Unauthorized" } }, "returns_403_error_when_sip_account_creation_is_disabled": { "summary": "Returns 403 error when SIP account creation is disabled", "value": { "errors": { "base": [ "Access denied" ] } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/sipaccounts/{id}": { "get": { "summary": "Get SIP account details", "description": "Retrieve details of a specific SIP account.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "01234" }, "example": "01234", "description": "SIP account identifier — the account **name** (e.g. `01234`, which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve the same account." } ], "responses": { "200": { "description": "Successfully returns SIP account configuration and settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "sipaccount": { "type": "object", "properties": { "id": { "type": "integer", "example": 464, "description": "Unique SIP account identifier" }, "name": { "type": "string", "example": "75303", "description": "SIP account username" }, "callerid": { "type": "string", "example": "", "description": "Caller ID" }, "label": { "type": "string", "example": "some-label-456", "description": "Account label" }, "host": { "type": "string", "example": "dynamic", "description": "SIP server host" }, "rewrite_enabled": { "type": "boolean", "description": "Whether number rewriting is enabled" }, "rewrite_cond": { "type": "string", "example": "", "description": "Rewrite condition pattern (regular expression)" }, "rewrite_prefix": { "type": "string", "example": "", "description": "Prefix to add when rewriting numbers" }, "didinfo_enabled": { "type": "boolean", "example": true, "description": "Whether DID info is included in SIP headers" }, "ip_restrict": { "type": "boolean", "description": "Whether access is restricted by IP address" }, "call_restrict": { "type": "boolean", "description": "Whether per-call cost limits are enabled" }, "call_limit": { "type": "integer", "example": 60, "description": "Maximum cost per call in cents" }, "channels_restrict": { "type": "boolean", "description": "Whether concurrent channel limits are enabled" }, "max_channels": { "type": "integer", "example": 1, "description": "Maximum number of concurrent channels allowed" }, "cost_limit": { "type": "boolean", "description": "Whether maximum call cost limit is enabled" }, "max_call_cost": { "type": "string", "example": "0.0", "description": "Maximum allowed cost per call" }, "created_at": { "type": "string", "example": "2026-04-10 11:11:15 UTC", "description": "Account creation timestamp" }, "low_balance": { "type": "boolean", "description": "Whether account has low balance" }, "allowed_ips": { "type": "array", "items": {}, "description": "List of IP addresses allowed to authenticate" }, "charge": { "type": "string", "example": "0.0", "description": "Total charges accumulated on this account" }, "talk_time": { "type": "integer", "example": 0, "description": "Total talk time in seconds" }, "spend_limit": { "type": "string", "example": "0.0", "description": "Maximum total spend amount" }, "spend_limit_enabled": { "type": "boolean", "description": "Whether spending limit is enabled" }, "available_amount": { "type": "string", "example": "0.0", "description": "Amount available for spending" }, "call_recording_enabled": { "type": "boolean" } }, "required": [ "id", "name", "callerid", "label", "host", "rewrite_enabled", "rewrite_cond", "rewrite_prefix", "didinfo_enabled", "ip_restrict", "call_restrict", "call_limit", "channels_restrict", "max_channels", "cost_limit", "max_call_cost", "created_at", "low_balance", "allowed_ips", "charge", "talk_time", "spend_limit", "spend_limit_enabled", "available_amount" ], "description": "SIP account details" } }, "required": [ "sipaccount" ] }, "example": { "sipaccount": { "id": 464, "name": "75303", "callerid": "", "label": "some-label-456", "host": "dynamic", "rewrite_enabled": false, "rewrite_cond": "", "rewrite_prefix": "", "didinfo_enabled": true, "ip_restrict": false, "call_restrict": false, "call_limit": 60, "channels_restrict": false, "max_channels": 1, "cost_limit": false, "max_call_cost": "0.0", "created_at": "2026-04-10 11:11:15 UTC", "low_balance": false, "allowed_ips": [], "charge": "0.0", "talk_time": 0, "spend_limit": "0.0", "spend_limit_enabled": false, "available_amount": "0.0", "call_recording_enabled": false } } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the SIP account name nor id matches an account you own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "summary": "Update SIP account", "description": "Update SIP account settings.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "01234" }, "example": "01234", "description": "SIP account identifier — the account **name** (e.g. `01234`, which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve the same account." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "sipaccount[label]": { "type": "string", "description": "Account label/name", "example": "Updated Label" }, "sipaccount[password]": { "type": "string", "description": "SIP password" }, "sipaccount[callerid]": { "type": "string", "description": "Caller ID to display on outbound calls", "example": "9876543210" }, "sipaccount[rewrite_enabled]": { "type": "string", "description": "Enable number rewriting" }, "sipaccount[rewrite_cond]": { "type": "string", "description": "Rewrite condition pattern (regular expression)" }, "sipaccount[rewrite_prefix]": { "type": "string", "description": "Prefix to add when rewriting numbers" }, "sipaccount[didinfo_enabled]": { "type": "string", "description": "Enable DID info in SIP headers", "example": "true" }, "sipaccount[ip_restrict]": { "type": "string", "description": "Restrict access by IP address (requires allowed IPs)" }, "sipaccount[call_restrict]": { "type": "string", "description": "Enable per-call cost limits", "example": "true" }, "sipaccount[call_limit]": { "type": "string", "description": "Maximum cost per call in cents", "example": "2000" }, "sipaccount[channels_restrict]": { "type": "string", "description": "Enable concurrent channel limits", "example": "true" }, "sipaccount[max_channels]": { "type": "string", "description": "Maximum concurrent channels allowed", "example": "10" }, "sipaccount[cost_limit]": { "type": "string", "description": "Enable maximum call cost limit" }, "sipaccount[max_call_cost]": { "type": "string", "description": "Maximum allowed cost per call in cents" }, "sipaccount[spend_limit_enabled]": { "type": "string", "description": "Enable total spending limit" }, "sipaccount[spend_limit]": { "type": "string", "description": "Maximum total spend amount in cents" }, "sipaccount[reset_available_amount]": { "type": "string", "description": "Amount available for spend limit reset in cents" }, "sipaccount[call_recording_enabled]": { "type": "string", "description": "Enable or disable recording of outbound calls made via a selected SIP account" } } } } } }, "responses": { "200": { "description": "Successfully updates SIP account settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "sipaccount": { "type": "object", "properties": { "id": { "type": "integer", "example": 468, "description": "Unique SIP account identifier" }, "name": { "type": "string", "example": "83256", "description": "SIP account username" }, "callerid": { "type": "string", "example": "", "description": "Caller ID" }, "label": { "type": "string", "example": "Updated Label", "description": "Account label" }, "host": { "type": "string", "example": "dynamic", "description": "SIP server host" }, "rewrite_enabled": { "type": "boolean", "description": "Whether number rewriting is enabled" }, "rewrite_cond": { "type": "string", "example": "", "description": "Rewrite condition pattern (regular expression)" }, "rewrite_prefix": { "type": "string", "example": "", "description": "Prefix to add when rewriting numbers" }, "didinfo_enabled": { "type": "boolean", "example": true, "description": "Whether DID info is included in SIP headers" }, "ip_restrict": { "type": "boolean", "description": "Whether access is restricted by IP address" }, "call_restrict": { "type": "boolean", "example": true, "description": "Whether per-call cost limits are enabled" }, "call_limit": { "type": "integer", "example": 2000, "description": "Maximum cost per call in cents" }, "channels_restrict": { "type": "boolean", "example": true, "description": "Whether concurrent channel limits are enabled" }, "max_channels": { "type": "integer", "example": 5, "description": "Maximum number of concurrent channels allowed" }, "cost_limit": { "type": "boolean", "description": "Whether maximum call cost limit is enabled" }, "max_call_cost": { "type": "string", "example": "0.0", "description": "Maximum allowed cost per call" }, "created_at": { "type": "string", "example": "2026-04-10 11:11:23 UTC", "description": "Account creation timestamp" }, "low_balance": { "type": "boolean", "description": "Whether account has low balance" }, "allowed_ips": { "type": "array", "items": {}, "description": "List of IP addresses allowed to authenticate" }, "charge": { "type": "string", "example": "0.0", "description": "Total charges accumulated on this account" }, "talk_time": { "type": "integer", "example": 0, "description": "Total talk time in seconds" }, "spend_limit": { "type": "string", "example": "10000.0", "description": "Maximum total spend amount" }, "spend_limit_enabled": { "type": "boolean", "description": "Whether spending limit is enabled" }, "available_amount": { "type": "string", "example": "10000.0", "description": "Amount available for spending" }, "call_recording_enabled": { "type": "boolean" } }, "required": [ "id", "name", "callerid", "label", "host", "rewrite_enabled", "rewrite_cond", "rewrite_prefix", "didinfo_enabled", "ip_restrict", "call_restrict", "call_limit", "channels_restrict", "max_channels", "cost_limit", "max_call_cost", "created_at", "low_balance", "allowed_ips", "charge", "talk_time", "spend_limit", "spend_limit_enabled", "available_amount" ], "description": "Updated SIP account details" }, "warnings": { "type": "array", "description": "Non-fatal notices for parts of the request that were accepted but silently skipped (e.g. an unverified caller ID). Present only when non-empty.", "items": { "$ref": "#/components/schemas/Warning" } } }, "required": [ "sipaccount" ] }, "example": { "sipaccount": { "id": 468, "name": "83256", "callerid": "", "label": "Updated Label", "host": "dynamic", "rewrite_enabled": false, "rewrite_cond": "", "rewrite_prefix": "", "didinfo_enabled": true, "ip_restrict": false, "call_restrict": true, "call_limit": 2000, "channels_restrict": true, "max_channels": 5, "cost_limit": false, "max_call_cost": "0.0", "created_at": "2026-04-10 11:11:23 UTC", "low_balance": false, "allowed_ips": [], "charge": "0.0", "talk_time": 0, "spend_limit": "10000.0", "spend_limit_enabled": false, "available_amount": "10000.0", "call_recording_enabled": false }, "warnings": [ { "resource": "caller_id", "identifier": "9876543210", "code": "not_an_owned_or_verified_caller_id", "message": "is not an owned or verified caller ID and was ignored" } ] } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the SIP account name nor id matches an account you own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "summary": "Delete SIP account", "description": "Delete a SIP account.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "01234" }, "example": "01234", "description": "SIP account identifier — the account **name** (e.g. `01234`, which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve the same account." } ], "responses": { "204": { "description": "Successfully deletes SIP account" }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope {\"errors\":{\"base\":[\"data not found\"]}} when neither the SIP account name nor id matches an account you own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/sipaccounts/{sipaccount_id}/allowed_ips": { "get": { "summary": "List allowed IP addresses", "description": "Retrieve list of IP addresses allowed to authenticate this SIP account.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "parameters": [ { "name": "sipaccount_id", "in": "path", "required": true, "schema": { "type": "string", "example": "01234" }, "example": "01234", "description": "Parent SIP account identifier — the account **name** (e.g. `01234`, which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve the same account." } ], "responses": { "200": { "description": "Successfully returns list of allowed IP addresses", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_ips": { "type": "array", "items": { "type": "string" }, "description": "List of allowed IP address strings" } }, "required": [ "allowed_ips" ] }, "example": { "allowed_ips": [ "1.2.3.4" ] } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope when neither the SIP account name nor id matches an account you own", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "summary": "Add allowed IP address", "description": "Add IP address to SIP account whitelist.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "parameters": [ { "name": "sipaccount_id", "in": "path", "required": true, "schema": { "type": "string", "example": "01234" }, "example": "01234", "description": "Parent SIP account identifier — the account **name** (e.g. `01234`, which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve the same account." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP address to allow", "example": "1.2.3.4" } }, "required": [ "ip" ] } } } }, "responses": { "200": { "description": "Successfully adds IP to whitelist", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_ips": { "type": "array", "items": { "type": "string" }, "description": "List of allowed IP addresses after creation" } }, "required": [ "allowed_ips" ] }, "example": { "allowed_ips": [ "1.2.3.4" ] } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope when neither the SIP account name nor id matches an account you own", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } }, "422": { "description": "Returns 422 error when IP address format is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "ip": [ "can't be blank", "only ip format xxx.xxx.xxx.xxx" ] } } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "summary": "Remove allowed IP address", "description": "Remove IP address from SIP account whitelist.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SIP Accounts" ], "parameters": [ { "name": "sipaccount_id", "in": "path", "required": true, "schema": { "type": "string", "example": "01234" }, "example": "01234", "description": "Parent SIP account identifier — the account **name** (e.g. `01234`, which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve the same account." }, { "name": "ip", "in": "query", "required": true, "schema": { "type": "string" }, "description": "IP address to remove", "example": "1.2.3.4" } ], "responses": { "204": { "description": "Successfully removes IP from whitelist" }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "Returns the 404 error envelope when neither the SIP account name nor id matches an account you own", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/sms": { "get": { "summary": "List sent SMS messages", "description": "Retrieve paginated list of SMS messages sent by the authenticated user.\nNote: Contact your account manager to set up a Relay URL for inbound messages.\n", "tags": [ "SMS" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "string", "minimum": 1, "default": 1 }, "description": "Page number for pagination (starts from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "string", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of items per page" } ], "responses": { "200": { "description": "Successfully returns paginated list of sent SMS messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "sms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 100, "description": "SMS ID" }, "destination": { "type": "string", "example": "1234567890", "description": "Destination number" }, "message": { "type": "string", "example": "Test", "description": "Message content" }, "status": { "type": "string", "enum": [ "created", "failed", "sent", "dlr_error", "delivered", "not_delivered", "interrupted" ], "example": "created", "description": "Delivery status" }, "charge": { "type": "number", "format": "float", "example": 0, "description": "SMS cost" }, "segments_count": { "type": "integer", "example": 1, "description": "Number of segments" } }, "required": [ "id", "destination", "message", "status", "charge", "segments_count" ] }, "description": "List of SMS messages" }, "pagination": { "type": "object", "properties": { "pages": { "type": "integer" }, "page": { "type": "integer" }, "total_records": { "type": "integer" }, "per_page": { "type": "integer" } }, "required": [ "pages", "page", "total_records", "per_page" ] } }, "required": [ "sms", "pagination" ] }, "example": { "sms": [ { "id": 100, "destination": "1234567890", "message": "Test", "status": "created", "charge": 0, "segments_count": 1 } ], "pagination": { "pages": 1, "page": 1, "total_records": 1, "per_page": 100 } } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "summary": "Send SMS message", "description": "Send an SMS message from a DID number owned by the authenticated user.\n\n**Requirements:**\n- Source DID must be owned by user\n- Source DID must have SMS enabled\n- Sufficient account balance for SMS cost\n- Valid destination phone number\n\n**Cost:**\n- Charged per segment (160 characters)\n- Price varies by destination country\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SMS" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "sm[source]": { "type": "string", "description": "Source DID number (must be SMS-enabled and owned by user)", "example": "1234567890" }, "sm[destination]": { "type": "string", "description": "Destination phone number (must be a valid international number)", "example": "" }, "sm[message]": { "type": "string", "description": "SMS text content (160 chars per segment)", "example": "Test message" }, "dlr[callback_endpoint]": { "type": "string", "description": "Optional DLR (Delivery Receipt) callback URL", "example": "https://example.com/webhook" } }, "required": [ "sm[source]", "sm[destination]", "sm[message]" ] } } } }, "responses": { "200": { "description": "Successfully sends SMS message and returns details with ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "sms": { "type": "object", "properties": { "id": { "type": "integer", "example": 99, "description": "SMS ID" }, "destination": { "type": "string", "example": "12012025555", "description": "Destination number" }, "message": { "type": "string", "example": "Test message from API", "description": "Message content" }, "status": { "type": "string", "enum": [ "created", "failed", "sent", "dlr_error", "delivered", "not_delivered", "interrupted" ], "example": "created", "description": "Delivery status" }, "charge": { "type": "number", "format": "float", "example": 0.0001, "description": "SMS cost" }, "segments_count": { "type": "integer", "example": 1, "description": "Number of segments" } }, "required": [ "id", "destination", "message", "status", "charge", "segments_count" ], "description": "Created SMS details" } }, "required": [ "sms" ] }, "example": { "sms": { "id": 99, "destination": "12012025555", "message": "Test message from API", "status": "created", "charge": 0.0001, "segments_count": 1 } } } } }, "400": { "description": "The request body must be valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": {} } } }, "403": { "description": "Returns 403 error when destination number is blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "examples": { "returns_403_error_when_api_token_is_incorrect": { "summary": "Returns 403 error when API token is incorrect", "value": { "error": "Unauthorized" } }, "returns_403_error_when_destination_number_is_blocked": { "summary": "Returns 403 error when destination number is blocked", "value": { "error": "SMS delivery to this destination is currently restricted" } } } } } }, "422": { "description": "Returns 422 error when destination phone number is invalid", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] }, "examples": { "returns_422_error_when_destination_parameter_is_missing_or_empty": { "summary": "Returns 422 error when destination parameter is missing or empty", "value": { "errors": { "destination": [ "Required" ] } } }, "returns_422_error_when_destination_phone_number_is_invalid": { "summary": "Returns 422 error when destination phone number is invalid", "value": { "error": "SMS delivery failed: Invalid phone number" } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/sms/{id}": { "get": { "summary": "Get SMS message details", "description": "Retrieve details of a specific SMS message sent by the authenticated user.\n\n**Returned Information:**\n- SMS ID and status\n- Source and destination numbers\n- Message content\n- Delivery status and timestamps\n- Cost and segment count\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "SMS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 103, "description": "SMS message ID" } ], "responses": { "200": { "description": "Successfully returns SMS message details including status and timestamps", "content": { "application/json": { "schema": { "type": "object", "properties": { "sms": { "type": "object", "properties": { "id": { "type": "integer", "example": 102, "description": "SMS ID" }, "destination": { "type": "string", "example": "1234567890", "description": "Destination number" }, "message": { "type": "string", "example": "Test message", "description": "Message content" }, "status": { "type": "string", "enum": [ "created", "failed", "sent", "dlr_error", "delivered", "not_delivered", "interrupted" ], "example": "created", "description": "Delivery status" }, "charge": { "type": "number", "format": "float", "example": 0, "description": "SMS cost" }, "segments_count": { "type": "integer", "example": 1, "description": "Number of segments" } }, "required": [ "id", "destination", "message", "status", "charge", "segments_count" ], "description": "SMS message details" } }, "required": [ "sms" ] }, "example": { "sms": { "id": 102, "destination": "1234567890", "message": "Test message", "status": "created", "charge": 0, "segments_count": 1 } } } } }, "403": { "description": "Returns 403 error when API token is incorrect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v2/numbers/countries": { "get": { "summary": "List countries", "description": "Retrieve a list of all countries where DID numbers are available.\n\n**When to use:**\n- Building country selection interface\n- Checking number availability by country\n- Starting the DID purchase flow\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "returns list of available countries", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1907, "description": "Country identifier" }, "name": { "type": "string", "example": "United States", "description": "Country name" }, "short_name": { "type": "string", "example": "US", "description": "ISO 3166-1 alpha-2 country code" }, "has_provinces_or_states": { "type": "boolean", "description": "Whether country has states or provinces" } }, "required": [ "id", "name", "short_name", "has_provinces_or_states" ] }, "description": "List of countries with available DID numbers" } }, "required": [ "countries" ] }, "example": { "countries": [ { "id": 1907, "name": "United States", "short_name": "US", "has_provinces_or_states": false } ] } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } } } } }, "/api/v2/numbers/countries/{country_id}/cities": { "get": { "summary": "List cities", "description": "Retrieve a list of cities within a country where DID numbers are available.\n\n**Important notes:**\n- For countries with states/provinces, use region-specific endpoint instead\n- Each city includes count of available DIDs\n- Cities are returned with area codes\n\n**When to use:**\n- Building city selection for countries without states\n- Checking DID availability by city\n- Displaying available locations to users\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "country_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 0, "description": "Country identifier" } ], "responses": { "200": { "description": "returns list of cities", "content": { "application/json": { "schema": { "type": "object", "properties": { "cities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1955, "description": "City identifier" }, "name": { "type": "string", "example": "New York", "description": "City name and state/province" }, "area_code": { "type": "string", "example": "212200", "description": "Area code for this city" }, "count": { "type": "integer", "minimum": 0, "example": 1, "description": "Number of available DIDs in this city" } }, "required": [ "id", "name", "area_code", "count" ] }, "description": "List of cities with available DID numbers" } }, "required": [ "cities" ] }, "example": { "cities": [ { "id": 1955, "name": "New York", "area_code": "212200", "count": 1 } ] } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } } } } }, "/api/v2/numbers/countries/{country_id}/regions": { "get": { "summary": "List NANP regions", "description": "Retrieve a list of states or provinces within a country (e.g., US states, Canadian provinces).\n\n**Important notes:**\n- Only applicable for countries with `has_provinces_or_states: true`\n- Returns 404 for countries without regional divisions\n- Use this before querying cities in countries with states/provinces\n\n**When to use:**\n- Building state/province selection for US, Canada, etc.\n- Filtering DID search by region\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "country_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1926, "description": "Country identifier" } ], "responses": { "200": { "description": "returns list of regions", "content": { "application/json": { "schema": { "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Region/state identifier" }, "name": { "type": "string", "example": "New York", "description": "State or province name" }, "short_name": { "type": "string", "example": "NY", "description": "State abbreviation" } }, "required": [ "id", "name", "short_name" ] }, "description": "List of states/provinces with available DID numbers" } }, "required": [ "regions" ] }, "example": { "regions": [ { "id": 1, "name": "New York", "short_name": "NY" } ] } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } } } } }, "/api/v2/numbers/countries/{country_id}/locations": { "get": { "summary": "Search locations by prefix", "description": "Search for locations (cities) that have DID numbers starting with a specific prefix.\n\n**Important notes:**\n- Useful for finding locations with specific area codes\n- Prefix can be partial number (e.g., \"212\" for NYC area code)\n- Returns combined location information (country, state, city)\n\n**When to use:**\n- Implementing \"vanity number\" search by prefix\n- Finding locations with specific area codes\n- Reverse lookup of number to location\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "country_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1962, "description": "Country identifier" }, { "name": "prefix", "in": "query", "required": true, "schema": { "type": "integer" }, "example": 212, "description": "Number prefix to search for" }, { "name": "sms_enabled", "in": "query", "required": false, "schema": { "type": "string" }, "example": "true", "description": "Filter locations by SMS capability" } ], "responses": { "200": { "description": "returns list of locations", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "city_id": { "type": "integer", "example": 1975, "description": "City identifier" }, "city_name": { "type": "string", "example": "New York", "description": "City name" }, "country_name": { "type": "string", "example": "United States", "description": "Country name" }, "state_id": { "type": "integer", "example": 12, "description": "State identifier (if applicable)" }, "country_id": { "type": "integer", "example": 1959, "description": "Country identifier" }, "label": { "type": "string", "example": "New York 212200, United States", "description": "Combined location label for display" }, "city_code": { "type": "integer", "example": 212200, "description": "City code/area code" }, "state_name": { "type": "string", "example": "New York", "description": "State name (if applicable)" } }, "required": [ "city_id", "city_name", "country_name", "state_id", "country_id", "label", "city_code", "state_name" ] }, "description": "List of locations matching search criteria" } }, "required": [ "locations" ] }, "example": { "locations": [ { "city_id": 1975, "city_name": "New York", "country_name": "United States", "state_id": 12, "country_id": 1959, "label": "New York 212200, United States", "city_code": 212200, "state_name": "New York" } ] } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } } } } }, "/api/v2/numbers/countries/{country_id}/cities/{city_id}/dids": { "get": { "summary": "List numbers by city", "description": "Retrieve paginated list of available DID numbers in a specific city.\n\n**Important notes:**\n- For countries without regions (UK, Netherlands, etc.)\n- Results are paginated (default 25 per page)\n- Includes full pricing and feature details for each number\n- Use for countries where regions are not applicable\n\n**When to use:**\n- Displaying available numbers after city selection\n- Browsing DID inventory by location\n- Non-US/Canada purchase flows\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "country_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 0, "description": "Country identifier" }, { "name": "city_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1950, "description": "City identifier" } ], "responses": { "200": { "description": "returns list of available dids", "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 1, "description": "Total number of items" }, "total_pages": { "type": "integer", "example": 1, "description": "Total number of pages" }, "current_page": { "type": "integer", "example": 1, "description": "Current page number" } }, "required": [ "total", "total_pages", "current_page" ], "description": "Pagination metadata" }, "dids": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2622, "description": "DID identifier" }, "country": { "type": "string", "example": "United States", "description": "Country name" }, "city": { "type": "string", "example": "New York", "description": "City name" }, "sms_enabled": { "type": "boolean", "description": "Whether SMS is available for this number" }, "no_local_cli": { "type": "boolean", "description": "Whether number does not support local caller ID" }, "channels": { "type": "integer", "example": 1, "description": "Maximum simultaneous calls" }, "free_min": { "type": "integer", "example": 0, "description": "Free minutes included per month" }, "cnam": { "type": "boolean", "description": "Caller Name (CNAM) support" }, "commitment_months": { "type": "integer", "example": 12, "description": "Minimum service term in months" }, "activation": { "type": "number", "format": "float", "example": 1.17, "description": "One-time activation fee (USD)" }, "monthly": { "type": "number", "format": "float", "example": 1.755, "description": "Monthly recurring fee (USD)" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per-minute inbound call rate (USD)" }, "origination_per_min": { "type": "number", "format": "float", "example": 0.585, "description": "Per-minute origination rate (USD)" }, "required_documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "example": 22, "description": "Document type ID" }, "name": { "type": "string", "example": "Proof of Address", "description": "Document type name" } }, "required": [ "type", "name" ] }, "description": "List of required documents for this number" }, "state": { "type": "string", "example": "New York", "description": "State name (if applicable)" }, "country_short_name": { "type": "string", "example": "US", "description": "ISO country code" }, "number": { "type": "string", "example": "12122001234", "description": "Phone number" }, "never_sold": { "type": "integer", "example": 1, "description": "Whether number has never been sold before (1=yes, 0=no)" }, "call_recording_enabled": { "type": "boolean" } }, "required": [ "id", "country", "city", "sms_enabled", "no_local_cli", "channels", "free_min", "cnam", "commitment_months", "activation", "monthly", "per_minute", "origination_per_min", "required_documents", "state", "country_short_name", "number", "never_sold" ] }, "description": "Array of available DID numbers" } }, "required": [ "pagination", "dids" ], "description": "Paginated list of available DID numbers" } }, "required": [ "dids" ] }, "example": { "dids": { "pagination": { "total": 1, "total_pages": 1, "current_page": 1 }, "dids": [ { "id": 2622, "country": "United States", "city": "New York", "sms_enabled": false, "no_local_cli": false, "channels": 1, "free_min": 0, "cnam": false, "commitment_months": 12, "required_documents": [ { "type": 22, "name": "Proof of Address" } ], "activation": 1.17, "monthly": 1.755, "per_minute": 0.117, "origination_per_min": 0.585, "state": "New York", "country_short_name": "US", "number": "12122001234", "never_sold": 1, "call_recording_enabled": false } ] } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } } } } }, "/api/v2/numbers/search": { "get": { "summary": "Search numbers (advanced)", "description": "Advanced search for available DID numbers with multiple filter criteria.\n\n**Important notes:**\n- Supports pagination (page, per_page parameters)\n- All filter parameters are optional\n- Combine multiple filters for precise results\n- Use for complex search scenarios beyond location-based browsing\n\n**When to use:**\n- Implementing vanity number search\n- Finding numbers with specific features\n- Custom number selection interfaces\n- Bulk number lookup\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id_in", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 2653, "description": "Search for specific DID IDs (comma-separated)" }, { "name": "number_in", "in": "query", "required": false, "schema": { "type": "string" }, "example": "12125551234,12125559876", "description": "Search for specific numbers (exact match, comma-separated)" }, { "name": "number_contains", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 555, "description": "Search for numbers containing this pattern" }, { "name": "begins_with", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 121, "description": "Search for numbers beginning with this pattern" }, { "name": "ends_with", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1234, "description": "Search for numbers ending with this pattern" }, { "name": "city_name_contains", "in": "query", "required": false, "schema": { "type": "string" }, "example": "YORK", "description": "Filter by city name (partial match)" }, { "name": "country_name_contains", "in": "query", "required": false, "schema": { "type": "string" }, "example": "United States", "description": "Filter by country name (partial match)" }, { "name": "state_name_contains", "in": "query", "required": false, "schema": { "type": "string" }, "example": "York", "description": "Filter by state/region name (partial match, US only)" }, { "name": "sms_enabled", "in": "query", "required": false, "schema": { "type": "string" }, "example": "true", "description": "Filter by SMS capability (true/false)" }, { "name": "no_local_cli", "in": "query", "required": false, "schema": { "type": "string" }, "example": "false", "description": "Filter by local caller ID capability (true/false)" }, { "name": "vendor_id", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 6241, "description": "Filter by vendor ID (requires special permission)" }, { "name": "city_id", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1972, "description": "Filter by city ID" }, { "name": "region_id", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 11, "description": "Filter by region ID" }, { "name": "require_docs", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1, "description": "Filter by document requirements" }, { "name": "commitment_months", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 12, "description": "Filter by commitment period in months" }, { "name": "cheap_sorting", "in": "query", "required": false, "schema": { "type": "string" }, "example": "false", "description": "Sort by price (activation + monthly fee) ascending" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1, "description": "Page number for pagination" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25, "description": "Number of items per page" } ], "responses": { "200": { "description": "returns search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 1, "description": "Total number of items" }, "total_pages": { "type": "integer", "example": 1, "description": "Total number of pages" }, "current_page": { "type": "integer", "example": 1, "description": "Current page number" } }, "required": [ "total", "total_pages", "current_page" ], "description": "Pagination metadata" }, "dids": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2651, "description": "DID identifier" }, "country": { "type": "string", "example": "United States", "description": "Country name" }, "city": { "type": "string", "example": "NEW YORK CITY", "description": "City name" }, "sms_enabled": { "type": "boolean", "example": true, "description": "Whether SMS is available for this number" }, "no_local_cli": { "type": "boolean", "description": "Whether number does not support local caller ID" }, "channels": { "type": "integer", "example": 2, "description": "Maximum simultaneous calls" }, "free_min": { "type": "integer", "example": 100, "description": "Free minutes included per month" }, "cnam": { "type": "boolean", "description": "Caller Name (CNAM) support" }, "commitment_months": { "type": "integer", "example": 12, "description": "Minimum service term in months" }, "activation": { "type": "number", "format": "float", "example": 2.925, "description": "One-time activation fee (USD)" }, "monthly": { "type": "number", "format": "float", "example": 0.9945, "description": "Monthly recurring fee (USD)" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per-minute inbound call rate (USD)" }, "origination_per_min": { "nullable": true, "description": "Per-minute origination rate (USD)" }, "required_documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "integer", "example": 34, "description": "Document type ID" }, "name": { "type": "string", "example": "Proof of Address", "description": "Document type name" } }, "required": [ "type", "name" ] }, "description": "List of required documents for this number" }, "state": { "type": "string", "example": "", "description": "State name (if applicable)" }, "country_short_name": { "type": "string", "example": "US", "description": "ISO country code" }, "number": { "type": "string", "example": "12125551234", "description": "Phone number" }, "never_sold": { "type": "integer", "example": 1, "description": "Whether number has never been sold before (1=yes, 0=no)" }, "call_recording_enabled": { "type": "boolean" } }, "required": [ "id", "country", "city", "sms_enabled", "no_local_cli", "channels", "free_min", "cnam", "commitment_months", "activation", "monthly", "per_minute", "origination_per_min", "required_documents", "state", "country_short_name", "number", "never_sold" ] }, "description": "Array of available DID numbers" } }, "required": [ "pagination", "dids" ], "description": "Paginated search results" } }, "required": [ "dids" ] }, "example": { "dids": { "pagination": { "total": 1, "total_pages": 1, "current_page": 1 }, "dids": [ { "id": 2651, "country": "United States", "city": "NEW YORK CITY", "sms_enabled": true, "no_local_cli": false, "channels": 2, "free_min": 100, "cnam": false, "commitment_months": 12, "required_documents": [ { "type": 34, "name": "Proof of Address" } ], "activation": 2.925, "monthly": 0.9945, "per_minute": 0.117, "origination_per_min": null, "state": "", "country_short_name": "US", "number": "12125551234", "never_sold": 1, "call_recording_enabled": false } ] } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } } } } }, "/api/v2/numbers": { "get": { "summary": "List purchased numbers", "description": "Retrieve a list of DID numbers purchased by the authenticated user.\n\n**Important notes:**\n- Returns only active numbers by default\n- Use `show_all=true` to include numbers pending document approval\n- Includes service information (SMS, etc.)\n- Shows current status of each number\n\n**When to use:**\n- Displaying user's number inventory\n- Checking number status\n- Listing numbers for configuration\n- Dashboard display\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "show_all", "in": "query", "required": false, "schema": { "type": "string" }, "example": "true", "description": "Include numbers pending documentation approval" } ], "responses": { "200": { "description": "returns DIDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2654, "description": "Unique DID identifier" }, "number": { "type": "string", "example": "1234567890", "description": "Phone number" }, "country": { "type": "string", "example": "United States", "description": "Country name where the number is located" }, "area": { "type": "string", "example": "New York", "description": "City or area name" }, "channels": { "type": "integer", "example": 1, "description": "Number of simultaneous call channels" }, "activation": { "type": "number", "format": "float", "example": 1.17, "description": "One-time activation fee" }, "monthly_fee": { "type": "number", "format": "float", "example": 1.17, "description": "Monthly recurring fee" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per-minute rate for incoming calls" }, "services": { "type": "array", "items": { "type": "string", "enum": [ "sms" ] }, "description": "List of enabled services (e.g., sms)" }, "status": { "type": "string", "enum": [ "active", "pending_docs" ], "example": "active", "description": "Current status of the number" }, "destination_count": { "type": "integer", "example": 0, "description": "Number of configured routing destinations" }, "call_recording_enabled": { "type": "boolean" }, "commitment_months": { "type": "integer", "example": 6, "description": "Minimum commitment period in months" }, "identity_id": { "type": "integer", "example": 198, "description": "Associated identity/document ID for verification" } }, "required": [ "id", "number", "country", "area", "channels", "activation", "monthly_fee", "per_minute", "services", "status", "destination_count", "call_recording_enabled", "commitment_months", "identity_id" ] }, "description": "List of DID numbers owned by the user" } }, "required": [ "dids" ] }, "example": { "dids": [ { "id": 2654, "number": "1234567890", "country": "United States", "area": "New York", "channels": 1, "activation": 1.17, "monthly_fee": 1.17, "per_minute": 0.117, "services": [ "sms" ], "status": "active", "destination_count": 0, "call_recording_enabled": false, "commitment_months": 6, "identity_id": 198 } ] } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } } } }, "/api/v2/numbers/purchase": { "post": { "summary": "Purchase numbers", "description": "Purchase one or more DID numbers with identity document association.\n\n**Important notes:**\n- Can purchase multiple numbers in a single request\n- Identities must contain required documents for the number's country\n\n**When to use:**\n- Purchasing numbers with document verification\n- Bulk number purchase with identity association\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "id_in": { "type": "array", "items": { "type": "string" }, "description": "Array of DID IDs to purchase", "example": [ 2531, 2532, 2533 ] }, "did_numbers": { "type": "array", "items": { "type": "string" }, "description": "Array of DID numbers to purchase", "example": [ "1111111111", "2222222222", "3333333333" ] }, "identities": { "type": "array", "items": { "type": "object" }, "description": "Array of identity objects with document associations", "example": [ { "id": 1188, "did_ids": [ 12972 ] }, { "id": 1189, "did_numbers": [ "2222222222" ] } ] } } } } } }, "responses": { "200": { "description": "purchase DIDs and link documents attached to identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "errors": { "type": "object", "properties": {}, "description": "Errors that occurred during purchase" }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 12966, "description": "DID identifier" }, "number": { "type": "string", "example": "1111111111", "description": "Purchased phone number" }, "sms_enabled": { "type": "boolean", "description": "Whether SMS is enabled" }, "no_local_cli": { "type": "boolean", "description": "Whether local caller ID is disabled" }, "channels": { "type": "integer", "example": 1, "description": "Maximum simultaneous calls" }, "country": { "type": "string", "example": "c1", "description": "Country name" }, "area": { "type": "string", "example": "Fake city for 1111111111", "description": "City/area name" }, "free_minutes": { "type": "integer", "example": 0, "description": "Free minutes included per month" }, "codec": { "nullable": true, "description": "Audio codec" }, "require_docs": { "type": "string", "example": "1,2,3", "description": "Comma-separated list of required document type IDs" }, "commitment_months": { "type": "integer", "example": 12, "description": "Minimum service term in months (omitted when the commitment policy is disabled)" }, "activation": { "type": "number", "format": "float", "example": 1.17, "description": "One-time activation fee (USD)" }, "monthly_fee": { "type": "number", "format": "float", "example": 0.585, "description": "Monthly recurring fee (USD)" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per-minute inbound call rate (USD)" }, "origination_per_min": { "type": "number", "format": "float", "example": 0, "description": "Per-minute origination rate (USD)" }, "never_sold": { "type": "integer", "example": 1, "description": "Whether number has never been sold before (1=yes, 0=no)" } }, "required": [ "id", "number", "sms_enabled", "no_local_cli", "channels", "country", "area", "free_minutes", "codec", "require_docs", "activation", "monthly_fee", "per_minute", "origination_per_min", "never_sold" ] }, "description": "Successfully purchased numbers" } }, "required": [ "errors", "purchases" ], "description": "Purchase response object" } }, "required": [ "purchase" ] }, "example": { "purchase": { "errors": {}, "purchases": [ { "id": 12966, "number": "1111111111", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "c1", "area": "Fake city for 1111111111", "free_minutes": 0, "codec": null, "require_docs": "1,2,3", "commitment_months": 12, "never_sold": 1, "activation": 1.17, "monthly_fee": 0.585, "per_minute": 0.117, "origination_per_min": 0 }, { "id": 12967, "number": "2222222222", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "c2", "area": "Fake city for 2222222222", "free_minutes": 0, "codec": null, "require_docs": "1,2", "commitment_months": 12, "never_sold": 1, "activation": 1.17, "monthly_fee": 0.585, "per_minute": 0.117, "origination_per_min": 0 }, { "id": 12968, "number": "3333333333", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "c2", "area": "Fake city for 3333333333", "free_minutes": 0, "codec": null, "require_docs": "1,2", "commitment_months": 12, "never_sold": 1, "activation": 1.17, "monthly_fee": 0.585, "per_minute": 0.117, "origination_per_min": 0 } ] } } } } }, "400": { "description": "returns bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" } }, "required": [ "error" ] }, "example": { "error": true } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "422": { "description": "returns errors for unprocessed entities", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "base": { "type": "array", "items": { "type": "string" } } }, "required": [ "base" ], "description": "Errors that occurred during purchase" }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 12972, "description": "DID identifier" }, "number": { "type": "string", "example": "1111111111", "description": "Purchased phone number" }, "sms_enabled": { "type": "boolean", "description": "Whether SMS is enabled" }, "no_local_cli": { "type": "boolean", "description": "Whether local caller ID is disabled" }, "channels": { "type": "integer", "example": 1, "description": "Maximum simultaneous calls" }, "country": { "type": "string", "example": "c1", "description": "Country name" }, "area": { "type": "string", "example": "Fake city for 1111111111", "description": "City/area name" }, "free_minutes": { "type": "integer", "example": 0, "description": "Free minutes included per month" }, "codec": { "nullable": true, "description": "Audio codec" }, "require_docs": { "type": "string", "example": "1,2,3", "description": "Comma-separated list of required document type IDs" }, "commitment_months": { "type": "integer", "example": 12, "description": "Minimum service term in months" }, "activation": { "type": "number", "format": "float", "example": 1.17, "description": "One-time activation fee (USD)" }, "monthly_fee": { "type": "number", "format": "float", "example": 0.585, "description": "Monthly recurring fee (USD)" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per-minute inbound call rate (USD)" }, "origination_per_min": { "type": "number", "format": "float", "example": 0, "description": "Per-minute origination rate (USD)" }, "never_sold": { "type": "integer", "example": 1, "description": "Whether number has never been sold before (1=yes, 0=no)" } }, "required": [ "id", "number", "sms_enabled", "no_local_cli", "channels", "country", "area", "free_minutes", "codec", "require_docs", "commitment_months", "activation", "monthly_fee", "per_minute", "origination_per_min", "never_sold" ] }, "description": "Successfully purchased numbers" } }, "required": [ "errors", "purchases" ], "description": "Purchase response object" } }, "required": [ "purchase" ] } ] }, "examples": { "the_request_could_not_be_processed_because_one_or_more_fields_are_missing_or_invalid_see_errors_for_details": { "summary": "The request could not be processed because one or more fields are missing or invalid. See `errors` for details.", "value": { "errors": { "identities": [ "is missing or malformed" ] } } }, "returns_errors_for_unprocessed_entities": { "summary": "returns errors for unprocessed entities", "value": { "purchase": { "errors": { "base": [ "Low balance" ] }, "purchases": [ { "id": 10145, "number": "1111111111", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "c1", "area": "Fake city for 1111111111", "free_minutes": 0, "codec": null, "require_docs": "1,2,3", "commitment_months": 12, "never_sold": 1, "activation": 1.17, "monthly_fee": 0.585, "per_minute": 0.117, "origination_per_min": 0 }, { "id": 10146, "number": "2222222222", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "c2", "area": "Fake city for 2222222222", "free_minutes": 0, "codec": null, "require_docs": "1,2", "commitment_months": 12, "never_sold": 1, "activation": 1.17, "monthly_fee": 0.585, "per_minute": 0.117, "origination_per_min": 0 }, { "id": 10147, "number": "3333333333", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "c2", "area": "Fake city for 3333333333", "free_minutes": 0, "codec": null, "require_docs": "1,2", "commitment_months": 12, "never_sold": 1, "activation": 1.17, "monthly_fee": 0.585, "per_minute": 0.117, "origination_per_min": 0 } ] } } } } } } } } }, "put": { "summary": "Update purchased number settings", "description": "Update a purchased DID number's identity association or call recording setting.\n\n**Important notes:**\n- New identity must contain required documents for the number\n- `call_recording_enabled` requires the account-level \"Allow call recording\" setting to be on; returns 422 otherwise\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "DID ID", "example": 13001 }, "identity_id": { "type": "integer", "description": "Identity ID to associate with the number", "example": 1207 }, "call_recording_enabled": { "type": "string", "description": "Enable or disable inbound call recording for this DID" } } } } } }, "responses": { "200": { "description": "updates purchased number", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "integer", "example": 12998, "description": "DID identifier" }, "number": { "type": "string", "example": "1234567890", "description": "Phone number" }, "country": { "type": "string", "example": "US", "description": "Country name" }, "area": { "type": "string", "example": "Fake city for 1234567890", "description": "City/area name" }, "channels": { "type": "integer", "example": 1, "description": "Maximum simultaneous calls" }, "activation": { "type": "number", "format": "float", "example": 1.17, "description": "One-time activation fee (USD)" }, "monthly_fee": { "type": "number", "format": "float", "example": 1.17, "description": "Monthly recurring fee (USD)" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per-minute inbound call rate (USD)" }, "services": { "type": "array", "items": {}, "description": "Enabled services for this number" }, "status": { "type": "string", "enum": [ "active", "pending_docs" ], "example": "pending_docs", "description": "Number status" }, "destination_count": { "type": "integer", "example": 0, "description": "Number of configured routing destinations" }, "commitment_months": { "type": "integer", "example": 12, "description": "Minimum service term in months (omitted when the commitment policy is disabled)" }, "identity_id": { "type": "integer", "example": 1198, "description": "Associated identity ID" }, "call_recording_enabled": { "type": "boolean", "description": "Whether inbound call recording is enabled for this DID" } }, "required": [ "id", "number", "country", "area", "channels", "activation", "monthly_fee", "per_minute", "services", "status", "destination_count", "identity_id" ], "description": "Updated purchase details" }, "invalid_doc_types": { "type": "object", "properties": {}, "description": "Document types that are invalid or missing" } }, "required": [ "purchase", "invalid_doc_types" ] }, "example": { "purchase": { "id": 12998, "number": "1234567890", "country": "US", "area": "Fake city for 1234567890", "channels": 1, "activation": 1.17, "monthly_fee": 1.17, "per_minute": 0.117, "services": [], "status": "pending_docs", "destination_count": 0, "commitment_months": 12, "identity_id": 1198, "call_recording_enabled": false }, "invalid_doc_types": {} } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "422": { "description": "returns unprocessable entity with validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "identity_id": [ "Identity not found or not accessible" ] } } } } }, "500": { "description": "The server could not complete the request. Retry later or contact support if the problem persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "internal server error" ] } } } } } } }, "delete": { "summary": "Delete purchased numbers", "description": "Cancel purchase of DID numbers and return them to inventory.\n\n**Important notes:**\n- Can cancel multiple numbers in a single request\n- Numbers are returned to seller's inventory\n- Optional quarantine period before number becomes available again\n- Refund policy depends on service terms\n\n**When to use:**\n- User wants to cancel number purchase\n- Returning numbers after unsuccessful activation\n- Bulk number release\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n\n**Partial cancellation:** Numbers not present in your cancelable inventory\nare skipped (not cancelled) and reported in the `warnings` array with code\n`not_in_inventory`. If none of the requested numbers are cancelable, the\nrequest returns `422`.\n", "tags": [ "Numbers & Inventory" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id_in", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Array of DID IDs to cancel", "example": [ 12903, 12904, 12905, 999999 ] }, { "name": "did_numbers", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Array of DID numbers to cancel", "example": [ "79090160041", "79090160042", "79090160043" ] } ], "responses": { "200": { "description": "cancels owned numbers and reports skipped ones as warnings", "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 12897, "description": "DID identifier" }, "number": { "type": "string", "example": "79090160035", "description": "Phone number" }, "sms_enabled": { "type": "boolean", "description": "Whether SMS is enabled" }, "no_local_cli": { "type": "boolean", "description": "Whether local caller ID is disabled" }, "channels": { "type": "integer", "example": 1, "description": "Maximum simultaneous calls" }, "country": { "type": "string", "example": "Fake country for 79090160035", "description": "Country name" }, "area": { "type": "string", "example": "Fake city for 79090160035", "description": "City/area name" }, "free_minutes": { "type": "integer", "example": 0, "description": "Free minutes included per month" }, "codec": { "nullable": true, "description": "Audio codec" }, "require_docs": { "type": "string", "example": "", "description": "Comma-separated list of required document type IDs" }, "commitment_months": { "type": "integer", "example": 12, "description": "Minimum service term in months" }, "activation": { "type": "number", "format": "float", "example": 1.17, "description": "One-time activation fee (USD)" }, "monthly_fee": { "type": "number", "format": "float", "example": 1.17, "description": "Monthly recurring fee (USD)" }, "per_minute": { "type": "number", "format": "float", "example": 0.117, "description": "Per-minute inbound call rate (USD)" }, "origination_per_min": { "type": "number", "format": "float", "example": 0, "description": "Per-minute origination rate (USD)" }, "never_sold": { "type": "integer", "example": 0, "description": "Whether number has never been sold before (1=yes, 0=no)" } }, "required": [ "id", "number", "sms_enabled", "no_local_cli", "channels", "country", "area", "free_minutes", "codec", "require_docs", "commitment_months", "activation", "monthly_fee", "per_minute", "origination_per_min", "never_sold" ] }, "description": "List of cancelled DIDs returned to inventory" }, "warnings": { "type": "array", "description": "Non-fatal notices for requested numbers that were not in your cancelable inventory and were skipped. Present only when non-empty.", "items": { "$ref": "#/components/schemas/Warning" } } }, "required": [ "dids" ] }, "example": { "dids": [ { "id": 12897, "number": "79090160035", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "Fake country for 79090160035", "area": "Fake city for 79090160035", "free_minutes": 0, "codec": null, "require_docs": "", "commitment_months": 12, "never_sold": 0, "activation": 1.17, "monthly_fee": 1.17, "per_minute": 0.117, "origination_per_min": 0 }, { "id": 12898, "number": "79090160036", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "Fake country for 79090160035", "area": "Fake city for 79090160035", "free_minutes": 0, "codec": null, "require_docs": "", "commitment_months": 12, "never_sold": 0, "activation": 1.17, "monthly_fee": 1.17, "per_minute": 0.117, "origination_per_min": 0 }, { "id": 12899, "number": "79090160037", "sms_enabled": false, "no_local_cli": false, "channels": 1, "country": "Fake country for 79090160035", "area": "Fake city for 79090160035", "free_minutes": 0, "codec": null, "require_docs": "", "commitment_months": 12, "never_sold": 0, "activation": 1.17, "monthly_fee": 1.17, "per_minute": 0.117, "origination_per_min": 0 } ], "warnings": [ { "resource": "did", "identifier": "999999", "code": "not_in_inventory", "message": "is not in your cancelable inventory" } ] } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access denied" } } } }, "422": { "description": "returns unprocessable entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "none of the requested numbers were found among your cancelable purchases" ] } } } } } } } }, "/api/v2/numbers/risk_checks": { "get": { "summary": "List risk checks", "description": "Retrieves a list of risk check tasks.\n\nReturns information about all risk check tasks created by your organization,\nincluding task status, number counts, and processing timestamps. Supports filtering by various criteria and pagination.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Risk Checks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "task_ids", "in": "query", "required": false, "schema": { "type": "string" }, "example": "15,16", "description": "Filter tasks by task IDs (comma-separated)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "example": "completed,pending,failed", "description": "Filter by status" }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-15", "description": "Filter created from this date (YYYY-MM-DD)" }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-17", "description": "Filter created until this date (YYYY-MM-DD)" }, { "name": "processed_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-15", "description": "Filter processed from this date (YYYY-MM-DD)" }, { "name": "processed_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-17", "description": "Filter processed until this date (YYYY-MM-DD)" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "created_at", "description": "Field to sort by" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc", "description": "Sort order" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1, "description": "Page number for pagination (starts from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 10, "description": "Number of items per page" } ], "responses": { "200": { "description": "returns risk check tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 8, "description": "Task identifier" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "example": "pending", "description": "Task status" }, "total_numbers": { "type": "integer", "example": 1, "description": "Total numbers in the task" }, "completed_count": { "type": "integer", "example": 0, "description": "Number of completed checks" }, "failed_count": { "type": "integer", "example": 0, "description": "Number of failed checks" }, "pending_count": { "type": "integer", "example": 1, "description": "Number of pending checks" }, "processed_at": { "type": "string", "example": "2026-04-16T09:28:16Z", "description": "Processing completion timestamp" }, "created_at": { "type": "string", "example": "2026-04-16T09:28:16Z", "description": "Task creation timestamp" } }, "required": [ "id", "status", "total_numbers", "completed_count", "failed_count", "pending_count", "processed_at", "created_at" ] }, "description": "List of risk check tasks" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 2, "description": "Total number of items" }, "total_pages": { "type": "integer", "example": 1, "description": "Total number of pages" }, "current_page": { "type": "integer", "example": 1, "description": "Current page number" }, "per_page": { "type": "integer", "example": 10, "description": "Items per page" } }, "required": [ "total", "total_pages", "current_page", "per_page" ], "description": "Pagination metadata" } }, "required": [ "tasks", "pagination" ] }, "example": { "tasks": [ { "id": 8, "status": "pending", "processed_at": "2026-04-16T09:28:16Z", "created_at": "2026-04-16T09:28:16Z", "total_numbers": 1, "completed_count": 0, "failed_count": 0, "pending_count": 1 }, { "id": 7, "status": "completed", "processed_at": "2026-04-16T09:28:16Z", "created_at": "2026-04-16T09:28:16Z", "total_numbers": 5, "completed_count": 5, "failed_count": 0, "pending_count": 0 } ], "pagination": { "total": 2, "total_pages": 1, "current_page": 1, "per_page": 10 } } } } }, "401": { "description": "returns unauthorized for without authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden for without access to risk checks", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access to API V2 risk checks is forbidden" } } } } } }, "post": { "summary": "Create risk check", "description": "Creates a new risk check task for the provided phone numbers (maximum 1500 numbers per request).\n\nUse the returned task ID to check the status and retrieve results via the tasks and logs endpoints.\n\n**Note:** Results are informational only. Use at your own discretion.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Risk Checks" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "type": "string" }, "description": "Array of phone numbers to check for risk", "example": [ "79991234567", "79991234568" ] } } } } } }, "responses": { "201": { "description": "returns created risk check task", "content": { "application/json": { "schema": { "type": "object", "properties": { "risk_check_request": { "type": "object", "properties": { "task_id": { "type": "integer", "example": 19, "description": "Task identifier" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "example": "pending", "description": "Task status" }, "total_numbers": { "type": "integer", "example": 2, "description": "Total numbers in the request" }, "processed_at": { "nullable": true, "description": "Processing completion timestamp" }, "created_at": { "type": "string", "example": "2026-04-16T09:28:20Z", "description": "Task creation timestamp" } }, "required": [ "task_id", "status", "total_numbers", "processed_at", "created_at" ], "description": "Created risk check task details" } }, "required": [ "risk_check_request" ] }, "example": { "risk_check_request": { "task_id": 19, "status": "pending", "total_numbers": 2, "processed_at": null, "created_at": "2026-04-16T09:28:20Z" } } } } }, "401": { "description": "returns unauthorized for without authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden for without access to risk checks", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access to API V2 risk checks is forbidden" } } } }, "422": { "description": "returns unprocessable entity when another risk check is already running", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "oneOf": [ { "type": "object", "properties": { "errors": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "type": "string" } } }, "required": [ "numbers" ] } }, "required": [ "errors" ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] } ] }, "examples": { "returns_unprocessable_entity_for_empty_numbers": { "summary": "returns unprocessable entity for empty numbers", "value": { "errors": { "numbers": [ "Required" ] } } }, "returns_unprocessable_entity_when_another_risk_check_is_already_running": { "summary": "returns unprocessable entity when another risk check is already running", "value": { "error": "Previous check is still in progress" } } } } } } } } }, "/api/v2/numbers/risk_checks/logs": { "get": { "summary": "List risk check logs", "description": "Retrieves risk check logs for individual phone numbers.\n\nReturns detailed information about each number that was checked, including its risk level,\nstatus, and processing time. Supports filtering by various criteria and pagination.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Risk Checks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "type": "string" }, "example": "9,10", "description": "Filter logs by log IDs (comma-separated)" }, { "name": "task_ids", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 5, "description": "Filter logs by task IDs (comma-separated)" }, { "name": "number", "in": "query", "required": false, "schema": { "type": "string" }, "example": "79991234567,79991234568", "description": "Filter logs by specific phone numbers (comma-separated)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "example": "completed,pending,failed", "description": "Filter by status" }, { "name": "risk_level", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Low", "High" ] }, "example": "High,Low", "description": "Filter logs by risk level" }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-15", "description": "Filter created from this date (YYYY-MM-DD)" }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-17", "description": "Filter created until this date (YYYY-MM-DD)" }, { "name": "processed_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-15", "description": "Filter processed from this date (YYYY-MM-DD)" }, { "name": "processed_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-17", "description": "Filter processed until this date (YYYY-MM-DD)" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "created_at", "description": "Field to sort by" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc", "description": "Sort order" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1, "description": "Page number for pagination (starts from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 10, "description": "Number of items per page" } ], "responses": { "200": { "description": "returns risk check logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2, "description": "Log identifier" }, "number": { "type": "string", "example": "79991234568", "description": "Phone number that was checked" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "example": "completed", "description": "Check status" }, "risk_level": { "type": "string", "enum": [ "Low", "High" ], "example": "Low", "description": "Risk assessment level" }, "category": { "nullable": true, "description": "Risk category" }, "task_id": { "type": "integer", "example": 1, "description": "Parent task identifier" }, "processed_at": { "type": "string", "example": "2026-04-16T09:28:07Z", "description": "Processing completion timestamp" }, "created_at": { "type": "string", "example": "2026-04-16T09:28:07Z", "description": "Log creation timestamp" } }, "required": [ "id", "number", "status", "risk_level", "category", "task_id", "processed_at", "created_at" ] }, "description": "List of risk check logs" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 2, "description": "Total number of items" }, "total_pages": { "type": "integer", "example": 1, "description": "Total number of pages" }, "current_page": { "type": "integer", "example": 1, "description": "Current page number" }, "per_page": { "type": "integer", "example": 10, "description": "Items per page" } }, "required": [ "total", "total_pages", "current_page", "per_page" ], "description": "Pagination metadata" } }, "required": [ "logs", "pagination" ] }, "example": { "logs": [ { "id": 2, "number": "79991234568", "status": "completed", "risk_level": "Low", "category": null, "task_id": 1, "processed_at": "2026-04-16T09:28:07Z", "created_at": "2026-04-16T09:28:07Z" }, { "id": 1, "number": "79991234567", "status": "completed", "risk_level": "High", "category": "SPAMMER", "task_id": 1, "processed_at": "2026-04-16T09:28:07Z", "created_at": "2026-04-16T09:28:07Z" } ], "pagination": { "total": 2, "total_pages": 1, "current_page": 1, "per_page": 10 } } } } }, "401": { "description": "returns unauthorized for without authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden for without access to risk checks", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access to API V2 risk checks is forbidden" } } } } } } }, "/api/v2/hlr": { "post": { "summary": "Create HLR lookup", "description": "Submits phone numbers for an HLR (Home Location Register) lookup\n(maximum 1500 numbers per request).\n\nNumbers must be supplied in **E.164 format** (e.g. `+14155552671`); a leading `+`\nis added automatically when omitted.\n\nA single number resolves synchronously; larger batches are processed asynchronously — poll\nthe history endpoint (`GET /api/v2/hlr/history`) for results. Lookups are performed\nindependently of call setup and do not affect PDD. Results are not cached: each request\nre-queries the provider.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "HLR Lookups" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "type": "string" }, "description": "Array of phone numbers in E.164 format (e.g. +14155552671)", "example": [ "12125551234" ] } } } } } }, "responses": { "201": { "description": "returns the created HLR lookup task", "content": { "application/json": { "schema": { "type": "object", "properties": { "hlr_request": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "example": "pending", "description": "Task status" }, "processed_at": { "nullable": true, "description": "Processing completion timestamp" }, "created_at": { "type": "string", "example": "2026-06-18T07:29:01Z", "description": "Task creation timestamp" }, "task_id": { "type": "integer", "example": 51, "description": "Task identifier" }, "total_numbers": { "type": "integer", "example": 2, "description": "Total numbers in the request" } }, "required": [ "status", "processed_at", "created_at", "task_id", "total_numbers" ], "description": "Created HLR lookup task details" } }, "required": [ "hlr_request" ] }, "example": { "hlr_request": { "status": "pending", "processed_at": null, "created_at": "2026-06-18T07:29:01Z", "task_id": 51, "total_numbers": 2 } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access to API V2 HLR is forbidden" } } } }, "422": { "description": "returns unprocessable entity for validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "examples": { "returns_unprocessable_entity": { "summary": "returns unprocessable entity", "value": { "error": "Previous check is still in progress" } }, "returns_unprocessable_entity_for_validation_errors": { "summary": "returns unprocessable entity for validation errors", "value": { "error": "No phone numbers provided" } }, "returns_unprocessable_entity_for_validation_errors_3": { "summary": "returns unprocessable entity for validation errors", "value": { "error": "Phone number is too long (max 50 characters)" } } } } } } } } }, "/api/v2/hlr/history": { "get": { "summary": "List HLR lookup history", "description": "Returns the caller's HLR lookup logs — one per number checked — with the lookup result\n(validity, carrier, MCC/MNC, phone type, ported and risky flags, country). Supports\nfiltering by number prefix, status, and date ranges, plus pagination.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "HLR Lookups" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter logs by log IDs (comma-separated)" }, { "name": "task_ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter logs by task IDs (comma-separated)" }, { "name": "number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter logs by specific phone numbers (comma-separated)" }, { "name": "number_start", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1212, "description": "Filter logs by phone-number prefix (starts-with)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "example": "completed,pending,failed", "description": "Filter by status" }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-06-17", "description": "Filter created from this date (YYYY-MM-DD)" }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-06-19", "description": "Filter created until this date (YYYY-MM-DD)" }, { "name": "processed_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter processed from this date (YYYY-MM-DD)" }, { "name": "processed_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter processed until this date (YYYY-MM-DD)" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "created_at", "description": "Field to sort by" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc", "description": "Sort order" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1, "description": "Page number for pagination (starts from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 10, "description": "Number of items per page" } ], "responses": { "200": { "description": "returns the caller HLR logs filtered by number prefix", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 57, "description": "Log identifier" }, "number": { "type": "string", "example": "12125551234", "description": "Phone number that was checked" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "example": "completed", "description": "Lookup status" }, "phone_type": { "type": "string", "example": "mobile", "description": "Line type (e.g. mobile, fixed)" }, "carrier": { "type": "string", "example": "Acme Telecom", "description": "Carrier / operator name" }, "mcc": { "type": "string", "example": "310", "description": "Mobile Country Code" }, "mnc": { "type": "string", "example": "260", "description": "Mobile Network Code" }, "ported": { "type": "boolean", "description": "Whether the number was ported" }, "risky": { "type": "boolean", "description": "Whether the destination is flagged risky" }, "country": { "type": "string", "example": "US", "description": "Country" }, "task_id": { "type": "integer", "example": 45, "description": "Parent task identifier" }, "processed_at": { "type": "string", "example": "2026-06-18T07:29:00Z", "description": "Processing completion timestamp" }, "created_at": { "type": "string", "example": "2026-06-18T07:29:00Z", "description": "Log creation timestamp" }, "valid": { "type": "boolean", "example": true, "description": "Whether the number is valid" }, "price": { "type": "string", "example": "0.07", "description": "Client price charged for this lookup (USD)" }, "error_code": { "nullable": true, "enum": [ "000", "113", "121", "199" ], "description": "Normalized lookup error code: 000 — OK, 113 — Internal service error, 121 — Invalid phone number length or format, 199 — Unexpected error. null when no result is available yet.", "type": "string" } }, "required": [ "id", "number", "status", "phone_type", "carrier", "mcc", "mnc", "ported", "risky", "country", "task_id", "processed_at", "created_at", "valid", "price", "error_code" ] }, "description": "List of HLR lookup logs" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 1, "description": "Total number of items" }, "total_pages": { "type": "integer", "example": 1, "description": "Total number of pages" }, "current_page": { "type": "integer", "example": 1, "description": "Current page number" }, "per_page": { "type": "integer", "example": 10, "description": "Items per page" } }, "required": [ "total", "total_pages", "current_page", "per_page" ], "description": "Pagination metadata" } }, "required": [ "logs", "pagination" ] }, "example": { "logs": [ { "id": 57, "number": "12125551234", "status": "completed", "phone_type": "mobile", "carrier": "Acme Telecom", "mcc": "310", "mnc": "260", "ported": false, "risky": false, "country": "US", "task_id": 45, "processed_at": "2026-06-18T07:29:00Z", "created_at": "2026-06-18T07:29:00Z", "valid": true, "price": "0.07", "error_code": null } ], "pagination": { "total": 1, "total_pages": 1, "current_page": 1, "per_page": 10 } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "403": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Access to API V2 HLR is forbidden" } } } } } } }, "/api/v2/documents": { "get": { "summary": "List documents", "description": "Retrieve a list of documents with filtering and pagination.\n\n**Important notes:**\n- Supports filtering by approval status, identity ID, and date range\n- Results can be sorted and paginated\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1022,1023", "description": "Filter documents by IDs (comma-separated)" }, { "name": "identity_id", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1134, "description": "Filter documents by identity ID" }, { "name": "approvement_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "example": "approved", "description": "Filter documents by approval status" }, { "name": "upload_date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-09T11:11:13Z", "description": "Filter documents created from this date" }, { "name": "upload_date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-11T11:11:13Z", "description": "Filter documents created until this date" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "created_at", "description": "Field to sort by" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "asc", "description": "Sort order" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1, "description": "Page number for pagination (starts from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 10, "description": "Number of items per page" } ], "responses": { "200": { "description": "returns documents from specified identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Document 1", "description": "Document name" }, "id": { "type": "integer", "example": 1016, "description": "Document identifier" }, "user_id": { "type": "integer", "example": 15374, "description": "Owner user ID" }, "country": { "type": "string", "example": "US", "description": "Country code" }, "created_at": { "type": "string", "example": "2026-04-10T11:11:13Z", "description": "Upload timestamp" }, "doc_type": { "type": "string", "enum": [ "Personal ID", "Proof of address" ], "example": "Proof of address", "description": "Document type identifier" }, "approvement_status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ], "example": "verified", "description": "Document approval status" }, "identity_id": { "type": "integer", "example": 1132, "description": "Associated identity ID" }, "identity": { "type": "object", "properties": { "id": { "type": "integer", "example": 1132, "description": "Identity identifier" }, "name": { "type": "string", "example": "Paper Box 23", "description": "Identity name" }, "user_id": { "type": "integer", "example": 15374, "description": "Owner user ID" }, "created_at": { "type": "string", "example": "2026-04-10T11:11:13Z", "description": "Identity creation timestamp" }, "persistence_status": { "type": "string", "enum": [ "active", "archived", "active-immortal" ], "example": "active", "description": "Identity persistence status" }, "is_default": { "type": "boolean", "description": "Is default identity flag" } }, "required": [ "id", "name", "user_id", "created_at", "persistence_status", "is_default" ], "description": "Identity details" }, "expired_at": { "type": "string", "example": "2027-04-10T11:11:13Z", "description": "Document expiration timestamp" }, "files": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "frontside", "description": "File role (frontside, backside)" }, "label": { "type": "string", "example": "File", "description": "File label" }, "url": { "type": "string", "example": "/api/v2/documents/1016/files/frontside", "description": "File download URL" }, "name": { "type": "string", "example": "test.png", "description": "Original file name" } }, "required": [ "role", "label", "url", "name" ] }, "description": "Document files" } }, "required": [ "name", "id", "user_id", "country", "created_at", "doc_type", "approvement_status", "identity_id", "identity", "expired_at", "files" ] }, "description": "List of documents" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 2, "description": "Total number of items" }, "total_pages": { "type": "integer", "example": 1, "description": "Total number of pages" }, "current_page": { "type": "integer", "example": 1, "description": "Current page number" }, "per_page": { "type": "integer", "example": 10, "description": "Items per page" } }, "required": [ "total", "total_pages", "current_page", "per_page" ], "description": "Pagination metadata" } }, "required": [ "documents", "pagination" ] }, "example": { "documents": [ { "name": "Document 1", "id": 1016, "user_id": 15374, "country": "US", "created_at": "2026-04-10T11:11:13Z", "expired_at": "2027-04-10T11:11:13Z", "approvement_status": "verified", "doc_type": "Proof of address", "identity_id": 1132, "identity": { "id": 1132, "name": "Paper Box 23", "user_id": 15374, "created_at": "2026-04-10T11:11:13Z", "persistence_status": "active", "is_default": false }, "files": [ { "role": "frontside", "label": "File", "url": "/api/v2/documents/1016/files/frontside", "name": "test.png" } ] }, { "name": "Document 2", "id": 1017, "user_id": 15374, "country": "US", "created_at": "2026-04-10T11:11:13Z", "expired_at": "2027-04-10T11:11:13Z", "approvement_status": "verified", "doc_type": "Proof of address", "identity_id": 1132, "identity": { "id": 1132, "name": "Paper Box 23", "user_id": 15374, "created_at": "2026-04-10T11:11:13Z", "persistence_status": "active", "is_default": false }, "files": [ { "role": "frontside", "label": "File", "url": "/api/v2/documents/1017/files/frontside", "name": "test.png" } ] } ], "pagination": { "total": 2, "total_pages": 1, "current_page": 1, "per_page": 10 } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } } }, "post": { "summary": "Upload document", "description": "Upload a new document for identity verification.\n\n**Document Types:**\n- `personal_id` - Personal ID\n- `address_proof` - Proof of address\n\n**File Requirements:**\n- Allowed extensions: jpg, jpeg, png, pdf\n- Accepted MIME types: [\"image/jpeg\", \"image/png\", \"application/pdf\"]\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document[name]": { "type": "string", "description": "Document name", "example": "Test Document" }, "document[doc_type]": { "type": "string", "description": "Document type", "enum": [ "personal_id", "address_proof" ], "example": "personal_id" }, "document[files][frontside]": { "type": "string", "format": "binary", "description": "Frontside file upload (binary)" }, "document[files][backside]": { "type": "string", "format": "binary", "description": "Backside file upload (binary, Personal ID only)" }, "document[identity_id]": { "type": "integer", "description": "Identity ID to associate the document with", "example": 1093 }, "document[country]": { "type": "string", "description": "Country code (optional)", "example": "UK" } }, "required": [ "document[name]", "document[doc_type]", "document[files][frontside]", "document[identity_id]" ] } } } }, "responses": { "200": { "description": "creates a new document", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Document created", "description": "Success message" }, "document_id": { "type": "integer", "example": 977, "description": "Created document ID" }, "document": { "type": "object", "properties": { "name": { "type": "string", "example": "Test Document", "description": "Document name" }, "id": { "type": "integer", "example": 977, "description": "Document identifier" }, "user_id": { "type": "integer", "example": 15122, "description": "Owner user ID" }, "country": { "type": "string", "example": "UK", "description": "Country code" }, "created_at": { "type": "string", "example": "2026-04-10T11:10:52Z", "description": "Upload timestamp" }, "doc_type": { "type": "string", "enum": [ "Personal ID", "Proof of address" ], "example": "Personal ID", "description": "Document type identifier" }, "approvement_status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ], "example": "in review", "description": "Document approval status" }, "identity_id": { "type": "integer", "example": 1088, "description": "Associated identity ID" }, "identity": { "type": "object", "properties": { "id": { "type": "integer", "example": 1088, "description": "Identity identifier" }, "name": { "type": "string", "example": "Paper Box 4", "description": "Identity name" }, "user_id": { "type": "integer", "example": 15122, "description": "Owner user ID" }, "created_at": { "type": "string", "example": "2026-04-10T11:10:52Z", "description": "Identity creation timestamp" }, "persistence_status": { "type": "string", "enum": [ "active", "archived", "active-immortal" ], "example": "active", "description": "Identity persistence status" }, "is_default": { "type": "boolean", "description": "Is default identity flag" } }, "required": [ "id", "name", "user_id", "created_at", "persistence_status", "is_default" ], "description": "Identity details" }, "expired_at": { "nullable": true, "description": "Document expiration timestamp" }, "files": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "label": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "label", "url", "name" ] }, "description": "Uploaded document files" } }, "required": [ "name", "id", "user_id", "country", "created_at", "doc_type", "approvement_status", "identity_id", "identity", "expired_at", "files" ], "description": "Created document details" } }, "required": [ "message", "document_id", "document" ] }, "example": { "message": "Document created", "document_id": 977, "document": { "name": "Test Document", "id": 977, "user_id": 15122, "country": "UK", "created_at": "2026-04-10T11:10:52Z", "doc_type": "Personal ID", "approvement_status": "in review", "identity_id": 1088, "identity": { "id": 1088, "name": "Paper Box 4", "user_id": 15122, "created_at": "2026-04-10T11:10:52Z", "persistence_status": "active", "is_default": false }, "expired_at": null, "files": [ { "role": "backside", "label": "Backside", "url": "/api/v2/documents/977/files/backside", "name": "test.png" }, { "role": "backside", "label": "Backside", "url": "/api/v2/documents/977/files/backside", "name": "test.png" } ] } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "422": { "description": "returns unprocessable entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "field_validation": { "summary": "One or more document fields failed validation", "value": { "errors": { "name": [ "Required" ], "country": [ "Is missing" ], "backside": [ "Required" ] } } }, "malformed_document": { "summary": "The document payload is missing or malformed", "value": { "errors": { "document": [ "is missing or malformed" ] } } } }, "example": { "errors": { "name": [ "Required" ], "country": [ "Is missing" ], "backside": [ "Required" ] } } } } } } } }, "/api/v2/documents/{id}": { "put": { "summary": "Update document", "description": "Update an existing document's name or identity.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 988, "description": "Document ID" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document[name]": { "type": "string", "description": "Updated document name", "example": "Updated Name" }, "document[identity_id]": { "type": "integer", "description": "Updated identity ID", "example": 1112 } } } } } }, "responses": { "200": { "description": "updates the document", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Document updated", "description": "Success message" }, "document_id": { "type": "integer" }, "document": { "type": "object", "properties": { "name": { "type": "string", "example": "Updated Name", "description": "Document name" }, "id": { "type": "integer", "example": 984, "description": "Document identifier" }, "user_id": { "type": "integer", "example": 15214, "description": "Owner user ID" }, "country": { "type": "string", "example": "US", "description": "Country code" }, "created_at": { "type": "string", "example": "2026-04-10T11:11:02Z", "description": "Upload timestamp" }, "doc_type": { "type": "string", "enum": [ "Personal ID", "Proof of address" ], "example": "Personal ID", "description": "Document type identifier" }, "approvement_status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ], "example": "in review", "description": "Document approval status" }, "identity_id": { "type": "integer", "example": 1105, "description": "Associated identity ID" }, "identity": { "type": "object", "properties": { "id": { "type": "integer", "example": 1105, "description": "Identity identifier" }, "name": { "type": "string", "example": "New Box", "description": "Identity name" }, "user_id": { "type": "integer", "example": 15214, "description": "Owner user ID" }, "created_at": { "type": "string", "example": "2026-04-10T11:11:02Z", "description": "Identity creation timestamp" }, "persistence_status": { "type": "string", "enum": [ "active", "archived", "active-immortal" ], "example": "active", "description": "Identity persistence status" }, "is_default": { "type": "boolean", "description": "Is default identity flag" } }, "required": [ "id", "name", "user_id", "created_at", "persistence_status", "is_default" ], "description": "Identity details" }, "expired_at": { "type": "string", "example": "2026-04-20T11:11:02Z", "description": "Document expiration timestamp" }, "files": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "label": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "label", "url", "name" ] } } }, "required": [ "name", "id", "user_id", "country", "created_at", "doc_type", "approvement_status", "identity_id", "identity", "expired_at", "files" ], "description": "Updated document details" } }, "required": [ "message", "document_id", "document" ] }, "example": { "message": "Document updated", "document_id": 984, "document": { "name": "Updated Name", "id": 984, "user_id": 15214, "country": "US", "created_at": "2026-04-10T11:11:02Z", "doc_type": "Personal ID", "approvement_status": "in review", "identity_id": 1105, "identity": { "id": 1105, "name": "New Box", "user_id": 15214, "created_at": "2026-04-10T11:11:02Z", "persistence_status": "active", "is_default": false }, "expired_at": "2026-04-20T11:11:02Z", "files": [ { "role": "frontside", "label": "File", "url": "/api/v2/documents/984/files/frontside", "name": "test.png" } ] } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } }, "422": { "description": "returns unprocessable entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "name": [ "Required" ] } } } } } } }, "delete": { "summary": "Delete document", "description": "Delete a document by ID.\n\n**Important notes:**\n- Document is permanently removed\n- Cannot be undone\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1034, "description": "Document ID" } ], "responses": { "204": { "description": "deletes the document" }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } } } }, "get": { "summary": "Get document", "description": "Get a document by ID.\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1028, "description": "Document ID" } ], "responses": { "200": { "description": "returns the document details", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "name": { "type": "string", "example": "Test Document 6b82649a", "description": "Document name" }, "id": { "type": "integer", "example": 1025, "description": "Document identifier" }, "user_id": { "type": "integer" }, "country": { "type": "string" }, "created_at": { "type": "string" }, "doc_type": { "type": "string", "example": "Personal ID", "description": "Document type identifier" }, "approvement_status": { "type": "string", "example": "in review", "description": "Document approval status" }, "identity_id": { "nullable": true }, "identity": { "nullable": true }, "expired_at": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "label": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "label", "url", "name" ] }, "description": "Uploaded document files" } }, "required": [ "name", "id", "user_id", "country", "created_at", "doc_type", "approvement_status", "identity_id", "identity", "expired_at", "files" ] } }, "required": [ "document" ] }, "example": { "document": { "name": "Test Document 6b82649a", "id": 1025, "user_id": 15391, "country": "US", "created_at": "2026-04-10T11:11:14Z", "doc_type": "Personal ID", "approvement_status": "in review", "identity_id": null, "identity": null, "expired_at": "2026-04-20T11:11:14Z", "files": [ { "role": "frontside", "label": "File", "url": "/api/v2/documents/1025/files/frontside", "name": "test.png" } ] } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } } } } }, "/api/v2/documents/countries": { "get": { "summary": "List document countries", "description": "Retrieve a list of countries available for document filtering.\n\n**When to use:**\n- Building country filter dropdown for documents\n- Finding documents by country\n- Searching countries by name pattern\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "name_contains", "in": "query", "required": false, "schema": { "type": "string" }, "example": "land", "description": "Filter countries by name pattern (case-insensitive substring match)" } ], "responses": { "200": { "description": "returns list of countries", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Poland", "description": "Country name" } }, "required": [ "name" ] }, "description": "List of countries available for document filtering" } }, "required": [ "countries" ] }, "example": { "countries": [ { "name": "Poland" } ] } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } } } }, "/api/v2/documents/{id}/files/{role}": { "get": { "summary": "Download document file by role", "description": "Download a specific document file by role (frontside/backside).\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "KYC Documents" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1065, "description": "Document ID" }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "frontside", "backside" ] }, "example": "frontside", "description": "File role" } ], "responses": { "200": { "description": "returns file with proper headers and content", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "base": [ "data not found" ] } } } } } } } }, "/api/v2/identities": { "get": { "summary": "List identities", "description": "Retrieve a list of identities with filtering and pagination.\n\n**Important notes:**\n- Supports filtering by name, IDs, and date range\n- Results can be sorted and paginated\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Identities" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1159,1160", "description": "Filter identities by IDs (comma-separated)" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "example": "box", "description": "Filter identities by name (partial match)" }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-09T11:11:20Z", "description": "Filter identities created from this date (YYYY-MM-DD)" }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-04-11T11:11:20Z", "description": "Filter identities created until this date (YYYY-MM-DD)" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "name", "description": "Field to sort by" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "asc", "description": "Sort order" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1, "description": "Page number for pagination (starts from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 10, "description": "Number of items per page" } ], "responses": { "200": { "description": "returns identities with documents count", "content": { "application/json": { "schema": { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1150, "description": "Identity identifier" }, "name": { "type": "string", "example": "Box 1", "description": "Identity name" }, "user_id": { "type": "integer", "example": 15478, "description": "Owner user ID" }, "created_at": { "type": "string", "example": "2026-04-10T11:11:20Z", "description": "Creation timestamp" }, "persistence_status": { "type": "string" }, "is_default": { "type": "boolean" }, "documents_count": { "type": "integer", "example": 2, "description": "Number of documents in this identity" } }, "required": [ "id", "name", "user_id", "created_at", "persistence_status", "is_default", "documents_count" ] }, "description": "List of identities" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 2, "description": "Total number of items" }, "total_pages": { "type": "integer", "example": 1, "description": "Total number of pages" }, "current_page": { "type": "integer", "example": 1, "description": "Current page number" }, "per_page": { "type": "integer", "example": 10, "description": "Items per page" } }, "required": [ "total", "total_pages", "current_page", "per_page" ], "description": "Pagination metadata" } }, "required": [ "identities", "pagination" ] }, "example": { "identities": [ { "id": 1150, "name": "Box 1", "user_id": 15478, "created_at": "2026-04-10T11:11:20Z", "persistence_status": "active", "is_default": false, "documents_count": 2 }, { "id": 1151, "name": "Box 2", "user_id": 15478, "created_at": "2026-04-10T11:11:20Z", "persistence_status": "active", "is_default": false, "documents_count": 1 } ], "pagination": { "total": 2, "total_pages": 1, "current_page": 1, "per_page": 10 } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } } } }, "post": { "summary": "Create identity", "description": "Create a new identity for document organization.\n\n**Required Fields:**\n- name - Identity name\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Identities" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "identity[name]": { "type": "string", "description": "Identity name", "example": "" } } } } } }, "responses": { "200": { "description": "creates a new identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Identity created", "description": "Success message" }, "identity_id": { "type": "integer", "example": 1099, "description": "Created identity ID" }, "identity": { "type": "object", "properties": { "id": { "type": "integer", "example": 1099, "description": "Identity identifier" }, "name": { "type": "string", "example": "New Box", "description": "Identity name" }, "user_id": { "type": "integer", "example": 15165, "description": "Owner user ID" }, "created_at": { "type": "string" }, "persistence_status": { "type": "string" }, "is_default": { "type": "boolean" }, "documents_count": { "type": "integer" } }, "required": [ "id", "name", "user_id", "created_at", "persistence_status", "is_default", "documents_count" ], "description": "Created identity details" } }, "required": [ "message", "identity_id", "identity" ] }, "example": { "message": "Identity created", "identity_id": 1099, "identity": { "id": 1099, "name": "New Box", "user_id": 15165, "created_at": "2026-04-10T11:10:55Z", "persistence_status": "active", "is_default": false, "documents_count": 0 } } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "422": { "description": "returns unprocessable entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": { "name": [ "Required" ] } } } } } } } }, "/api/v2/identities/{id}": { "delete": { "summary": "Archive identity", "description": "Archive an identity.\n\n**Important notes:**\n- Identity is archived and becomes inactive\n- Cannot delete primary/default identity\n- Associated documents are preserved\n\n**Authentication:**\n- Requires Bearer token in Authorization header: `Authorization: Bearer `\n", "tags": [ "Identities" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1169, "description": "Identity ID" } ], "responses": { "200": { "description": "archives the identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Identity deleted", "description": "Success message" }, "identity_id": { "type": "integer", "example": 1163, "description": "Archived identity ID" } }, "required": [ "message", "identity_id" ] }, "example": { "message": "Identity deleted", "identity_id": 1163 } } } }, "401": { "description": "returns unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "returns not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "data not found" } } } }, "422": { "description": "returns forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Primary identity cannot be archived" ] } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Authenticate API requests via API key like \"Bearer YOUR_TOKEN\"" } }, "schemas": { "Error": { "type": "object", "description": "Standard error response. `errors` maps a field name (or `base` for errors not tied to a specific field) to an array of human-readable messages.", "required": [ "errors" ], "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "base": [ "data not found" ] } } } }, "Warning": { "type": "object", "description": "A non-fatal notice that part of the request was accepted but a specific item was silently skipped. Additive and non-breaking; clients may branch on `code`.", "properties": { "resource": { "type": "string", "description": "Entity kind the warning is about (e.g. \"caller_id\", \"did\").", "example": "caller_id" }, "identifier": { "type": "string", "description": "The value the client sent that was skipped.", "example": "19999999999" }, "code": { "type": "string", "description": "Stable machine-readable token for the reason.", "example": "not_an_owned_or_verified_caller_id" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "is not an owned or verified caller ID and was ignored" } }, "required": [ "resource", "identifier", "code", "message" ] }, "BaseCdr": { "type": "object", "description": "Base call detail record with common fields", "required": [ "timestamp", "type", "amount", "duration", "from", "to" ], "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Call start time in ISO 8601 format (UTC)", "example": "2024-01-15T10:30:00Z" }, "type": { "type": "string", "description": "Call type", "enum": [ "sip", "incoming", "web", "api" ], "example": "sip" }, "amount": { "type": "number", "format": "float", "description": "Call cost (charged/credited amount)", "example": 0.05 }, "duration": { "type": "integer", "description": "Call duration in seconds. 0 = missed call", "minimum": 0, "example": 120 }, "from": { "type": "string", "description": "Caller number/identifier", "example": "100" }, "to": { "type": "string", "description": "Destination number/identifier", "example": "+14155551234" } } }, "SipCdr": { "allOf": [ { "$ref": "#/components/schemas/BaseCdr" }, { "type": "object", "description": "Outbound SIP call detail record", "properties": { "destination_name": { "type": "string", "description": "Destination country/region name", "example": "United States" }, "sip_account": { "type": "string", "nullable": true, "description": "SIP account used for the call", "example": "john@sip.provider.com" }, "per_minute": { "type": "number", "format": "float", "nullable": true, "description": "Per-minute rate. null = unknown, 0 = free", "example": 0.025 } } } ] }, "IncomingCdr": { "allOf": [ { "$ref": "#/components/schemas/BaseCdr" }, { "type": "object", "description": "Incoming call detail record", "properties": { "did_number": { "type": "string", "nullable": true, "description": "DID number that received the call (purchased virtual number)", "example": "+18005551234" } } } ] }, "WebCdr": { "allOf": [ { "$ref": "#/components/schemas/BaseCdr" }, { "type": "object", "description": "Web call detail record (no additional fields)" } ] }, "CdrListResponse": { "type": "object", "description": "Paginated list of CDR records", "required": [ "calls", "pagination" ], "properties": { "calls": { "type": "array", "description": "Array of call detail records", "items": { "oneOf": [ { "$ref": "#/components/schemas/SipCdr" }, { "$ref": "#/components/schemas/IncomingCdr" }, { "$ref": "#/components/schemas/WebCdr" } ] } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Pagination": { "type": "object", "description": "Pagination metadata for list responses", "required": [ "page", "per_page", "total_pages", "total_records" ], "properties": { "page": { "type": "integer", "description": "Current page number (1-based)", "minimum": 1, "example": 1 }, "per_page": { "type": "integer", "description": "Number of records per page", "minimum": 1, "example": 10 }, "total_pages": { "type": "integer", "description": "Total number of pages available", "minimum": 0, "example": 325 }, "total_records": { "type": "integer", "description": "Total number of records", "minimum": 0, "example": 3248 } } } } }, "tags": [ { "name": "Account Balance", "x-version": "v1" }, { "name": "Calls", "x-version": "v1" }, { "name": "Reports", "x-version": "v1" }, { "name": "Purchases", "x-version": "v1" }, { "name": "Inbound Destinations", "x-version": "v1" }, { "name": "SIP Accounts", "x-version": "v1" }, { "name": "SMS", "x-version": "v1" }, { "name": "Numbers & Inventory", "x-version": "v2" }, { "name": "Risk Checks", "x-version": "v2" }, { "name": "HLR Lookups", "x-version": "v2" }, { "name": "KYC Documents", "x-version": "v2" }, { "name": "Identities", "x-version": "v2" } ] }