{
  "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- **Click2Call:** Place a two-leg callback from your server — we ring one of your SIP accounts, dial the destination, and bridge the two — then follow it by polling or by webhook.\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/capabilities": {
      "get": {
        "summary": "List API capabilities",
        "description": "List the API operations your key may call, and the account it belongs to.\n\nYour account decides which parts of the API are open to it: API v1, buying and\nbrowsing numbers, SIP accounts, Click2Call, call recordings, the ASR report,\nsending SMS, risk checks and HLR lookups. This operation answers for any valid\nkey, whatever is enabled, so it is also the cheapest way to check that a key\nworks.\n\nEach entry is an HTTP method and a path exactly as this reference spells it,\npath parameters included (`/api/v1/sipaccounts/{id}`). An operation missing from\nthe list is refused for your account. Checks that depend on the request itself,\nsuch as the number you ask for or a rate limit, are not reflected here.\n\nThis operation does not list itself. An invalid key gets `401 Unauthorized`.\n",
        "tags": [
          "API Access"
        ],
        "operationId": "capabilities_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the operations open to this key and the account it belongs to",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "capabilities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "method": {
                            "type": "string",
                            "enum": [
                              "GET",
                              "POST",
                              "PUT",
                              "PATCH",
                              "DELETE"
                            ],
                            "example": "GET",
                            "description": "HTTP method of the operation"
                          },
                          "path": {
                            "type": "string",
                            "example": "/api/v1/balance",
                            "description": "Path of the operation as written in this reference, with path parameters"
                          }
                        },
                        "required": [
                          "method",
                          "path"
                        ]
                      },
                      "description": "Operations this key may call"
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 2854,
                          "description": "Account ID"
                        },
                        "email": {
                          "type": "string",
                          "example": "email361@factory361.com",
                          "description": "Account email"
                        }
                      },
                      "required": [
                        "id",
                        "email"
                      ],
                      "description": "The account the key belongs to"
                    }
                  },
                  "required": [
                    "capabilities",
                    "user"
                  ]
                },
                "example": {
                  "capabilities": [
                    {
                      "method": "GET",
                      "path": "/api/v1/balance"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/calls"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/calls/statistics"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/recordings/{user_id}/{token}"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/call_price"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/transactions"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/purchases"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/purchases/{purchase_id}/destinations"
                    },
                    {
                      "method": "POST",
                      "path": "/api/v1/purchases/{purchase_id}/destinations"
                    },
                    {
                      "method": "PATCH",
                      "path": "/api/v1/purchases/{purchase_id}/destinations/{id}"
                    },
                    {
                      "method": "DELETE",
                      "path": "/api/v1/purchases/{purchase_id}/destinations/{id}"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/sipaccounts"
                    },
                    {
                      "method": "POST",
                      "path": "/api/v1/sipaccounts"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/sipaccounts/{id}"
                    },
                    {
                      "method": "PATCH",
                      "path": "/api/v1/sipaccounts/{id}"
                    },
                    {
                      "method": "DELETE",
                      "path": "/api/v1/sipaccounts/{id}"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/sipaccounts/{sipaccount_id}/allowed_ips"
                    },
                    {
                      "method": "POST",
                      "path": "/api/v1/sipaccounts/{sipaccount_id}/allowed_ips"
                    },
                    {
                      "method": "DELETE",
                      "path": "/api/v1/sipaccounts/{sipaccount_id}/allowed_ips"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/sms"
                    },
                    {
                      "method": "POST",
                      "path": "/api/v1/sms"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v1/sms/{id}"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v2/documents"
                    },
                    {
                      "method": "POST",
                      "path": "/api/v2/documents"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v2/documents/countries"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v2/documents/{id}"
                    },
                    {
                      "method": "PUT",
                      "path": "/api/v2/documents/{id}"
                    },
                    {
                      "method": "DELETE",
                      "path": "/api/v2/documents/{id}"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v2/documents/{id}/files/{role}"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v2/identities"
                    },
                    {
                      "method": "POST",
                      "path": "/api/v2/identities"
                    },
                    {
                      "method": "DELETE",
                      "path": "/api/v2/identities/{id}"
                    },
                    {
                      "method": "GET",
                      "path": "/api/v2/numbers"
                    }
                  ],
                  "user": {
                    "id": 2854,
                    "email": "email361@factory361.com"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is not valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          }
        }
      }
    },
    "/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",
        "tags": [
          "Account Balance"
        ],
        "operationId": "balance_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "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"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/calls": {
      "get": {
        "summary": "Retrieve call detail records",
        "operationId": "calls_show",
        "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, SIP account, AMD status and hangup cause\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\nSee also: calls_statistics, totals for the same filters.\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": "amd_status",
            "in": "query",
            "description": "Return only calls with this answering machine detection (AMD) verdict, matched ignoring case:\n- `machine` — AMD detected an answering machine\n- `human` — AMD detected a person\n- `notsure` — AMD ran but could not tell a machine from a person, for example on silence, unclear audio or a timeout\n\nOnly outbound calls carry a verdict, so `type=incoming` with this filter returns no calls.\nA value that no call has returns no calls.\nA malformed value, for example one with `|` or non-ASCII characters, is ignored, as if the parameter were not sent.\n",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "machine"
          },
          {
            "name": "hangup_cause",
            "in": "query",
            "description": "Return only calls that ended this way, matched ignoring case:\n- `AMD_MACHINE` — AMD detected an answering machine; takes precedence over the other values\n- `NORMAL_CLEARING` — the call was answered\n- `NO_ANSWER` — nobody answered, including calls the caller cancelled before an answer\n- `BUSY` — the called party was busy\n- `FAILED` — the call could not be connected\n\nA value that no call has returns no calls.\nA malformed value, for example one with `|` or non-ASCII characters, is ignored, as if the parameter were not sent.\n",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "AMD_MACHINE",
                "NORMAL_CLEARING",
                "NO_ANSWER",
                "BUSY",
                "FAILED"
              ]
            },
            "example": "AMD_MACHINE"
          },
          {
            "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": "SIP account name from sipaccounts_index",
            "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,
                      "amd_status": "machine",
                      "amd_score": 93,
                      "hangup_cause": "AMD_MACHINE"
                    },
                    {
                      "timestamp": "2024-01-15T10:30:00Z",
                      "type": "incoming",
                      "amount": 0.02,
                      "duration": 90,
                      "from": "+14155551234",
                      "to": "100",
                      "did_number": "+18005551234",
                      "amd_status": null,
                      "amd_score": null,
                      "hangup_cause": "NORMAL_CLEARING"
                    },
                    {
                      "timestamp": "2024-01-15T10:35:00Z",
                      "type": "incoming",
                      "amount": 0,
                      "duration": 0,
                      "from": "+14155559999",
                      "to": "100",
                      "did_number": "+18005551234",
                      "amd_status": null,
                      "amd_score": null,
                      "hangup_cause": "NO_ANSWER"
                    },
                    {
                      "timestamp": "2024-01-15T10:30:00Z",
                      "type": "web",
                      "amount": 0.03,
                      "duration": 60,
                      "from": "web_user_123",
                      "to": "+14155551234",
                      "amd_status": null,
                      "amd_score": null,
                      "hangup_cause": "NORMAL_CLEARING"
                    }
                  ],
                  "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, AMD Status, AMD Score, Hangup Cause\n\n`AMD Status` and `AMD Score` are omitted when `type=incoming`. `AMD Status`, `AMD Score` and `Hangup Cause` carry the values of `amd_status`, `amd_score` and `hangup_cause` in the JSON response; an empty cell stands for `null`.\n"
                },
                "example": "Date,Time,SIP ID,Type,From,To,Destination name,Duration,DID inc. fee,Termination,Charge,Balance,AMD Status,AMD Score,Hangup Cause\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,machine,93,AMD_MACHINE\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\nRows: calls_show.\n",
        "tags": [
          "Calls"
        ],
        "operationId": "calls_statistics",
        "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": 39452,
            "description": "SIP account name from sipaccounts_index"
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 1234567890,
            "description": "Search term for filtering calls"
          },
          {
            "name": "amd_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "human",
            "description": "Count only calls with this answering machine detection (AMD) verdict, matched ignoring case:\n- `machine` — AMD detected an answering machine\n- `human` — AMD detected a person\n- `notsure` — AMD ran but could not tell a machine from a person, for example on silence,\n  unclear audio or a timeout\n\nOnly outbound calls carry a verdict, so under this filter the received and missed counts\nand the received total are 0. A value that no call has gives zero counts and totals.\nA malformed value, for example one with `|` or non-ASCII characters, is ignored,\nas if the parameter were not sent.\n"
          },
          {
            "name": "hangup_cause",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "AMD_MACHINE",
                "NORMAL_CLEARING",
                "NO_ANSWER",
                "BUSY",
                "FAILED"
              ]
            },
            "example": "NORMAL_CLEARING",
            "description": "Count only calls that ended this way, matched ignoring case:\n- `AMD_MACHINE` — AMD detected an answering machine; takes precedence over the other values\n- `NORMAL_CLEARING` — the call was answered\n- `NO_ANSWER` — nobody answered, including calls the caller cancelled before an answer\n- `BUSY` — the called party was busy\n- `FAILED` — the call could not be connected\n\nA value that no call has gives zero counts and totals.\nA malformed value, for example one with `|` or non-ASCII characters, is ignored,\nas if the parameter were not sent.\n"
          }
        ],
        "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",
        "tags": [
          "Calls"
        ],
        "operationId": "calls_recording",
        "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/call_price": {
      "get": {
        "summary": "Quote the price of an outbound call",
        "description": "What a call from one of your SIP accounts to `b_number`, presenting `a_number` as the caller ID,\nwill be billed: the destination name, the per-minute price and the billing increment.\n\nThe quote replays what the platform does to the call before it is billed: the SIP account's\ndestination rewrite, its caller-ID restrictions, routing rules and caller-ID overrides. It then\nrates the call with the same code billing uses: exact prices, origin-based rates and markup\nincluded.\n\n**Not modelled:**\n- the carrier (trunk) chosen for the call, which can change the increment and, through the\n  caller ID it presents, the price;\n- blocklists and allowlists: a destination that would be refused is still quoted;\n- where the platform picks a caller ID at random, the first candidate is used.\n\nSend `b_number` in E.164 (country code first). A national number is quoted only when the SIP\naccount has a rewrite rule that turns it into E.164.\n",
        "tags": [
          "Calls"
        ],
        "operationId": "call_price_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "a_number",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "+13125550100"
            },
            "example": "+13125550100",
            "description": "Caller ID the call presents; up to 5 digits means anonymous"
          },
          {
            "name": "b_number",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "+447911123456"
            },
            "example": "+447911123456",
            "description": "Number to call, E.164 (a leading + is accepted)"
          },
          {
            "name": "sipaccount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "100001"
            },
            "example": "100001",
            "description": "SIP account name from sipaccounts_index, the account placing the call"
          }
        ],
        "responses": {
          "200": {
            "description": "The price and increment the call will be billed at",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "destination_name": {
                      "type": "string",
                      "example": "United Kingdom - O2",
                      "nullable": true,
                      "description": "Destination as listed in your price list; null for an exact price only"
                    },
                    "price": {
                      "type": "number",
                      "format": "float",
                      "example": 0.056,
                      "description": "Price per minute in USD"
                    },
                    "increment": {
                      "type": "object",
                      "properties": {
                        "initial": {
                          "type": "integer",
                          "example": 30,
                          "description": "Seconds billed for the first block"
                        },
                        "unit": {
                          "type": "integer",
                          "example": 1,
                          "description": "Seconds per block after the first"
                        }
                      },
                      "required": [
                        "initial",
                        "unit"
                      ]
                    }
                  },
                  "required": [
                    "destination_name",
                    "price",
                    "increment"
                  ]
                },
                "example": {
                  "destination_name": "United Kingdom - O2",
                  "price": 0.056,
                  "increment": {
                    "initial": 30,
                    "unit": 1
                  }
                }
              }
            }
          },
          "404": {
            "description": "No SIP account of yours has that name",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "sipaccount_not_found",
                    "message": "no SIP account with that name",
                    "details": []
                  }
                }
              }
            }
          },
          "422": {
            "description": "The destination has no price for this SIP account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "field": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "field"
                            ]
                          }
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "validation_failed",
                    "message": "The request contains invalid parameters",
                    "details": [
                      {
                        "code": "destination_not_priced",
                        "message": "the destination has no price",
                        "field": "b_number"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/click2call": {
      "post": {
        "summary": "Place a Click2Call call",
        "description": "Places one call: the platform connects the agent leg first and, once it\nanswers, dials the destination number (the customer leg) and bridges the\ntwo. The agent leg is one of your SIP accounts by default, or your own\nWebSocket endpoint with `a_type: stream`.\n\nThe response is the call resource in its initial `accepted` state. Poll\n`GET /api/v1/click2call/{id}` for progress.\n\n> **`a_type: stream` requires an endpoint that speaks our protocol.** The\n> message shapes, the audio format and what answers the call are described in\n> [WebSocket Calls](https://docs.didlogic.com/docs/guides/apps-developer-tools/websocket-calls).\n\n### States\n\n`accepted` → `agent_ringing` → `agent_answered` → `customer_ringing` →\n`bridged` → `completed`, with `failed` reachable from any of them.\n\n> **`agent_ringing` is best-effort.** It is derived from a ringing\n> indication on the agent leg, which some user agents never send, so it may\n> be skipped entirely — a call can go straight from `accepted` to\n> `agent_answered`. Do not require `agent_ringing` in client logic.\n\n### Webhooks\n\nPass `callback_url` and we POST a JSON body to it on every transition of the\ncall. It must be an `https` URL on a public host, at most 255 characters;\nanything else is refused with `422` and no call is placed. Delivery is per\ncall — there is no per-account setting, and calls placed without the field\nget no webhooks.\n\n| Event | Fires when |\n|-------|-----------|\n| `click2call.agent_ringing` | the agent leg starts ringing |\n| `click2call.agent_answered` | the agent leg answers |\n| `click2call.customer_ringing` | the destination is dialled |\n| `click2call.bridged` | the two legs are bridged |\n| `click2call.completed` | the call ends normally |\n| `click2call.failed` | the call ends any other way |\n| `click2call.finalized` | the billed record is committed |\n\nThe body is `{\"event\": …, \"occurred_at\": …, \"event_seq\": …, \"data\": {…}}`,\nwhere `data` is the same call resource this endpoint returns. New fields may\nappear in `data` and new names in the `click2call.*` namespace at any time:\nignore what you do not recognise.\n\n> **`click2call.completed` and `.failed` fire immediately, with `cost` still\n> `null`.** `click2call.finalized` follows once billing has settled and\n> carries the priced document. The two can arrive out of order — `.finalized`\n> does not mean nothing more is coming. Order is recoverable only from\n> `event_seq`, which increases within a call.\n\nRequests are **not signed**. Treat the call id as unguessable, not as proof\nof origin, and confirm anything that matters with\n`GET /api/v1/click2call/{id}`.\n\n**Delivery.** Answer `2xx` within 15 seconds. A `408`, `429`, `5xx` or a\ntransport failure is retried up to five times with exponential backoff from\n30 seconds, honouring `Retry-After`; any other `4xx` is treated as permanent\nand never retried. Delivery is at-least-once, so the same `event_seq` can\narrive twice.\n\n### Recordings\n\n`recording_url` is `null` until the call is settled, and stays `null` for a\ncall that was not recorded. It rides in the same `data` of every\n`click2call.*` webhook, so `click2call.finalized` is where it first appears.\n\n**Default.** `recording_url` is a signed S3 link valid for 1 hour. Each read\nof the call (click2call_show) mints a fresh one. Once it has expired, fetch\nthe file through calls_recording.\n\n**Permanent links.** Enabled on request through your account manager or\nsupport. `recording_url` becomes `/api/v1/recordings/{user_id}/{token}`,\nwhich needs no authentication and answers `302` to a signed URL valid for\n5 minutes, `404` when the recording is no longer retained or the option is\nturned off, and `429` with `Retry-After` past the per-minute download limit.\nDetails: recordings_show.\n\n### Caller ID\n\nWhile the agent's phone rings it shows the destination number as the\ncaller. Pass `a_cli` to show a number of your choice instead — for example\nwhen your agents must not see where the call is going. It is an E.164\nnumber of at most 15 digits, with or without the leading `+`; if the field\nis present at all it must be one, and anything else — including `null` or\nan empty string — is refused with `422 invalid_a_cli` and **no call is\nplaced**, so the destination is never shown by accident. `a_cli` does not\nchange the caller ID the destination sees.\n\n`b_cli` is not supported in v1: sending it is refused with `422\ncaller_id_unsupported` and **no call is placed**. The caller ID presented on\nthe customer leg is the one configured for your account.\n\n### Refusals\n\n`403` means the account may not use this endpoint at all —\n`click2call_api_disabled` or `account_not_verified`. `409` means the account\nis in a state that forbids placing a call — `account_suspended`. `402` means\nthe call cannot be paid for — `insufficient_funds`. `422` means the request\nitself was refused, and every violation is listed in `error.details`. In every\ncase no call is placed and nothing is charged.\n\n`data.id` feeds click2call_show and click2call_destroy. `data.recording_url` feeds recordings_show.\n",
        "tags": [
          "Click2Call"
        ],
        "operationId": "click2call_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "a_type": {
                    "type": "string",
                    "description": "Type of the agent leg. `sip_account` rings one of your SIP accounts; `stream` connects your own WebSocket endpoint first, where the account allows it.",
                    "enum": [
                      "sip_account",
                      "stream"
                    ]
                  },
                  "a_endpoint": {
                    "type": "string",
                    "description": "For `sip_account`, the five-digit SIP account name from sipaccounts_index to ring first. For `stream`, the public `wss://` URL of your endpoint, at most 2048 characters, dialled exactly as given. Your endpoint is sent `start` as soon as the socket opens and the leg is answered; the destination is dialled after that, and its pickup arrives as `answered`."
                  },
                  "b_number": {
                    "type": "string",
                    "description": "Destination number in E.164, with or without the leading `+`."
                  },
                  "callback_url": {
                    "type": "string",
                    "description": "Optional `https` URL on a public host, at most 255 characters. Every transition of this call is POSTed to it — see the description above."
                  },
                  "client_call_id": {
                    "type": "string",
                    "description": "Optional label of your own, echoed back on every surface that reports this call. At most 64 characters of `A-Z`, `a-z`, `0-9`, `_` or `-`. Not checked for uniqueness and never used to address the call."
                  },
                  "a_cli": {
                    "type": "string",
                    "description": "Optional caller ID shown on the agent leg instead of `b_number`: E.164, at most 15 digits, with or without the leading `+`. When present it must be valid — `null` or an empty string is refused, never ignored."
                  }
                },
                "required": [
                  "a_type",
                  "a_endpoint",
                  "b_number",
                  "callback_url",
                  "client_call_id"
                ]
              },
              "example": {
                "a_type": "sip_account",
                "a_endpoint": "10001",
                "b_number": "+447700900000",
                "callback_url": "https://hooks.example.com/didlogic",
                "client_call_id": "order-42_ABC",
                "a_cli": "+442071234567"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The call was placed. Poll the read operation for progress.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "01K0SPIKE0000000000000002A",
                          "description": "Call ID (26-character ULID). Use it for the read and cancel operations."
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "accepted",
                            "agent_ringing",
                            "agent_answered",
                            "customer_ringing",
                            "bridged",
                            "completed",
                            "failed"
                          ],
                          "example": "accepted",
                          "description": "How far the call has got. `agent_ringing` may be skipped — see the description above."
                        },
                        "reason": {
                          "nullable": true,
                          "type": "string",
                          "enum": [
                            "no_answer",
                            "busy",
                            "unreachable",
                            "canceled",
                            "timed_out",
                            "platform_error"
                          ],
                          "description": "Why the call ended. `null` while the call is live and on a normal end."
                        },
                        "a_type": {
                          "type": "string",
                          "example": "sip_account",
                          "description": "Type of the agent leg: `sip_account` or `stream`."
                        },
                        "a_endpoint": {
                          "type": "string",
                          "example": "10001",
                          "description": "The SIP account that was rung first, or for `stream` the endpoint URL exactly as you supplied it"
                        },
                        "b_number": {
                          "type": "string",
                          "example": "447700900000",
                          "description": "Destination number, digits only"
                        },
                        "b_cli": {
                          "nullable": true,
                          "type": "string",
                          "description": "Always `null` in v1"
                        },
                        "created_at": {
                          "type": "string",
                          "example": "2026-07-31T10:00:00.000Z",
                          "description": "When the call was placed. The 12-hour retention window runs from here."
                        },
                        "agent_ringing_at": {
                          "nullable": true,
                          "type": "string",
                          "description": "When the agent leg started ringing. Best-effort: `null` when the phone never reported the ring, not only when it never rang."
                        },
                        "agent_answered_at": {
                          "nullable": true,
                          "type": "string",
                          "description": "When the agent leg answered"
                        },
                        "customer_ringing_at": {
                          "nullable": true,
                          "type": "string",
                          "description": "When the destination was dialled"
                        },
                        "bridged_at": {
                          "nullable": true,
                          "type": "string",
                          "description": "When the two legs were bridged"
                        },
                        "ended_at": {
                          "nullable": true,
                          "type": "string",
                          "description": "When the call ended"
                        },
                        "duration": {
                          "nullable": true,
                          "type": "integer",
                          "description": "Whole life of the call in seconds, ringing included. Not the billed time."
                        },
                        "cost": {
                          "nullable": true,
                          "type": "string",
                          "description": "Total cost in dollars, four decimals"
                        },
                        "finalized_at": {
                          "nullable": true,
                          "type": "string",
                          "description": "When the billed record was committed. `null` until then, and until it is set `cost` may still be `null`."
                        },
                        "recording_url": {
                          "nullable": true,
                          "type": "string",
                          "description": "Where the recording of the call can be downloaded. `null` when the call was not recorded, and `null` on a call that has not settled yet. By default the link is signed and expires one hour after it was minted; each read of the call mints a fresh one, and `GET /api/v1/calls/recording/{callid}` also gives one. If the account has permanent recording links enabled (on request through your account manager or support), the field holds a permanent `/api/v1/recordings/{user_id}/{token}` URL instead. It does not expire while the recording is retained and the option stays on."
                        },
                        "client_call_id": {
                          "type": "string",
                          "example": "order-42_ABC",
                          "nullable": true,
                          "description": "The label you supplied when placing the call, echoed back unchanged. `null` when none was supplied. Carried on every webhook for this call."
                        },
                        "a_cli": {
                          "type": "string",
                          "example": "442071234567",
                          "nullable": true,
                          "description": "The caller ID the agent leg was presented with, digits only: the `a_cli` you supplied, or `b_number` when you supplied none. Carried on every webhook for this call."
                        }
                      },
                      "required": [
                        "id",
                        "state",
                        "reason",
                        "a_type",
                        "a_endpoint",
                        "b_number",
                        "b_cli",
                        "created_at",
                        "agent_ringing_at",
                        "agent_answered_at",
                        "customer_ringing_at",
                        "bridged_at",
                        "ended_at",
                        "duration",
                        "cost",
                        "finalized_at",
                        "recording_url",
                        "client_call_id",
                        "a_cli"
                      ],
                      "description": "The Click2Call call resource"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "01K0SPIKE0000000000000002A",
                    "state": "accepted",
                    "reason": null,
                    "a_type": "sip_account",
                    "a_endpoint": "10001",
                    "b_number": "447700900000",
                    "b_cli": null,
                    "created_at": "2026-07-31T10:00:00.000Z",
                    "agent_ringing_at": null,
                    "agent_answered_at": null,
                    "customer_ringing_at": null,
                    "bridged_at": null,
                    "ended_at": null,
                    "duration": null,
                    "cost": null,
                    "finalized_at": null,
                    "recording_url": null,
                    "client_call_id": "order-42_ABC",
                    "a_cli": "442071234567"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The API token is missing or incorrect. This endpoint answers `401`; the rest of v1 answers `403` for the same refusal.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "402": {
            "description": "The account has no funds available — `insufficient_funds`. The request was well formed and permitted; it simply cannot be paid for. No call is placed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "insufficient_funds",
                    "message": "the account has no funds available",
                    "details": []
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account may not use this endpoint: the request is refused with `click2call_api_disabled` or `account_not_verified`. No call is placed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "examples": {
                  "Account not verified": {
                    "value": {
                      "error": {
                        "code": "account_not_verified",
                        "message": "the account has not been verified yet",
                        "details": []
                      }
                    }
                  },
                  "Click2Call API disabled": {
                    "value": {
                      "error": {
                        "code": "click2call_api_disabled",
                        "message": "the Click2Call API is not enabled for this account",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The account is in a state that forbids placing a call — `account_suspended`. The request itself was well formed and permitted; no call is placed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "account_suspended",
                    "message": "the account is suspended",
                    "details": []
                  }
                }
              }
            }
          },
          "422": {
            "description": "The request failed validation. `error.code` is always `validation_failed`; each violation appears in `error.details` with its own `code` and the `field` it belongs to — `caller_id_unsupported` (`b_cli` is not supported in v1), `a_type_unsupported`, `invalid_a_endpoint`, `invalid_stream_url`, `invalid_stream_token`, `unknown_sip_account`, `invalid_b_number`, `invalid_a_cli`, `callback_url_insecure`, `invalid_callback_url` or `invalid_client_call_id`. No call is placed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "field": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "field"
                            ]
                          }
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "examples": {
                  "Agent leg type unsupported (stream not enabled)": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "a_type_unsupported",
                            "message": "a_type must be sip_account",
                            "field": "a_type"
                          }
                        ]
                      }
                    }
                  },
                  "Agent leg type unsupported": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "a_type_unsupported",
                            "message": "a_type must be sip_account",
                            "field": "a_type"
                          }
                        ]
                      }
                    }
                  },
                  "Callback URL not https": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "callback_url_insecure",
                            "message": "callback_url must use https",
                            "field": "callback_url"
                          }
                        ]
                      }
                    }
                  },
                  "Caller ID unsupported": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "caller_id_unsupported",
                            "message": "a caller ID for the destination leg is not supported yet",
                            "field": "b_cli"
                          }
                        ]
                      }
                    }
                  },
                  "Agent caller ID invalid": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "invalid_a_cli",
                            "message": "a_cli must be an E.164 number of at most 15 digits",
                            "field": "a_cli"
                          }
                        ]
                      }
                    }
                  },
                  "Agent leg unknown": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "invalid_a_endpoint",
                            "message": "a_endpoint must be a five-digit SIP account",
                            "field": "a_endpoint"
                          }
                        ]
                      }
                    }
                  },
                  "Callback URL invalid": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "invalid_callback_url",
                            "message": "callback_url must be a public https URL of at most 255 characters",
                            "field": "callback_url"
                          }
                        ]
                      }
                    }
                  },
                  "Client call id invalid": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "invalid_client_call_id",
                            "message": "client_call_id must be 1 to 64 characters of A-Z, a-z, 0-9, underscore or hyphen",
                            "field": "client_call_id"
                          }
                        ]
                      }
                    }
                  },
                  "Rejected by the call platform": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "invalid_sip_account",
                            "message": "a_endpoint must be a five-digit SIP account",
                            "field": null
                          }
                        ]
                      }
                    }
                  },
                  "Stream token invalid": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "invalid_stream_token",
                            "message": "stream_token must be 1 to 512 printable characters without spaces",
                            "field": "stream_token"
                          }
                        ]
                      }
                    }
                  },
                  "Stream URL invalid": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "invalid_stream_url",
                            "message": "a_endpoint must be a public wss:// URL of at most 2048 characters",
                            "field": "a_endpoint"
                          }
                        ]
                      }
                    }
                  },
                  "Stream SIP account missing": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "unknown_sip_account",
                            "message": "sip_account must be one of your five-digit SIP accounts",
                            "field": "sip_account"
                          }
                        ]
                      }
                    }
                  },
                  "Stream SIP account unknown": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The request contains invalid parameters",
                        "details": [
                          {
                            "code": "unknown_sip_account",
                            "message": "sip_account must be one of your five-digit SIP accounts",
                            "field": "sip_account"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/click2call/{id}": {
      "get": {
        "summary": "Read a Click2Call call",
        "description": "Returns the current state of one call. This is the polling endpoint: call it\nuntil `state` is `completed` or `failed`.\n\n### States\n\n| State | Meaning |\n|---|---|\n| `accepted` | The call was placed; no leg has moved yet |\n| `agent_ringing` | Your SIP account is ringing — **best-effort, may be skipped** |\n| `agent_answered` | Your SIP account answered |\n| `customer_ringing` | The destination is being dialled |\n| `bridged` | Both legs are up and talking |\n| `completed` | The call ended normally |\n| `failed` | The call did not come together |\n\n`agent_ringing` is derived from a ringing indication on the agent leg, which\nsome user agents never send. A call may therefore go straight from\n`accepted` to `agent_answered`; clients must not require `agent_ringing`.\n\n### `reason`\n\n`reason` answers *why the call ended*, on its own axis from `state`. It is\n`null` while the call is live **and** on a normal end. Otherwise it is one\nof `no_answer`, `busy`, `unreachable`, `canceled`, `timed_out` or\n`platform_error`. A call your own `DELETE` ended reports `canceled` —\nincluding when it had already been answered, in which case `state` is\n`completed`. A `DELETE` that arrives after the call has already ended leaves\nthe original reason in place.\n\n### Retention\n\nA call is readable for **12 hours from the moment it was placed** — not from\nthe moment it ended. After that the record is gone and this endpoint answers\n`404`. Call history is a separate product surface.\n\n### Recordings\n\n`recording_url` is `null` until the call is settled, and stays `null` for a\ncall that was not recorded.\n\n**Default.** `recording_url` is a signed S3 link valid for 1 hour, minted\nfresh on each read. Once it has expired, fetch the file through\ncalls_recording.\n\n**Permanent links.** Enabled on request through your account manager or\nsupport. `recording_url` becomes `/api/v1/recordings/{user_id}/{token}`,\nwhich needs no authentication and answers `302` to a signed URL valid for\n5 minutes. It answers `404` when the recording is no longer retained or the\noption is turned off, and `429` with `Retry-After` past the per-minute\ndownload limit. Details: recordings_show.\n\nThis link is the `recording_url` returned by click2call_create,\nclick2call_show and their `click2call.*` webhooks, and sent in the\ncall-recording webhook. Without permanent links enabled, `recording_url`\nholds a temporary pre-signed URL; to fetch a recording after it expires,\nuse calls_recording.\n\n### `404`\n\n`404 call_not_found` means the call is unknown to you: it never existed, the\nID is malformed, it belongs to another account, or it has fallen out of the\n12-hour window. The cases are deliberately indistinguishable.\n\n`data.recording_url` feeds recordings_show. See also: click2call_destroy.\n",
        "tags": [
          "Click2Call"
        ],
        "operationId": "click2call_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01K0SPIKE0000000000000002A",
            "description": "Call ID (`data.id`) from click2call_create, a 26-character ULID"
          }
        ],
        "responses": {
          "200": {
            "description": "The current state of the call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "01K0SPIKE0000000000000002A",
                          "description": "Call ID (26-character ULID)"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "accepted",
                            "agent_ringing",
                            "agent_answered",
                            "customer_ringing",
                            "bridged",
                            "completed",
                            "failed"
                          ],
                          "example": "completed",
                          "description": "How far the call got. `agent_ringing` may be skipped — see the description above."
                        },
                        "reason": {
                          "type": "string",
                          "enum": [
                            "no_answer",
                            "busy",
                            "unreachable",
                            "canceled",
                            "timed_out",
                            "platform_error"
                          ],
                          "example": "canceled",
                          "nullable": true,
                          "description": "Why the call ended. `null` while the call is live and on a normal end."
                        },
                        "a_type": {
                          "type": "string",
                          "example": "sip_account",
                          "description": "Type of the agent leg. Always `sip_account` in v1."
                        },
                        "a_endpoint": {
                          "type": "string",
                          "example": "10001",
                          "description": "The SIP account that was rung first"
                        },
                        "b_number": {
                          "type": "string",
                          "example": "447700900000",
                          "description": "Destination number, digits only"
                        },
                        "b_cli": {
                          "nullable": true,
                          "type": "string",
                          "description": "Always `null` in v1"
                        },
                        "created_at": {
                          "type": "string",
                          "example": "2026-07-31T10:00:00.000Z",
                          "description": "When the call was placed. The 12-hour retention window runs from here."
                        },
                        "agent_ringing_at": {
                          "type": "string",
                          "example": "2026-07-31T10:00:03.000Z",
                          "nullable": true,
                          "description": "When the agent leg started ringing. Best-effort: `null` when the phone never reported the ring, not only when it never rang."
                        },
                        "agent_answered_at": {
                          "type": "string",
                          "example": "2026-07-31T10:00:07.000Z",
                          "nullable": true,
                          "description": "When the agent leg answered"
                        },
                        "customer_ringing_at": {
                          "type": "string",
                          "example": "2026-07-31T10:00:08.000Z",
                          "nullable": true,
                          "description": "When the destination was dialled"
                        },
                        "bridged_at": {
                          "type": "string",
                          "example": "2026-07-31T10:00:15.000Z",
                          "nullable": true,
                          "description": "When the two legs were bridged"
                        },
                        "ended_at": {
                          "type": "string",
                          "example": "2026-07-31T10:01:20.000Z",
                          "nullable": true,
                          "description": "When the call ended"
                        },
                        "duration": {
                          "type": "integer",
                          "example": 79,
                          "nullable": true,
                          "description": "Whole life of the call in seconds, ringing included. Not the billed time."
                        },
                        "cost": {
                          "type": "string",
                          "example": "0.1350",
                          "nullable": true,
                          "description": "Total cost in dollars, four decimals"
                        },
                        "finalized_at": {
                          "type": "string",
                          "example": "2026-07-31T10:01:22.000Z",
                          "nullable": true,
                          "description": "When the billed record was committed. `null` until then, and until it is set `cost` may still be `null`."
                        },
                        "recording_url": {
                          "nullable": true,
                          "type": "string",
                          "description": "Where the recording of the call can be downloaded. `null` when the call was not recorded, and `null` on a call that has not settled yet. By default the link is signed and expires one hour after it was minted; each read of the call mints a fresh one, and `GET /api/v1/calls/recording/{callid}` also gives one. If the account has permanent recording links enabled (on request through your account manager or support), the field holds a permanent `/api/v1/recordings/{user_id}/{token}` URL instead. It does not expire while the recording is retained and the option stays on."
                        },
                        "client_call_id": {
                          "nullable": true,
                          "type": "string",
                          "description": "The label you supplied when placing the call, echoed back unchanged. `null` when none was supplied. Carried on every webhook for this call."
                        },
                        "a_cli": {
                          "type": "string",
                          "example": "447700900000",
                          "nullable": true,
                          "description": "The caller ID the agent leg was presented with, digits only: the `a_cli` you supplied, or `b_number` when you supplied none. Carried on every webhook for this call."
                        }
                      },
                      "required": [
                        "id",
                        "state",
                        "reason",
                        "a_type",
                        "a_endpoint",
                        "b_number",
                        "b_cli",
                        "created_at",
                        "agent_ringing_at",
                        "agent_answered_at",
                        "customer_ringing_at",
                        "bridged_at",
                        "ended_at",
                        "duration",
                        "cost",
                        "finalized_at",
                        "recording_url",
                        "client_call_id",
                        "a_cli"
                      ],
                      "description": "The Click2Call call resource"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "01K0SPIKE0000000000000002A",
                    "state": "completed",
                    "reason": "canceled",
                    "a_type": "sip_account",
                    "a_endpoint": "10001",
                    "b_number": "447700900000",
                    "b_cli": null,
                    "created_at": "2026-07-31T10:00:00.000Z",
                    "agent_ringing_at": "2026-07-31T10:00:03.000Z",
                    "agent_answered_at": "2026-07-31T10:00:07.000Z",
                    "customer_ringing_at": "2026-07-31T10:00:08.000Z",
                    "bridged_at": "2026-07-31T10:00:15.000Z",
                    "ended_at": "2026-07-31T10:01:20.000Z",
                    "duration": 79,
                    "cost": "0.1350",
                    "finalized_at": "2026-07-31T10:01:22.000Z",
                    "recording_url": null,
                    "client_call_id": null,
                    "a_cli": "447700900000"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The API token is missing or incorrect. This endpoint answers `401`; the rest of v1 answers `403` for the same refusal.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "The API token is missing or incorrect, or the Click2Call API is not enabled for this account (`click2call_api_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "click2call_api_disabled",
                    "message": "the Click2Call API is not enabled for this account",
                    "details": []
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such call: it never existed, the ID is malformed, it belongs to another account, or it is older than the 12-hour retention window.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "call_not_found",
                    "message": "no call with that id",
                    "details": []
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Cancel a Click2Call call",
        "description": "Hangs the call up, whatever leg it has reached — before anyone answered, or\nmid-conversation. The response is `204 No Content` with an empty body.\n\n### Repeating the cancel is safe\n\nA repeated `DELETE` also answers `204`. The request is recorded once and\nevery repeat gets the same answer, so a client that retries on a timeout\ncannot get a spurious failure. Do **not** read a second `204` as \"there was\nstill a call to hang up\".\n\n### What the cancel shows up as\n\nA cancel that actually ended the call reads back with `reason` `canceled`.\nIts `state` is `completed` if the two legs had already been bridged, and\n`failed` if the call was hung up before it came together.\n\nIf the call had **already** ended on its own before your `DELETE` arrived, its\noriginal `reason` is kept — a call nobody answered still reads `no_answer`.\nCleaning up with a defensive `DELETE` therefore cannot hide why a call ended.\n\n### `404`\n\n`404 call_not_found` means the call is unknown to you: it never existed, the\nID is malformed, it belongs to another account, or it is older than the\n12-hour retention window — which runs from when the call was **placed**, not\nfrom when it ended. The cases are deliberately indistinguishable.\n\nSee also: click2call_show, which reads the call back after the cancel.\n",
        "tags": [
          "Click2Call"
        ],
        "operationId": "click2call_destroy",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01K0SPIKE0000000000000002A",
            "description": "Call ID (`data.id`) from click2call_create, a 26-character ULID"
          }
        ],
        "responses": {
          "204": {
            "description": "The call was hung up. The body is empty, and repeating the request answers 204 again."
          },
          "401": {
            "description": "The API token is missing or incorrect. This endpoint answers `401`; the rest of v1 answers `403` for the same refusal.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "The API token is missing or incorrect, or the Click2Call API is not enabled for this account (`click2call_api_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "click2call_api_disabled",
                    "message": "the Click2Call API is not enabled for this account",
                    "details": []
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such call: it never existed, the ID is malformed, it belongs to another account, or it is older than the 12-hour retention window.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "array",
                          "items": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "details"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": {
                    "code": "call_not_found",
                    "message": "no call with that id",
                    "details": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/recordings/{user_id}/{token}": {
      "get": {
        "summary": "Download a recording from a permanent link",
        "description": "Downloads a call recording from the permanent link carried in `recording_url` when the\naccount has permanent recording links enabled. The link needs no authentication.\n\n- `302` redirects to a signed download of the recording, valid for 5 minutes.\n- `404` when the link is invalid, the recording is no longer retained, or permanent\n  recording links are turned off for the account.\n- `429` with a `Retry-After` header when the account exceeds its per-minute download limit.\n\nThis link is the `recording_url` returned by click2call_create, click2call_show and their\n`click2call.*` webhooks, and sent in the call-recording webhook.\n\nWithout permanent links enabled, `recording_url` holds a temporary pre-signed URL\ninstead; to fetch a recording after it expires, use calls_recording.\n\n",
        "tags": [
          "Click2Call"
        ],
        "operationId": "recordings_show",
        "security": [],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 1234,
            "description": "User ID in the permanent `recording_url` from click2call_create, click2call_show"
          },
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "invalid-token",
            "description": "Encrypted recording token in the permanent `recording_url` from click2call_create, click2call_show"
          }
        ],
        "responses": {
          "302": {
            "description": "Redirects to a five-minute signed recording download.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                },
                "example": ""
              }
            }
          },
          "404": {
            "description": "The recording link is invalid or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errors": {
                    "base": [
                      "data not found"
                    ]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Returns 429 with `Retry-After` seconds to wait.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errors": {
                    "base": [
                      "rate limit exceeded"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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",
        "tags": [
          "Reports"
        ],
        "operationId": "asr_report_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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, paid_overstamping,\nchannel\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",
        "tags": [
          "Reports"
        ],
        "operationId": "transactions_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "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"
                }
              }
            }
          }
        }
      }
    },
    "/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`purchases[].number` feeds purchases_destinations_index, purchases_destinations_create,\npurchases_destinations_update, purchases_destinations_destroy, numbers_purchase_destroy and\nsms_create: it is the `purchase_id` of the destination operations, an entry of `did_numbers[]`\nwhen releasing numbers, and `sm[source]` when the number has SMS enabled. See also: numbers_index,\nthe same numbers with their inventory id.\n",
        "tags": [
          "Purchases"
        ],
        "operationId": "purchases_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "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"
                          },
                          "check_state": {
                            "type": "string",
                            "example": "active",
                            "description": "DID status"
                          },
                          "free_minutes": {
                            "type": "integer",
                            "example": 0,
                            "description": "Free minutes included"
                          },
                          "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"
                          }
                        },
                        "required": [
                          "number",
                          "channels",
                          "country",
                          "area",
                          "codec",
                          "check_state",
                          "free_minutes",
                          "activation",
                          "monthly_fee",
                          "per_minute"
                        ]
                      },
                      "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"
                }
              }
            }
          }
        }
      }
    },
    "/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`destination[].id` feeds purchases_destinations_update and purchases_destinations_destroy as `id`.\n",
        "tags": [
          "Inbound Destinations"
        ],
        "operationId": "purchases_destinations_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "43800327987"
            },
            "example": "43800327987",
            "description": "Purchased number id or number from numbers_index, purchases_index: the phone **number** (e.g. `43800327987`) or the numeric **inventory id** (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": 64,
                            "description": "Destination ID"
                          },
                          "transport": {
                            "type": "integer",
                            "enum": [
                              1,
                              4,
                              5,
                              10,
                              12,
                              13
                            ],
                            "example": 1,
                            "description": "Transport type: 1 = SIP URI, 4 = Phone number, 5 = SIP device, 10 = Webphone, 12 = WebSocket, 13 = SDK (rings the account of one of your SDK tokens; set up through the SDK, not through this API)"
                          },
                          "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"
                          },
                          "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)."
                          },
                          "active": {
                            "type": "boolean",
                            "example": true,
                            "description": "Whether destination is active"
                          },
                          "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)"
                          }
                        },
                        "required": [
                          "id",
                          "transport",
                          "destination",
                          "priority",
                          "callhunt",
                          "dialing_type",
                          "active",
                          "ai_agent_id",
                          "ai_agent_name"
                        ]
                      },
                      "description": "List of destinations"
                    }
                  },
                  "required": [
                    "destination"
                  ]
                },
                "example": {
                  "destination": [
                    {
                      "id": 64,
                      "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"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "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  12 = WebSocket)\n\n`transport: 12` streams the call to a WebSocket endpoint of your own instead of\nringing a phone or a SIP device, and `destination` is then its public `wss://`\nURL. It is available only to accounts enabled for voice streaming; any other\naccount is refused with `422`. The endpoint has to speak our protocol — see\n[WebSocket Calls](https://docs.didlogic.com/docs/guides/apps-developer-tools/websocket-calls).\n\n`did_destination.id` feeds purchases_destinations_update and purchases_destinations_destroy as `id`.\nRows: purchases_destinations_index.\n",
        "tags": [
          "Inbound Destinations"
        ],
        "operationId": "purchases_destinations_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "43800327987"
            },
            "example": "43800327987",
            "description": "Purchased number id or number from numbers_index, purchases_index: the phone **number** (e.g. `43800327987`) or the numeric **inventory id** (e.g. `21869`). Both resolve the same DID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "destination": {
                    "type": "object",
                    "properties": {
                      "destination": {
                        "type": "string",
                        "description": "Forwarding target (SIP URI or phone number). Required for every transport except Webphone (10), which rings your webphone and takes no address.",
                        "example": "sip:test@example.com"
                      },
                      "callhunt": {
                        "type": "boolean",
                        "description": "Enable callhunt (ring all). Ignored when `destination[dialing_type]` is sent.",
                        "example": false
                      },
                      "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"
                        ]
                      },
                      "active": {
                        "type": "boolean",
                        "description": "Activate this destination",
                        "example": true
                      },
                      "transport": {
                        "type": "integer",
                        "description": "Transport type (1=SIP URI, 4=Phone number, 5=SIP device, 10=Webphone, 12=WebSocket). 12 requires an account enabled for voice streaming.",
                        "enum": [
                          1,
                          4,
                          5,
                          10,
                          12
                        ],
                        "example": 1
                      }
                    },
                    "required": [
                      "transport"
                    ]
                  }
                },
                "required": [
                  "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": 67,
                          "description": "Destination ID"
                        },
                        "transport": {
                          "type": "integer",
                          "enum": [
                            1,
                            4,
                            5,
                            10,
                            12
                          ],
                          "example": 1,
                          "description": "Transport type"
                        },
                        "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"
                        },
                        "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)."
                        },
                        "active": {
                          "type": "boolean",
                          "example": true,
                          "description": "Whether destination is active"
                        },
                        "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)"
                        }
                      },
                      "required": [
                        "id",
                        "transport",
                        "destination",
                        "priority",
                        "callhunt",
                        "dialing_type",
                        "active",
                        "ai_agent_id",
                        "ai_agent_name"
                      ],
                      "description": "Created destination details"
                    }
                  },
                  "required": [
                    "did_destination"
                  ]
                },
                "example": {
                  "did_destination": {
                    "id": 67,
                    "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"
                    ]
                  }
                }
              }
            }
          },
          "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"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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",
        "tags": [
          "Inbound Destinations"
        ],
        "operationId": "purchases_destinations_update",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "43800327987"
            },
            "example": "43800327987",
            "description": "Purchased number id or number from numbers_index, purchases_index: the phone **number** (e.g. `43800327987`) or the numeric **inventory id** (e.g. `21869`). Both resolve the same DID."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 70,
            "description": "Destination id from purchases_destinations_index, purchases_destinations_create"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "destination": {
                    "type": "object",
                    "properties": {
                      "callhunt": {
                        "type": "boolean",
                        "description": "Enable callhunt (ring all). Ignored when `destination[dialing_type]` is sent.",
                        "example": true
                      },
                      "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"
                        ]
                      },
                      "active": {
                        "type": "boolean",
                        "description": "Activate/deactivate this destination",
                        "example": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "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": 68,
                          "description": "Destination ID"
                        },
                        "transport": {
                          "type": "integer",
                          "enum": [
                            1,
                            4,
                            5,
                            10,
                            12,
                            13
                          ],
                          "example": 1,
                          "description": "Transport type: 1 = SIP URI, 4 = Phone number, 5 = SIP device, 10 = Webphone, 12 = WebSocket, 13 = SDK (rings the account of one of your SDK tokens; set up through the SDK, not through this API)"
                        },
                        "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"
                        },
                        "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)."
                        },
                        "active": {
                          "type": "boolean",
                          "description": "Whether destination is active"
                        },
                        "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)"
                        }
                      },
                      "required": [
                        "id",
                        "transport",
                        "destination",
                        "priority",
                        "callhunt",
                        "dialing_type",
                        "active",
                        "ai_agent_id",
                        "ai_agent_name"
                      ],
                      "description": "Updated destination details"
                    }
                  },
                  "required": [
                    "did_destination"
                  ]
                },
                "example": {
                  "did_destination": {
                    "id": 68,
                    "transport": 1,
                    "destination": "sip:test@example.com",
                    "priority": 1,
                    "callhunt": true,
                    "dialing_type": "ring_all",
                    "active": false,
                    "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "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",
        "tags": [
          "Inbound Destinations"
        ],
        "operationId": "purchases_destinations_destroy",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "43800327987"
            },
            "example": "43800327987",
            "description": "Purchased number id or number from numbers_index, purchases_index: the phone **number** (e.g. `43800327987`) or the numeric **inventory id** (e.g. `21869`). Both resolve the same DID."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 63,
            "description": "Destination id from purchases_destinations_index, purchases_destinations_create"
          }
        ],
        "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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\nTechnical accounts the platform manages for you — the Webphone account and\neach SDK token's account (labelled `SDK Instance: <token label>`) — are\nlisted too, but cannot be fetched by id, updated or deleted through this API.\n\n`sipaccounts[].id` feeds sipaccounts_show, sipaccounts_update, sipaccounts_destroy,\nsipaccounts_allowed_ips_index, sipaccounts_allowed_ips_create and sipaccounts_allowed_ips_destroy;\neach also takes `sipaccounts[].name` in its place. `sipaccounts[].name` feeds call_price_show,\ncalls_show and click2call_create as the SIP account to price, filter by or ring. Full record:\nsipaccounts_show.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "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": 340,
                            "description": "Unique SIP account identifier"
                          },
                          "name": {
                            "type": "string",
                            "example": "20337",
                            "description": "SIP account username"
                          },
                          "callerid": {
                            "type": "string",
                            "example": "",
                            "description": "Caller ID"
                          },
                          "label": {
                            "type": "string",
                            "example": "some-label-10",
                            "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 the per-call duration limit is enabled"
                          },
                          "call_limit": {
                            "type": "integer",
                            "example": 60,
                            "description": "Maximum call duration in seconds"
                          },
                          "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-10-21 09:47:16 UTC",
                            "description": "Account creation timestamp"
                          },
                          "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"
                          },
                          "low_balance": {
                            "type": "boolean",
                            "description": "Whether account has low balance"
                          },
                          "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"
                          },
                          "allowed_ips": {
                            "type": "array",
                            "items": {},
                            "description": "List of IP addresses allowed to authenticate"
                          }
                        },
                        "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",
                          "charge",
                          "talk_time",
                          "low_balance",
                          "spend_limit",
                          "spend_limit_enabled",
                          "available_amount",
                          "call_recording_enabled",
                          "allowed_ips"
                        ]
                      },
                      "description": "List of SIP accounts"
                    }
                  },
                  "required": [
                    "sipaccounts"
                  ]
                },
                "example": {
                  "sipaccounts": [
                    {
                      "id": 340,
                      "name": "20337",
                      "callerid": "",
                      "label": "some-label-10",
                      "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-10-21 09:47:16 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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create SIP account",
        "description": "Create a new SIP account (trunk) for making/receiving calls.\n\n`sipaccount.id` feeds sipaccounts_show, sipaccounts_update, sipaccounts_destroy,\nsipaccounts_allowed_ips_index, sipaccounts_allowed_ips_create and sipaccounts_allowed_ips_destroy;\neach also takes `sipaccount.name` in its place. `sipaccount.name` feeds call_price_show,\ncalls_show and click2call_create as the SIP account to price, filter by or ring.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sipaccount": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string",
                        "description": "Account label/name",
                        "example": "Test SIP Account"
                      },
                      "password": {
                        "type": "string",
                        "description": "SIP password",
                        "example": "SecurePass123"
                      },
                      "callerid": {
                        "type": "string",
                        "description": "Caller ID to display on outbound calls",
                        "example": "1234567890"
                      },
                      "rewrite_enabled": {
                        "type": "boolean",
                        "description": "Enable number rewriting",
                        "example": false
                      },
                      "rewrite_cond": {
                        "type": "string",
                        "description": "Rewrite condition pattern (regular expression)"
                      },
                      "rewrite_prefix": {
                        "type": "string",
                        "description": "Prefix to add when rewriting numbers"
                      },
                      "didinfo_enabled": {
                        "type": "boolean",
                        "description": "Enable DID info in SIP headers",
                        "example": true
                      },
                      "ip_restrict": {
                        "type": "boolean",
                        "description": "Restrict access by IP address (requires allowed IPs)",
                        "example": false
                      },
                      "call_restrict": {
                        "type": "boolean",
                        "description": "Enable the per-call duration limit",
                        "example": true
                      },
                      "call_limit": {
                        "type": "integer",
                        "description": "Maximum call duration in seconds",
                        "example": 1000
                      },
                      "channels_restrict": {
                        "type": "boolean",
                        "description": "Enable concurrent channel limits",
                        "example": true
                      },
                      "max_channels": {
                        "type": "integer",
                        "description": "Maximum concurrent channels allowed",
                        "example": 5
                      },
                      "cost_limit": {
                        "type": "boolean",
                        "description": "Enable maximum call cost limit",
                        "example": false
                      },
                      "max_call_cost": {
                        "type": "integer",
                        "description": "Maximum allowed cost per call in cents"
                      },
                      "spend_limit_enabled": {
                        "type": "boolean",
                        "description": "Enable total spending limit",
                        "example": false
                      },
                      "spend_limit": {
                        "type": "integer",
                        "description": "Maximum total spend amount in cents"
                      },
                      "reset_available_amount": {
                        "type": "integer",
                        "description": "Amount available for spend limit reset in cents"
                      },
                      "call_recording_enabled": {
                        "type": "boolean",
                        "description": "Enable or disable recording of outbound calls made via a selected SIP account"
                      }
                    },
                    "required": [
                      "label",
                      "password"
                    ]
                  }
                },
                "required": [
                  "sipaccount"
                ]
              }
            }
          }
        },
        "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": 379,
                          "description": "SIP account ID"
                        },
                        "name": {
                          "type": "string",
                          "example": "68392",
                          "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 the per-call duration limit is enabled"
                        },
                        "call_limit": {
                          "type": "integer",
                          "example": 1000,
                          "description": "Maximum call duration in seconds"
                        },
                        "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-10-21 09:47:57 UTC",
                          "description": "Creation timestamp"
                        },
                        "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"
                        },
                        "low_balance": {
                          "type": "boolean",
                          "description": "Whether account has low balance"
                        },
                        "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"
                        },
                        "allowed_ips": {
                          "type": "array",
                          "items": {},
                          "description": "List of IP addresses allowed to authenticate"
                        }
                      },
                      "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",
                        "charge",
                        "talk_time",
                        "low_balance",
                        "spend_limit",
                        "spend_limit_enabled",
                        "available_amount",
                        "call_recording_enabled",
                        "allowed_ips"
                      ],
                      "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": 379,
                    "name": "68392",
                    "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-10-21 09:47:57 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": []
                  },
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sipaccounts/{id}": {
      "get": {
        "summary": "Get SIP account details",
        "description": "Retrieve details of a specific SIP account.\n\nRows: sipaccounts_index. See also: sipaccounts_allowed_ips_index, to manage the allowed IPs.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "01234"
            },
            "example": "01234",
            "description": "SIP account name or id from sipaccounts_index, sipaccounts_create: 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": 334,
                          "description": "Unique SIP account identifier"
                        },
                        "name": {
                          "type": "string",
                          "example": "44583",
                          "description": "SIP account username"
                        },
                        "callerid": {
                          "type": "string",
                          "example": "",
                          "description": "Caller ID"
                        },
                        "label": {
                          "type": "string",
                          "example": "some-label-1",
                          "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 the per-call duration limit is enabled"
                        },
                        "call_limit": {
                          "type": "integer",
                          "example": 60,
                          "description": "Maximum call duration in seconds"
                        },
                        "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-10-21 09:46:53 UTC",
                          "description": "Account creation timestamp"
                        },
                        "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"
                        },
                        "low_balance": {
                          "type": "boolean",
                          "description": "Whether account has low balance"
                        },
                        "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"
                        },
                        "allowed_ips": {
                          "type": "array",
                          "items": {},
                          "description": "List of IP addresses allowed to authenticate"
                        }
                      },
                      "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",
                        "charge",
                        "talk_time",
                        "low_balance",
                        "spend_limit",
                        "spend_limit_enabled",
                        "available_amount",
                        "call_recording_enabled",
                        "allowed_ips"
                      ],
                      "description": "SIP account details"
                    }
                  },
                  "required": [
                    "sipaccount"
                  ]
                },
                "example": {
                  "sipaccount": {
                    "id": 334,
                    "name": "44583",
                    "callerid": "",
                    "label": "some-label-1",
                    "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-10-21 09:46:53 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 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"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update SIP account",
        "description": "Update SIP account settings.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_update",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "01234"
            },
            "example": "01234",
            "description": "SIP account name or id from sipaccounts_index, sipaccounts_create: 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": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sipaccount": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string",
                        "description": "Account label/name",
                        "example": "Updated Label"
                      },
                      "password": {
                        "type": "string",
                        "description": "SIP password"
                      },
                      "callerid": {
                        "type": "string",
                        "description": "Caller ID to display on outbound calls",
                        "example": "9876543210"
                      },
                      "rewrite_enabled": {
                        "type": "boolean",
                        "description": "Enable number rewriting"
                      },
                      "rewrite_cond": {
                        "type": "string",
                        "description": "Rewrite condition pattern (regular expression)"
                      },
                      "rewrite_prefix": {
                        "type": "string",
                        "description": "Prefix to add when rewriting numbers"
                      },
                      "didinfo_enabled": {
                        "type": "boolean",
                        "description": "Enable DID info in SIP headers",
                        "example": true
                      },
                      "ip_restrict": {
                        "type": "boolean",
                        "description": "Restrict access by IP address (requires allowed IPs)"
                      },
                      "call_restrict": {
                        "type": "boolean",
                        "description": "Enable the per-call duration limit",
                        "example": true
                      },
                      "call_limit": {
                        "type": "integer",
                        "description": "Maximum call duration in seconds",
                        "example": 2000
                      },
                      "channels_restrict": {
                        "type": "boolean",
                        "description": "Enable concurrent channel limits",
                        "example": true
                      },
                      "max_channels": {
                        "type": "integer",
                        "description": "Maximum concurrent channels allowed",
                        "example": 10
                      },
                      "cost_limit": {
                        "type": "boolean",
                        "description": "Enable maximum call cost limit"
                      },
                      "max_call_cost": {
                        "type": "integer",
                        "description": "Maximum allowed cost per call in cents"
                      },
                      "spend_limit_enabled": {
                        "type": "boolean",
                        "description": "Enable total spending limit. Switching a disabled limit back on restarts it: the full limit is available again, counted from now"
                      },
                      "spend_limit": {
                        "type": "integer",
                        "description": "Maximum total spend amount in cents"
                      },
                      "reset_available_amount": {
                        "type": "integer",
                        "description": "Amount available for spend limit reset in cents"
                      },
                      "call_recording_enabled": {
                        "type": "boolean",
                        "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": 370,
                          "description": "Unique SIP account identifier"
                        },
                        "name": {
                          "type": "string",
                          "example": "72604",
                          "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 the per-call duration limit is enabled"
                        },
                        "call_limit": {
                          "type": "integer",
                          "example": 2000,
                          "description": "Maximum call duration in seconds"
                        },
                        "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-10-21 09:47:46 UTC",
                          "description": "Account creation timestamp"
                        },
                        "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"
                        },
                        "low_balance": {
                          "type": "boolean",
                          "description": "Whether account has low balance"
                        },
                        "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"
                        },
                        "allowed_ips": {
                          "type": "array",
                          "items": {},
                          "description": "List of IP addresses allowed to authenticate"
                        }
                      },
                      "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",
                        "charge",
                        "talk_time",
                        "low_balance",
                        "spend_limit",
                        "spend_limit_enabled",
                        "available_amount",
                        "call_recording_enabled",
                        "allowed_ips"
                      ],
                      "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": 370,
                    "name": "72604",
                    "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-10-21 09:47:46 UTC",
                    "charge": "0.0",
                    "talk_time": 0,
                    "low_balance": false,
                    "spend_limit": "10000.0",
                    "spend_limit_enabled": false,
                    "available_amount": "10000.0",
                    "call_recording_enabled": false,
                    "allowed_ips": []
                  },
                  "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"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete SIP account",
        "description": "Delete a SIP account.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_destroy",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "01234"
            },
            "example": "01234",
            "description": "SIP account name or id from sipaccounts_index, sipaccounts_create: 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"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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`allowed_ips` feeds sipaccounts_allowed_ips_destroy as `ip`.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_allowed_ips_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sipaccount_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "01234"
            },
            "example": "01234",
            "description": "SIP account name or id from sipaccounts_index, sipaccounts_create: 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"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Add allowed IP address",
        "description": "Add IP address to SIP account whitelist.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_allowed_ips_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sipaccount_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "01234"
            },
            "example": "01234",
            "description": "SIP account name or id from sipaccounts_index, sipaccounts_create: 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": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ip": {
                    "type": "string",
                    "description": "Single IPv4 address in dotted-decimal form; a range (CIDR) is rejected",
                    "example": "invalid-ip"
                  }
                },
                "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": [
                      "only ip format xxx.xxx.xxx.xxx"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove allowed IP address",
        "description": "Remove IP address from SIP account whitelist.\n",
        "tags": [
          "SIP Accounts"
        ],
        "operationId": "sipaccounts_allowed_ips_destroy",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sipaccount_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "01234"
            },
            "example": "01234",
            "description": "SIP account name or id from sipaccounts_index, sipaccounts_create: 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"
            },
            "example": "1.2.3.4",
            "description": "IP address to remove, from sipaccounts_allowed_ips_index"
          }
        ],
        "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"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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\n`sms[].id` feeds sms_show. Full record: sms_show.\n",
        "tags": [
          "SMS"
        ],
        "operationId": "sms_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "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": {
                    "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"
                      ]
                    },
                    "sms": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "example": 31,
                            "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"
                          },
                          "error_code": {
                            "nullable": true,
                            "type": "integer",
                            "description": "Why the SMS failed, as an SMPP command_status; `null` unless `status` is `failed`. A failure with no more specific code reads `255`.\n- `10` (`ESME_RINVSRCADR`) — Invalid sender ID: the sender ID is not accepted for this destination\n- `11` (`ESME_RINVDSTADR`) — Invalid destination number: the destination number is not valid\n- `69` (`ESME_RSUBMITFAIL`) — Submit failed: the message was rejected and not delivered\n- `255` (`ESME_RUNKNOWNERR`) — Unknown error: the message failed for any other reason"
                          },
                          "error_description": {
                            "nullable": true,
                            "type": "string",
                            "description": "The text for `error_code` (\"Invalid sender ID\", \"Invalid destination number\", \"Submit failed\", \"Unknown error\"); `null` unless `status` is `failed`."
                          }
                        },
                        "required": [
                          "id",
                          "destination",
                          "message",
                          "status",
                          "charge",
                          "segments_count",
                          "error_code",
                          "error_description"
                        ]
                      },
                      "description": "List of SMS messages"
                    }
                  },
                  "required": [
                    "pagination",
                    "sms"
                  ]
                },
                "example": {
                  "pagination": {
                    "pages": 1,
                    "page": 1,
                    "total_records": 1,
                    "per_page": 100
                  },
                  "sms": [
                    {
                      "id": 31,
                      "destination": "1234567890",
                      "message": "Test",
                      "status": "created",
                      "charge": 0,
                      "segments_count": 1,
                      "error_code": null,
                      "error_description": 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"
                }
              }
            }
          }
        }
      },
      "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`sms.id` feeds sms_show. See also: numbers_search_show, to find SMS-enabled numbers to buy.\n",
        "tags": [
          "SMS"
        ],
        "operationId": "sms_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sm": {
                    "type": "object",
                    "properties": {
                      "source": {
                        "type": "string",
                        "description": "Source number from numbers_index, purchases_index; it must be one of your numbers with SMS enabled (in numbers_index its `services` include `sms`) or one of your approved sender IDs",
                        "example": "1234567890"
                      },
                      "destination": {
                        "type": "string",
                        "description": "Destination phone number (must be a valid international number)",
                        "example": "+12012025555"
                      },
                      "message": {
                        "type": "string",
                        "description": "SMS text content (160 chars per segment)",
                        "example": "Test message from API"
                      }
                    },
                    "required": [
                      "source",
                      "destination",
                      "message"
                    ]
                  },
                  "dlr": {
                    "type": "object",
                    "properties": {
                      "callback_endpoint": {
                        "type": "string",
                        "description": "Optional DLR (Delivery Receipt) callback URL",
                        "example": "https://example.com/webhook"
                      }
                    }
                  }
                },
                "required": [
                  "sm"
                ]
              }
            }
          }
        },
        "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": 33,
                          "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"
                        },
                        "error_code": {
                          "nullable": true,
                          "type": "integer",
                          "description": "Why the SMS failed, as an SMPP command_status; `null` unless `status` is `failed`. A failure with no more specific code reads `255`.\n- `10` (`ESME_RINVSRCADR`) — Invalid sender ID: the sender ID is not accepted for this destination\n- `11` (`ESME_RINVDSTADR`) — Invalid destination number: the destination number is not valid\n- `69` (`ESME_RSUBMITFAIL`) — Submit failed: the message was rejected and not delivered\n- `255` (`ESME_RUNKNOWNERR`) — Unknown error: the message failed for any other reason"
                        },
                        "error_description": {
                          "nullable": true,
                          "type": "string",
                          "description": "The text for `error_code` (\"Invalid sender ID\", \"Invalid destination number\", \"Submit failed\", \"Unknown error\"); `null` unless `status` is `failed`."
                        }
                      },
                      "required": [
                        "id",
                        "destination",
                        "message",
                        "status",
                        "charge",
                        "segments_count",
                        "error_code",
                        "error_description"
                      ],
                      "description": "Created SMS details"
                    }
                  },
                  "required": [
                    "sms"
                  ]
                },
                "example": {
                  "sms": {
                    "id": 33,
                    "destination": "12012025555",
                    "message": "Test message from API",
                    "status": "created",
                    "charge": 0.0001,
                    "segments_count": 1,
                    "error_code": null,
                    "error_description": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body must be valid JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errors": {
                    "base": [
                      "malformed request body"
                    ]
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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\nRows: sms_index.\n",
        "tags": [
          "SMS"
        ],
        "operationId": "sms_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 0,
            "description": "SMS message id from sms_index, sms_create"
          }
        ],
        "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": 34,
                          "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"
                        },
                        "error_code": {
                          "nullable": true,
                          "type": "integer",
                          "description": "Why the SMS failed, as an SMPP command_status; `null` unless `status` is `failed`. A failure with no more specific code reads `255`.\n- `10` (`ESME_RINVSRCADR`) — Invalid sender ID: the sender ID is not accepted for this destination\n- `11` (`ESME_RINVDSTADR`) — Invalid destination number: the destination number is not valid\n- `69` (`ESME_RSUBMITFAIL`) — Submit failed: the message was rejected and not delivered\n- `255` (`ESME_RUNKNOWNERR`) — Unknown error: the message failed for any other reason"
                        },
                        "error_description": {
                          "nullable": true,
                          "type": "string",
                          "description": "The text for `error_code` (\"Invalid sender ID\", \"Invalid destination number\", \"Submit failed\", \"Unknown error\"); `null` unless `status` is `failed`."
                        }
                      },
                      "required": [
                        "id",
                        "destination",
                        "message",
                        "status",
                        "charge",
                        "segments_count",
                        "error_code",
                        "error_description"
                      ],
                      "description": "SMS message details"
                    }
                  },
                  "required": [
                    "sms"
                  ]
                },
                "example": {
                  "sms": {
                    "id": 34,
                    "destination": "1234567890",
                    "message": "Test message",
                    "status": "created",
                    "charge": 0,
                    "segments_count": 1,
                    "error_code": null,
                    "error_description": 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": "The requested resource could not be found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errors": {
                    "base": [
                      "data not found"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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`countries[].id` feeds numbers_countries_cities_index, numbers_countries_regions_index,\nnumbers_countries_locations_index and numbers_countries_cities_dids_index (`country_id`).\n`countries[].name` feeds numbers_search_show (`country_name_contains`). A country with\n`has_provinces_or_states` true lists its states in numbers_countries_regions_index.\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_countries_index",
        "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": 667,
                            "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": 667,
                      "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 a country with `has_provinces_or_states`, numbers_search_show narrows to one state by its `region_id` from numbers_countries_regions_index\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`cities[].id` feeds numbers_countries_cities_dids_index and numbers_search_show (`city_id`).\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_countries_cities_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "country_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 701,
            "description": "Country id from numbers_countries_index"
          }
        ],
        "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": 722,
                            "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": 722,
                      "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- A state's numbers are listed by numbers_search_show with the state's `region_id`\n\n**When to use:**\n- Building state/province selection for US, Canada, etc.\n- Filtering DID search by region\n\n`regions[].id` feeds numbers_search_show (`region_id`). `regions[].name` feeds\nnumbers_search_show (`state_name_contains`, United States only).\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_countries_regions_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "country_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 0,
            "description": "Country id from numbers_countries_index"
          }
        ],
        "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": 98,
                            "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": 98,
                      "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`locations[].city_id` feeds numbers_countries_cities_dids_index and numbers_search_show\n(`city_id`). `locations[].state_id` feeds numbers_search_show (`region_id`).\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_countries_locations_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "country_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 697,
            "description": "Country id from numbers_countries_index"
          },
          {
            "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": 718,
                            "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": 91,
                            "description": "State identifier (if applicable)"
                          },
                          "country_id": {
                            "type": "integer",
                            "example": 694,
                            "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": 718,
                      "city_name": "New York",
                      "country_name": "United States",
                      "state_id": 91,
                      "country_id": 694,
                      "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`dids.dids[].id` feeds numbers_purchase_create (`id_in`). `dids.dids[].number` feeds\nnumbers_purchase_create (`did_numbers`). See also: numbers_search_show.\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_countries_cities_dids_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "country_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 746,
            "description": "Country id from numbers_countries_index"
          },
          {
            "name": "city_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 774,
            "description": "City id from numbers_countries_cities_index, numbers_countries_locations_index"
          }
        ],
        "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": 841,
                                "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"
                              },
                              "required_documents": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "integer",
                                      "example": 7,
                                      "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"
                              },
                              "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)"
                              },
                              "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",
                              "required_documents",
                              "activation",
                              "monthly",
                              "per_minute",
                              "origination_per_min",
                              "state",
                              "country_short_name",
                              "number",
                              "never_sold",
                              "call_recording_enabled"
                            ]
                          },
                          "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": 841,
                        "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": 7,
                            "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`dids.dids[].id` feeds numbers_purchase_create (`id_in`). `dids.dids[].number` feeds\nnumbers_purchase_create (`did_numbers`). See also: numbers_countries_cities_dids_index.\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_search_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id_in",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 817,
            "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), from numbers_countries_index"
          },
          {
            "name": "state_name_contains",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "York",
            "description": "Filter by state/region name (partial match, US only), from numbers_countries_regions_index"
          },
          {
            "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": 2655,
            "description": "Filter by vendor ID (requires special permission)"
          },
          {
            "name": "city_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 747,
            "description": "City id from numbers_countries_cities_index, numbers_countries_locations_index"
          },
          {
            "name": "region_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 97,
            "description": "Region id from numbers_countries_regions_index, numbers_countries_locations_index"
          },
          {
            "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": 815,
                                "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"
                              },
                              "required_documents": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "integer",
                                      "example": 7,
                                      "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"
                              },
                              "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)"
                              },
                              "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",
                              "required_documents",
                              "activation",
                              "monthly",
                              "per_minute",
                              "origination_per_min",
                              "state",
                              "country_short_name",
                              "number",
                              "never_sold",
                              "call_recording_enabled"
                            ]
                          },
                          "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": 815,
                        "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": 7,
                            "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`dids[].id` feeds numbers_purchase_update and numbers_purchase_destroy (`id`, `id_in[]`).\n`dids[].number` feeds numbers_purchase_destroy (`did_numbers[]`). `dids[].id` feeds\npurchases_destinations_index, purchases_destinations_create, purchases_destinations_update and\npurchases_destinations_destroy (`purchase_id`, which takes the number too). `dids[].identity_id`\nfeeds identities_index and numbers_purchase_update (`ids`, `identity_id`). See also: purchases_index.\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_index",
        "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": 862,
                            "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": 429,
                            "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": 862,
                      "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": 429
                    }
                  ]
                }
              }
            }
          },
          "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`purchase.purchases[].id` feeds numbers_purchase_update and numbers_purchase_destroy (`id`, `id_in[]`).\n`purchase.purchases[].id` feeds purchases_destinations_index and purchases_destinations_create\n(`purchase_id`). `purchase.purchases[].number` feeds numbers_purchase_destroy (`did_numbers[]`).\nSee also: numbers_index.\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_purchase_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id_in": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "description": "Array of DID IDs to purchase, from numbers_countries_cities_dids_index, numbers_search_show",
                    "example": [
                      833
                    ]
                  },
                  "did_numbers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of DID numbers to purchase, from numbers_countries_cities_dids_index, numbers_search_show",
                    "example": [
                      "1111111111",
                      "2222222222",
                      "3333333333"
                    ]
                  },
                  "identities": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Array of identity objects with document associations",
                    "example": [
                      {
                        "id": 101,
                        "did_ids": [
                          21869
                        ]
                      },
                      {
                        "id": 102,
                        "did_numbers": [
                          "43800327988"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "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": 821,
                                "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: 1 - Personal ID, 2 - Proof of Address, 3 - Proof of Local Address, 4 - Business Registration, 5 - Local Business Registration, 6 - Letter of Intent"
                              },
                              "commitment_months": {
                                "type": "integer",
                                "example": 12,
                                "description": "Minimum service term in months (omitted when the commitment policy is disabled)"
                              },
                              "never_sold": {
                                "type": "integer",
                                "example": 1,
                                "description": "Whether number has never been sold before (1=yes, 0=no)"
                              },
                              "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)"
                              }
                            },
                            "required": [
                              "id",
                              "number",
                              "sms_enabled",
                              "no_local_cli",
                              "channels",
                              "country",
                              "area",
                              "free_minutes",
                              "codec",
                              "require_docs",
                              "never_sold",
                              "activation",
                              "monthly_fee",
                              "per_minute",
                              "origination_per_min"
                            ]
                          },
                          "description": "Successfully purchased numbers"
                        }
                      },
                      "required": [
                        "errors",
                        "purchases"
                      ],
                      "description": "Purchase response object"
                    }
                  },
                  "required": [
                    "purchase"
                  ]
                },
                "example": {
                  "purchase": {
                    "errors": {},
                    "purchases": [
                      {
                        "id": 821,
                        "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": 822,
                        "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": 823,
                        "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": {
                        "errors": {
                          "type": "object",
                          "properties": {
                            "identities": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          },
                          "required": [
                            "identities"
                          ]
                        },
                        "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": 827,
                                    "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: 1 - Personal ID, 2 - Proof of Address, 3 - Proof of Local Address, 4 - Business Registration, 5 - Local Business Registration, 6 - Letter of Intent"
                                  },
                                  "commitment_months": {
                                    "type": "integer",
                                    "example": 12,
                                    "description": "Minimum service term in months (omitted when the commitment policy is disabled)"
                                  },
                                  "never_sold": {
                                    "type": "integer",
                                    "example": 1,
                                    "description": "Whether number has never been sold before (1=yes, 0=no)"
                                  },
                                  "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)"
                                  }
                                },
                                "required": [
                                  "id",
                                  "number",
                                  "sms_enabled",
                                  "no_local_cli",
                                  "channels",
                                  "country",
                                  "area",
                                  "free_minutes",
                                  "codec",
                                  "require_docs",
                                  "never_sold",
                                  "activation",
                                  "monthly_fee",
                                  "per_minute",
                                  "origination_per_min"
                                ]
                              },
                              "description": "Successfully purchased numbers"
                            }
                          },
                          "required": [
                            "errors",
                            "purchases"
                          ],
                          "description": "Purchase response object"
                        }
                      }
                    }
                  ]
                },
                "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": 827,
                            "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": 828,
                            "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": 829,
                            "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**Other normalizations applied silently on number purchase/update:**\n- Webphone destinations (`transport=10`) are resolved server-side.\n- Boolean-like fields are coerced to booleans.\n- Destination strings are normalized.\n- SMS delivery-receipt (`dlr`) and Sender-ID settings follow account\n  defaults when omitted.\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_purchase_update",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "description": "DID ID from numbers_index, numbers_purchase_create",
                    "example": 768
                  },
                  "identity_id": {
                    "type": "integer",
                    "description": "Identity ID to associate with the number, from identities_index, identities_create",
                    "example": 0
                  },
                  "call_recording_enabled": {
                    "type": "boolean",
                    "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": 765,
                          "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"
                        },
                        "call_recording_enabled": {
                          "type": "boolean",
                          "description": "Whether inbound call recording is enabled for this DID"
                        },
                        "commitment_months": {
                          "type": "integer",
                          "example": 12,
                          "description": "Minimum service term in months (omitted when the commitment policy is disabled)"
                        },
                        "identity_id": {
                          "type": "integer",
                          "example": 395,
                          "description": "Associated identity ID"
                        }
                      },
                      "required": [
                        "id",
                        "number",
                        "country",
                        "area",
                        "channels",
                        "activation",
                        "monthly_fee",
                        "per_minute",
                        "services",
                        "status",
                        "destination_count",
                        "call_recording_enabled",
                        "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": 765,
                    "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,
                    "call_recording_enabled": false,
                    "commitment_months": 12,
                    "identity_id": 395
                  },
                  "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**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\nA number that is cancelable but whose cancellation fails is reported with\ncode `cancellation_failed` and is omitted from `dids`; it remains in your\ninventory and is still billable. A request where every number fails this\nway returns `200` with an empty `dids` array.\n",
        "tags": [
          "Numbers & Inventory"
        ],
        "operationId": "numbers_purchase_destroy",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id_in[]",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "example": [
                1001,
                1002
              ]
            },
            "description": "Array of DID IDs to cancel, from numbers_index",
            "example": [
              1001,
              1002
            ]
          },
          {
            "name": "did_numbers[]",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "12125551234",
                "12125551235"
              ]
            },
            "description": "Array of DID numbers to cancel, from numbers_index, purchases_index",
            "example": [
              "12125551234",
              "12125551235"
            ]
          }
        ],
        "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": 795,
                            "description": "DID identifier"
                          },
                          "number": {
                            "type": "string",
                            "example": "79090160029",
                            "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 79090160029",
                            "description": "Country name"
                          },
                          "area": {
                            "type": "string",
                            "example": "Fake city for 79090160029",
                            "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: 1 - Personal ID, 2 - Proof of Address, 3 - Proof of Local Address, 4 - Business Registration, 5 - Local Business Registration, 6 - Letter of Intent"
                          },
                          "commitment_months": {
                            "type": "integer",
                            "example": 12,
                            "description": "Minimum service term in months"
                          },
                          "never_sold": {
                            "type": "integer",
                            "example": 0,
                            "description": "Whether number has never been sold before (1=yes, 0=no)"
                          },
                          "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)"
                          }
                        },
                        "required": [
                          "id",
                          "number",
                          "sms_enabled",
                          "no_local_cli",
                          "channels",
                          "country",
                          "area",
                          "free_minutes",
                          "codec",
                          "require_docs",
                          "commitment_months",
                          "never_sold",
                          "activation",
                          "monthly_fee",
                          "per_minute",
                          "origination_per_min"
                        ]
                      },
                      "description": "List of cancelled DIDs returned to inventory"
                    },
                    "warnings": {
                      "type": "array",
                      "description": "Non-fatal notices for requested numbers that were not cancelled — either not in your cancelable inventory (`not_in_inventory`) or cancelable but not cancelled (`cancellation_failed`). Present only when non-empty.",
                      "items": {
                        "$ref": "#/components/schemas/Warning"
                      }
                    }
                  },
                  "required": [
                    "dids"
                  ]
                },
                "examples": {
                  "cancels_every_named_number": {
                    "summary": "cancels every named number",
                    "value": {
                      "dids": [
                        {
                          "id": 795,
                          "number": "79090160029",
                          "sms_enabled": false,
                          "no_local_cli": false,
                          "channels": 1,
                          "country": "Fake country for 79090160029",
                          "area": "Fake city for 79090160029",
                          "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": 796,
                          "number": "79090160030",
                          "sms_enabled": false,
                          "no_local_cli": false,
                          "channels": 1,
                          "country": "Fake country for 79090160029",
                          "area": "Fake city for 79090160029",
                          "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
                        }
                      ]
                    }
                  },
                  "cancels_owned_numbers_and_reports_skipped_ones_as_warnings": {
                    "summary": "cancels owned numbers and reports skipped ones as warnings",
                    "value": {
                      "dids": [
                        {
                          "id": 789,
                          "number": "79090160023",
                          "sms_enabled": false,
                          "no_local_cli": false,
                          "channels": 1,
                          "country": "Fake country for 79090160023",
                          "area": "Fake city for 79090160023",
                          "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": 790,
                          "number": "79090160024",
                          "sms_enabled": false,
                          "no_local_cli": false,
                          "channels": 1,
                          "country": "Fake country for 79090160023",
                          "area": "Fake city for 79090160023",
                          "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": 791,
                          "number": "79090160025",
                          "sms_enabled": false,
                          "no_local_cli": false,
                          "channels": 1,
                          "country": "Fake country for 79090160023",
                          "area": "Fake city for 79090160023",
                          "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`tasks[].id` feeds numbers_risk_checks_logs (`task_ids`). Rows: numbers_risk_checks_logs.\n",
        "tags": [
          "Risk Checks"
        ],
        "operationId": "numbers_risk_checks_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "123,124",
            "description": "Task IDs (comma-separated) from numbers_risk_checks_create, numbers_risk_checks_logs"
          },
          {
            "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-10-20",
            "description": "Filter created from this date (YYYY-MM-DD)"
          },
          {
            "name": "created_at_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-22",
            "description": "Filter created until this date (YYYY-MM-DD)"
          },
          {
            "name": "processed_at_from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-20",
            "description": "Filter processed from this date (YYYY-MM-DD)"
          },
          {
            "name": "processed_at_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-22",
            "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": 116,
                            "description": "Task identifier"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "completed",
                              "failed"
                            ],
                            "example": "pending",
                            "description": "Task status"
                          },
                          "processed_at": {
                            "type": "string",
                            "example": "2026-10-21T09:47:00Z",
                            "description": "Processing completion timestamp"
                          },
                          "created_at": {
                            "type": "string",
                            "example": "2026-10-21T09:47:00Z",
                            "description": "Task creation timestamp"
                          },
                          "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"
                          }
                        },
                        "required": [
                          "id",
                          "status",
                          "processed_at",
                          "created_at",
                          "total_numbers",
                          "completed_count",
                          "failed_count",
                          "pending_count"
                        ]
                      },
                      "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": 116,
                      "status": "pending",
                      "processed_at": "2026-10-21T09:47:00Z",
                      "created_at": "2026-10-21T09:47:00Z",
                      "total_numbers": 1,
                      "completed_count": 0,
                      "failed_count": 0,
                      "pending_count": 1
                    },
                    {
                      "id": 115,
                      "status": "completed",
                      "processed_at": "2026-10-21T09:47:00Z",
                      "created_at": "2026-10-21T09:47:00Z",
                      "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\n`risk_check_request.task_id` feeds numbers_risk_checks_index and numbers_risk_checks_logs (`task_ids`):\nthe task status and the per-number results.\n\n**Note:** Results are informational only. Use at your own discretion.\n",
        "tags": [
          "Risk Checks"
        ],
        "operationId": "numbers_risk_checks_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "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": {
                        "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-10-21T09:47:24Z",
                          "description": "Task creation timestamp"
                        },
                        "task_id": {
                          "type": "integer",
                          "example": 127,
                          "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 risk check task details"
                    }
                  },
                  "required": [
                    "risk_check_request"
                  ]
                },
                "example": {
                  "risk_check_request": {
                    "status": "pending",
                    "processed_at": null,
                    "created_at": "2026-10-21T09:47:24Z",
                    "task_id": 127,
                    "total_numbers": 2
                  }
                }
              }
            }
          },
          "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"
                    },
                    {
                      "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`logs[].task_id` feeds numbers_risk_checks_index (`task_ids`).\n",
        "tags": [
          "Risk Checks"
        ],
        "operationId": "numbers_risk_checks_logs",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "221,222",
            "description": "Filter logs by log IDs (comma-separated)"
          },
          {
            "name": "task_ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 132,
            "description": "Task IDs (comma-separated) from numbers_risk_checks_create, numbers_risk_checks_index"
          },
          {
            "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-10-20",
            "description": "Filter created from this date (YYYY-MM-DD)"
          },
          {
            "name": "created_at_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-22",
            "description": "Filter created until this date (YYYY-MM-DD)"
          },
          {
            "name": "processed_at_from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-20",
            "description": "Filter processed from this date (YYYY-MM-DD)"
          },
          {
            "name": "processed_at_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-22",
            "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": 214,
                            "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": 128,
                            "description": "Parent task identifier"
                          },
                          "processed_at": {
                            "type": "string",
                            "example": "2026-10-21T09:47:54Z",
                            "description": "Processing completion timestamp"
                          },
                          "created_at": {
                            "type": "string",
                            "example": "2026-10-21T09:47:54Z",
                            "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": 214,
                      "number": "79991234568",
                      "status": "completed",
                      "risk_level": "Low",
                      "category": null,
                      "task_id": 128,
                      "processed_at": "2026-10-21T09:47:54Z",
                      "created_at": "2026-10-21T09:47:54Z"
                    },
                    {
                      "id": 213,
                      "number": "79991234567",
                      "status": "completed",
                      "risk_level": "High",
                      "category": "SPAMMER",
                      "task_id": 128,
                      "processed_at": "2026-10-21T09:47:54Z",
                      "created_at": "2026-10-21T09:47:54Z"
                    }
                  ],
                  "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\nhlr_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`hlr_request.task_id` feeds hlr_history (`task_ids`).\n",
        "tags": [
          "HLR Lookups"
        ],
        "operationId": "hlr_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "numbers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of phone numbers in E.164 format (e.g. +14155552671)",
                    "example": []
                  }
                }
              }
            }
          }
        },
        "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-10-21T09:46:48Z",
                          "description": "Task creation timestamp"
                        },
                        "task_id": {
                          "type": "integer",
                          "example": 49,
                          "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-10-21T09:46:48Z",
                    "task_id": 49,
                    "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",
        "tags": [
          "HLR Lookups"
        ],
        "operationId": "hlr_history",
        "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), from hlr_create"
          },
          {
            "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-10-20",
            "description": "Filter created from this date (YYYY-MM-DD)"
          },
          {
            "name": "created_at_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-22",
            "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": 69,
                            "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": 51,
                            "description": "Parent task identifier"
                          },
                          "processed_at": {
                            "type": "string",
                            "example": "2026-10-21T09:47:32Z",
                            "description": "Processing completion timestamp"
                          },
                          "created_at": {
                            "type": "string",
                            "example": "2026-10-21T09:47:32Z",
                            "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,
                            "type": "string",
                            "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."
                          }
                        },
                        "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": 69,
                      "number": "12125551234",
                      "status": "completed",
                      "phone_type": "mobile",
                      "carrier": "Acme Telecom",
                      "mcc": "310",
                      "mnc": "260",
                      "ported": false,
                      "risky": false,
                      "country": "US",
                      "task_id": 51,
                      "processed_at": "2026-10-21T09:47:32Z",
                      "created_at": "2026-10-21T09:47:32Z",
                      "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`documents[].id` feeds documents_show, documents_update, documents_destroy and documents_files_download_file;\n`documents[].files[].role` feeds documents_files_download_file; `documents[].identity_id` feeds\nidentities_index. Full record: documents_show.\n",
        "tags": [
          "KYC Documents"
        ],
        "operationId": "documents_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "398,399",
            "description": "Filter documents by IDs (comma-separated)"
          },
          {
            "name": "identity_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 386,
            "description": "Filter documents by identity ID from identities_index, identities_create"
          },
          {
            "name": "approvement_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "approved",
                "rejected",
                "expired",
                "in review",
                "verified"
              ]
            },
            "example": "approved",
            "description": "Filter documents by approval status"
          },
          {
            "name": "upload_date_from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-20T09:46:48Z",
            "description": "Filter documents created from this date"
          },
          {
            "name": "upload_date_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-10-22T09:46:48Z",
            "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": 395,
                            "description": "Document identifier"
                          },
                          "user_id": {
                            "type": "integer",
                            "example": 2503,
                            "description": "Owner user ID"
                          },
                          "country": {
                            "type": "string",
                            "example": "United Kingdom",
                            "description": "Country of the document, as given at upload; for a letter of intent, the country of the purchased number"
                          },
                          "created_at": {
                            "type": "string",
                            "example": "2026-10-21T09:46:47Z",
                            "description": "Upload timestamp"
                          },
                          "expired_at": {
                            "type": "string",
                            "example": "2027-10-21T09:46:47Z",
                            "description": "Document expiration timestamp"
                          },
                          "approvement_status": {
                            "type": "string",
                            "enum": [
                              "in review",
                              "verified",
                              "rejected",
                              "expired"
                            ],
                            "example": "verified",
                            "description": "Document approval status (in review = pending, verified = approved)"
                          },
                          "doc_type": {
                            "type": "string",
                            "enum": [
                              "Personal ID",
                              "Proof of address",
                              "Business Registration",
                              "Letter of Intent"
                            ],
                            "example": "Proof of address",
                            "description": "Document type identifier"
                          },
                          "identity_id": {
                            "type": "integer",
                            "example": 385,
                            "description": "Associated identity ID"
                          },
                          "identity": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "example": 385,
                                "description": "Identity identifier"
                              },
                              "name": {
                                "type": "string",
                                "example": "Paper Box 1",
                                "description": "Identity name"
                              },
                              "user_id": {
                                "type": "integer",
                                "example": 2503,
                                "description": "Owner user ID"
                              },
                              "created_at": {
                                "type": "string",
                                "example": "2026-10-21T09:46:47Z",
                                "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"
                          },
                          "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/395/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",
                          "expired_at",
                          "approvement_status",
                          "doc_type",
                          "identity_id",
                          "identity",
                          "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": 395,
                      "user_id": 2503,
                      "country": "United Kingdom",
                      "created_at": "2026-10-21T09:46:47Z",
                      "expired_at": "2027-10-21T09:46:47Z",
                      "approvement_status": "verified",
                      "doc_type": "Proof of address",
                      "identity_id": 385,
                      "identity": {
                        "id": 385,
                        "name": "Paper Box 1",
                        "user_id": 2503,
                        "created_at": "2026-10-21T09:46:47Z",
                        "persistence_status": "active",
                        "is_default": false
                      },
                      "files": [
                        {
                          "role": "frontside",
                          "label": "File",
                          "url": "/api/v2/documents/395/files/frontside",
                          "name": "test.png"
                        }
                      ]
                    },
                    {
                      "name": "Document 2",
                      "id": 396,
                      "user_id": 2503,
                      "country": "United Kingdom",
                      "created_at": "2026-10-21T09:46:47Z",
                      "expired_at": "2027-10-21T09:46:47Z",
                      "approvement_status": "verified",
                      "doc_type": "Proof of address",
                      "identity_id": 385,
                      "identity": {
                        "id": 385,
                        "name": "Paper Box 1",
                        "user_id": 2503,
                        "created_at": "2026-10-21T09:46:47Z",
                        "persistence_status": "active",
                        "is_default": false
                      },
                      "files": [
                        {
                          "role": "frontside",
                          "label": "File",
                          "url": "/api/v2/documents/396/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- `business_registration` - Business Registration\n- `letter_of_intent` - Letter of Intent\n\n**File Requirements:**\n- Allowed extensions: jpg, jpeg, png, pdf\n- Accepted MIME types: [\"image/jpeg\", \"image/png\", \"application/pdf\"]\n\n`document_id` feeds documents_show, documents_update, documents_destroy and documents_files_download_file;\n`document.files[].role` feeds documents_files_download_file.\n",
        "tags": [
          "KYC Documents"
        ],
        "operationId": "documents_create",
        "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",
                      "business_registration",
                      "letter_of_intent"
                    ],
                    "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, from identities_index, identities_create",
                    "example": 392
                  },
                  "document[country]": {
                    "type": "string",
                    "description": "Country name from documents_countries, e.g. `United Kingdom`; a code such as `UK` or `GB` is refused. For `letter_of_intent` the country of the purchased number is stored instead",
                    "example": "United Kingdom"
                  }
                },
                "required": [
                  "document[name]",
                  "document[doc_type]",
                  "document[files][frontside]",
                  "document[identity_id]",
                  "document[country]"
                ]
              }
            }
          }
        },
        "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": 403,
                      "description": "Created document ID"
                    },
                    "document": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "Test Document",
                          "description": "Document name"
                        },
                        "id": {
                          "type": "integer",
                          "example": 403,
                          "description": "Document identifier"
                        },
                        "user_id": {
                          "type": "integer",
                          "example": 2527,
                          "description": "Owner user ID"
                        },
                        "country": {
                          "type": "string",
                          "example": "United Kingdom",
                          "description": "Country of the document, as given at upload; for a letter of intent, the country of the purchased number"
                        },
                        "created_at": {
                          "type": "string",
                          "example": "2026-10-21T09:46:52Z",
                          "description": "Upload timestamp"
                        },
                        "expired_at": {
                          "nullable": true,
                          "description": "Document expiration timestamp"
                        },
                        "approvement_status": {
                          "type": "string",
                          "enum": [
                            "in review",
                            "verified",
                            "rejected",
                            "expired"
                          ],
                          "example": "in review",
                          "description": "Document approval status (in review = pending, verified = approved)"
                        },
                        "doc_type": {
                          "type": "string",
                          "enum": [
                            "Personal ID",
                            "Proof of address",
                            "Business Registration",
                            "Letter of Intent"
                          ],
                          "example": "Personal ID",
                          "description": "Document type identifier"
                        },
                        "identity_id": {
                          "type": "integer",
                          "example": 388,
                          "description": "Associated identity ID"
                        },
                        "identity": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "integer",
                              "example": 388,
                              "description": "Identity identifier"
                            },
                            "name": {
                              "type": "string",
                              "example": "Paper Box 4",
                              "description": "Identity name"
                            },
                            "user_id": {
                              "type": "integer",
                              "example": 2527,
                              "description": "Owner user ID"
                            },
                            "created_at": {
                              "type": "string",
                              "example": "2026-10-21T09:46: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"
                        },
                        "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",
                        "expired_at",
                        "approvement_status",
                        "doc_type",
                        "identity_id",
                        "identity",
                        "files"
                      ],
                      "description": "Created document details"
                    }
                  },
                  "required": [
                    "message",
                    "document_id",
                    "document"
                  ]
                },
                "example": {
                  "message": "Document created",
                  "document_id": 403,
                  "document": {
                    "name": "Test Document",
                    "id": 403,
                    "user_id": 2527,
                    "country": "United Kingdom",
                    "created_at": "2026-10-21T09:46:52Z",
                    "expired_at": null,
                    "approvement_status": "in review",
                    "doc_type": "Personal ID",
                    "identity_id": 388,
                    "identity": {
                      "id": 388,
                      "name": "Paper Box 4",
                      "user_id": 2527,
                      "created_at": "2026-10-21T09:46:52Z",
                      "persistence_status": "active",
                      "is_default": false
                    },
                    "files": [
                      {
                        "role": "frontside",
                        "label": "Frontside",
                        "url": "/api/v2/documents/403/files/frontside",
                        "name": "test.png"
                      },
                      {
                        "role": "backside",
                        "label": "Backside",
                        "url": "/api/v2/documents/403/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": {
                  "malformed_document": {
                    "value": {
                      "errors": {
                        "document": [
                          "is missing or malformed"
                        ]
                      }
                    }
                  },
                  "field_validation": {
                    "value": {
                      "errors": {
                        "name": [
                          "Required"
                        ],
                        "country": [
                          "Is missing"
                        ],
                        "backside": [
                          "Required"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/documents/{id}": {
      "get": {
        "summary": "Get document",
        "description": "Get a document by ID.\n\n`document.files[].role` feeds documents_files_download_file; `document.identity_id` feeds identities_index.\nRows: documents_index.\n",
        "tags": [
          "KYC Documents"
        ],
        "operationId": "documents_show",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 442,
            "description": "Document ID from documents_index, documents_create"
          }
        ],
        "responses": {
          "200": {
            "description": "returns the document details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "Test Document 85094c58",
                          "description": "Document name"
                        },
                        "id": {
                          "type": "integer",
                          "example": 440,
                          "description": "Document identifier"
                        },
                        "user_id": {
                          "type": "integer"
                        },
                        "country": {
                          "type": "string",
                          "example": "United Kingdom",
                          "description": "Country of the document, as given at upload; for a letter of intent, the country of the purchased number"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "expired_at": {
                          "type": "string"
                        },
                        "approvement_status": {
                          "type": "string",
                          "enum": [
                            "in review",
                            "verified",
                            "rejected",
                            "expired"
                          ],
                          "example": "in review",
                          "description": "Document approval status (in review = pending, verified = approved)"
                        },
                        "doc_type": {
                          "type": "string",
                          "example": "Proof of address",
                          "description": "Document type identifier"
                        },
                        "identity_id": {
                          "nullable": true
                        },
                        "identity": {
                          "nullable": true
                        },
                        "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",
                        "expired_at",
                        "approvement_status",
                        "doc_type",
                        "identity_id",
                        "identity",
                        "files"
                      ]
                    }
                  },
                  "required": [
                    "document"
                  ]
                },
                "example": {
                  "document": {
                    "name": "Test Document 85094c58",
                    "id": 440,
                    "user_id": 2711,
                    "country": "United Kingdom",
                    "created_at": "2026-10-21T09:47:24Z",
                    "expired_at": "2026-10-31T09:47:24Z",
                    "approvement_status": "in review",
                    "doc_type": "Proof of address",
                    "identity_id": null,
                    "identity": null,
                    "files": [
                      {
                        "role": "frontside",
                        "label": "File",
                        "url": "/api/v2/documents/440/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"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update document",
        "description": "Update an existing document's name or identity.\n\n`document_id` feeds documents_show.\n",
        "tags": [
          "KYC Documents"
        ],
        "operationId": "documents_update",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 455,
            "description": "Document ID from documents_index, documents_create"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "document": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Updated document name",
                        "example": "Updated Name"
                      },
                      "identity_id": {
                        "type": "integer",
                        "description": "Updated identity ID from identities_index, identities_create",
                        "example": 442
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "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": 452,
                          "description": "Document identifier"
                        },
                        "user_id": {
                          "type": "integer",
                          "example": 2863,
                          "description": "Owner user ID"
                        },
                        "country": {
                          "type": "string",
                          "example": "United Kingdom",
                          "description": "Country of the document, as given at upload; for a letter of intent, the country of the purchased number"
                        },
                        "created_at": {
                          "type": "string",
                          "example": "2026-10-21T09:47:52Z",
                          "description": "Upload timestamp"
                        },
                        "expired_at": {
                          "type": "string",
                          "example": "2026-10-31T09:47:52Z",
                          "description": "Document expiration timestamp"
                        },
                        "approvement_status": {
                          "type": "string",
                          "enum": [
                            "in review",
                            "verified",
                            "rejected",
                            "expired"
                          ],
                          "example": "in review",
                          "description": "Document approval status (in review = pending, verified = approved)"
                        },
                        "doc_type": {
                          "type": "string",
                          "enum": [
                            "Personal ID",
                            "Proof of address",
                            "Business Registration",
                            "Letter of Intent"
                          ],
                          "example": "Personal ID",
                          "description": "Document type identifier"
                        },
                        "identity_id": {
                          "type": "integer",
                          "example": 437,
                          "description": "Associated identity ID"
                        },
                        "identity": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "integer",
                              "example": 437,
                              "description": "Identity identifier"
                            },
                            "name": {
                              "type": "string",
                              "example": "New Box",
                              "description": "Identity name"
                            },
                            "user_id": {
                              "type": "integer",
                              "example": 2863,
                              "description": "Owner user ID"
                            },
                            "created_at": {
                              "type": "string",
                              "example": "2026-10-21T09:47: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"
                        },
                        "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",
                        "expired_at",
                        "approvement_status",
                        "doc_type",
                        "identity_id",
                        "identity",
                        "files"
                      ],
                      "description": "Updated document details"
                    }
                  },
                  "required": [
                    "message",
                    "document_id",
                    "document"
                  ]
                },
                "example": {
                  "message": "Document updated",
                  "document_id": 452,
                  "document": {
                    "name": "Updated Name",
                    "id": 452,
                    "user_id": 2863,
                    "country": "United Kingdom",
                    "created_at": "2026-10-21T09:47:52Z",
                    "expired_at": "2026-10-31T09:47:52Z",
                    "approvement_status": "in review",
                    "doc_type": "Personal ID",
                    "identity_id": 437,
                    "identity": {
                      "id": 437,
                      "name": "New Box",
                      "user_id": 2863,
                      "created_at": "2026-10-21T09:47:52Z",
                      "persistence_status": "active",
                      "is_default": false
                    },
                    "files": [
                      {
                        "role": "frontside",
                        "label": "File",
                        "url": "/api/v2/documents/452/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",
        "tags": [
          "KYC Documents"
        ],
        "operationId": "documents_destroy",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 393,
            "description": "Document ID from documents_index, documents_create"
          }
        ],
        "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"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/documents/countries": {
      "get": {
        "summary": "List document countries",
        "description": "List the country names a document can be uploaded for.\n\nThe name is the exact value documents_create takes in `document[country]`; a code such as `UK` or `GB` is\nrefused. Narrow the list by part of the name with `name_contains`.\n\n`countries[].name` feeds documents_create.\n",
        "tags": [
          "KYC Documents"
        ],
        "operationId": "documents_countries",
        "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, as documents_create takes it in `document[country]`"
                          }
                        },
                        "required": [
                          "name"
                        ]
                      },
                      "description": "Countries a document can be uploaded for"
                    }
                  },
                  "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",
        "tags": [
          "KYC Documents"
        ],
        "operationId": "documents_files_download_file",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 451,
            "description": "Document ID from documents_index, documents_show, documents_create"
          },
          {
            "name": "role",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "frontside",
                "backside"
              ]
            },
            "example": "frontside",
            "description": "File role, `files[].role` from documents_index, documents_show, documents_create"
          }
        ],
        "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`identities[].id` feeds documents_index, documents_create, documents_update, identities_destroy and\nnumbers_purchase_update. When `documents_count` is above zero, documents_index lists those documents\nby `identity_id`.\n",
        "tags": [
          "Identities"
        ],
        "operationId": "identities_index",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "425,426",
            "description": "Filter identities by IDs (comma-separated); `identity_id` from documents_index, documents_show"
          },
          {
            "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-10-20T09:47:30Z",
            "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-10-22T09:47:30Z",
            "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": 420,
                            "description": "Identity identifier"
                          },
                          "name": {
                            "type": "string",
                            "example": "Box 1",
                            "description": "Identity name"
                          },
                          "user_id": {
                            "type": "integer",
                            "example": 2734,
                            "description": "Owner user ID"
                          },
                          "created_at": {
                            "type": "string",
                            "example": "2026-10-21T09:47:29Z",
                            "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": 420,
                      "name": "Box 1",
                      "user_id": 2734,
                      "created_at": "2026-10-21T09:47:29Z",
                      "persistence_status": "active",
                      "is_default": false,
                      "documents_count": 2
                    },
                    {
                      "id": 421,
                      "name": "Box 2",
                      "user_id": 2734,
                      "created_at": "2026-10-21T09:47:29Z",
                      "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`identity.id` feeds documents_index, documents_create, documents_update, identities_destroy and\nnumbers_purchase_update. Rows: identities_index.\n",
        "tags": [
          "Identities"
        ],
        "operationId": "identities_create",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "identity": {
                    "type": "object",
                    "properties": {
                      "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": 433,
                      "description": "Created identity ID"
                    },
                    "identity": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 433,
                          "description": "Identity identifier"
                        },
                        "name": {
                          "type": "string",
                          "example": "New Box",
                          "description": "Identity name"
                        },
                        "user_id": {
                          "type": "integer",
                          "example": 2829,
                          "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": 433,
                  "identity": {
                    "id": 433,
                    "name": "New Box",
                    "user_id": 2829,
                    "created_at": "2026-10-21T09:47:45Z",
                    "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",
        "tags": [
          "Identities"
        ],
        "operationId": "identities_destroy",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 447,
            "description": "Identity ID from identities_index, identities_create"
          }
        ],
        "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": 443,
                      "description": "Archived identity ID"
                    }
                  },
                  "required": [
                    "message",
                    "identity_id"
                  ]
                },
                "example": {
                  "message": "Identity deleted",
                  "identity_id": 443
                }
              }
            }
          },
          "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",
          "amd_status",
          "amd_score",
          "hangup_cause"
        ],
        "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"
          },
          "amd_status": {
            "type": "string",
            "nullable": true,
            "description": "Answering machine detection (AMD) verdict of an outbound call:\n- `machine` — AMD detected an answering machine\n- `human` — AMD detected a person\n- `notsure` — AMD ran but could not tell a machine from a person, for example on silence, unclear audio or a timeout\n\n`null` when no AMD result was recorded for the call, which is always the case for incoming calls.\n",
            "example": "machine"
          },
          "amd_score": {
            "type": "integer",
            "nullable": true,
            "description": "Probability that an answering machine picked up, as a percentage from 0 to 100, as reported by the AMD detector.\nIt is not a confidence in `amd_status`, and it carries no meaning when `amd_status` is `notsure`.\n`null` whenever `amd_status` is `null`.\n",
            "example": 93
          },
          "hangup_cause": {
            "type": "string",
            "nullable": true,
            "enum": [
              "AMD_MACHINE",
              "NORMAL_CLEARING",
              "NO_ANSWER",
              "BUSY",
              "FAILED",
              null
            ],
            "description": "How the call ended:\n- `AMD_MACHINE` — AMD detected an answering machine; takes precedence over the other values\n- `NORMAL_CLEARING` — the call was answered\n- `NO_ANSWER` — nobody answered, including calls the caller cancelled before an answer\n- `BUSY` — the called party was busy\n- `FAILED` — the call could not be connected\n\n`null` for calls made before hangup causes were recorded, for calls whose outcome the platform did not recognise,\nand for API calls that never reached the destination number.\n",
            "example": "NORMAL_CLEARING"
          }
        }
      },
      "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": "API Access",
      "x-version": "v1"
    },
    {
      "name": "Account Balance",
      "x-version": "v1"
    },
    {
      "name": "Calls",
      "x-version": "v1"
    },
    {
      "name": "Click2Call",
      "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"
    }
  ]
}
