---
openapi: 3.0.3
info:
  title: Get Started
  version: 1.0.0
  description: |
    ### Overview

    Welcome 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.

    ### API Versions

    We currently maintain two API versions. These versions are **interoperable** and should be used together to access the full range of didlogic services.

    #### API v1: Core Infrastructure

    The v1 API handles the foundational elements of your account and legacy connectivity services. Use this for:

    - **Billing & Finance:** Account balance, transaction history, and CSV exports.
    - **Voice Logs:** Call Detail Records (CDR) with advanced filtering.
    - **Messaging:** Standard SMS messaging services.
    - **Provisioning:** Basic SIP account management and ASR (Answer-Seizure Ratio) reporting.

    #### API v2: Enhanced DID Management

    The v2 API provides a more modern, granular interface for managing your global number inventory. Use this for:

    - **Number Purchase:** Search, browse, and purchase numbers by country, region, or city.
    - **Inventory Control:** Browse your purchased numbers.
    - **Compliance:** Upload and manage regulatory documents required for specific jurisdictions.
    - **Number Reputation Control:** Request risk checks for specific numbers to see whether they have any spam/scam flags and access risk check reports.

    ### Identifier interoperability (v1 ↔ v2)

    The same DID is addressable two ways: by its **phone number** on the v1
    number-keyed endpoints, and by its numeric **inventory id** on v2 `GET /api/v2/numbers`.
    So you don't get a 404 when you carry an id learned from v2 back to a v1 path,
    the v1 number-keyed endpoints now **also accept the inventory id**:

    - `GET/POST /api/v1/purchases/{purchase_id}/destinations` and
      `PUT/DELETE /api/v1/purchases/{purchase_id}/destinations/{id}` — `purchase_id`
      accepts the DID phone number (e.g. `43800327987`) **or** the v2 inventory id
      (e.g. `21869`).
    - `GET/PUT/DELETE /api/v1/sipaccounts/{id}` and
      `GET/POST/DELETE /api/v1/sipaccounts/{sipaccount_id}/allowed_ips` — the identifier
      accepts the SIP account **name** (e.g. `97653`) **or** its numeric **id** (e.g. `73`).

    Both forms resolve the same record; nothing about the existing name/number calls
    changes. A value that matches neither returns the standard `404` error envelope
    (`{"errors":{"base":["data not found"]}}`).

    Regulatory **documents** under v2 are the one exception — they stay split by
    design: the collection is addressed by the DID number
    (`GET /api/v2/numbers/documents?number=`) and a single document by its own id
    (`.../documents/{id}`). A number cannot pick one of many documents, and a document
    id cannot stand in for the collection, so dual-accept does not apply there.

    ### Authentication

    To ensure the security of your account, all requests to both v1 and v2 endpoints must be authenticated using **Bearer Token Authentication**.
    Include your token in the `Authorization` header of every HTTP request.

    > **Header Format:** `Authorization: Bearer YOUR_TOKEN`

    | | |
    |---|---|
    | **Security Scheme Type** | HTTP |
    | **HTTP Authorization Scheme** | bearer |
    | **Transport** | HTTPS (Required) |

    Please contact your account manager to access your API key.

    #### Example

    ```bash
    curl -X GET "https://api.didlogic.com/v2/numbers" \
         -H "Authorization: Bearer YOUR_TOKEN" \
         -H "Content-Type: application/json"
    ```
servers:
- url: https://app.didlogic.com
  description: Production
paths:
  "/api/v1/balance":
    get:
      summary: Get account balance
      description: |
        Retrieve the current account balance for the authenticated user.

        **Balance Representation:**
        - Returns balance in account currency (typically USD)
        - Value is rounded to 2 decimal places
        - Supports both JSON and plain text formats

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Account Balance
      responses:
        '200':
          description: Successfully returns account balance in JSON format with 2
            decimal places
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
                    format: float
                    example: 123.45
                    description: Current account balance rounded to 2 decimal places
                required:
                - balance
              examples:
                successfully_returns_account_balance_as_plain_text_string:
                  summary: Successfully returns account balance as plain text string
                  value: '123.45'
                successfully_returns_account_balance_in_json_format_with_2_decimal_places:
                  summary: Successfully returns account balance in JSON format with
                    2 decimal places
                  value:
                    balance: 123.45
            text/plain:
              schema:
                type: string
              example: '123.45'
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
      security:
      - BearerAuth: []
  "/api/v1/calls":
    get:
      summary: Retrieve call detail records
      description: |
        Retrieve a list of call detail records (CDR) with filtering and pagination options.

        **Important notes:**
        - Results can be filtered by date range, call type, phone numbers, and SIP account
        - Supports both JSON and CSV export formats
        - Use pagination for large result sets
        - Statistics include total count, duration, and cost

        **When to use:**
        - Generating call history reports
        - Analyzing call patterns and costs
        - Exporting billing data
        - Monitoring SIP account usage
      tags:
      - Calls
      security:
      - BearerAuth: []
      parameters:
      - name: type
        in: query
        description: Filter by call type (sip = outbound SIP calls, web = outbound
          web calls, api = outbound API calls, incoming = received calls)
        required: false
        schema:
          type: string
          enum:
          - sip
          - web
          - incoming
          - api
        example: sip
      - name: missed
        in: query
        description: Include missed calls in results (0 = exclude, 1 = include)
        required: false
        schema:
          type: string
          enum:
          - '0'
          - '1'
        example: '1'
      - name: from_search
        in: query
        description: Filter by caller phone number (partial match supported)
        required: false
        schema:
          type: string
        example: '1221'
      - name: to_search
        in: query
        description: Filter by destination phone number (partial match supported)
        required: false
        schema:
          type: string
        example: '1800'
      - name: filter
        in: query
        description: Filter by phone number (alphanumeric, spaces, hyphens, underscores)
        required: false
        schema:
          type: string
          pattern: "^[a-zA-Z0-9 \\-_]+$"
        example: "+14155551234"
      - name: sip_account
        in: query
        description: Filter by SIP account/device identifier
        required: false
        schema:
          type: string
        example: '36465'
      - name: from
        in: query
        description: Start date for filtering (inclusive). Format YYYY-MM-DD
        required: false
        schema:
          type: string
          format: date
        example: '2025-01-01'
      - name: to
        in: query
        description: End date for filtering (inclusive). Format YYYY-MM-DD
        required: false
        schema:
          type: string
          format: date
        example: '2025-01-31'
      - name: all
        in: query
        description: Return all records (ignores pagination). Use with caution for
          large datasets.
        required: false
        schema:
          type: boolean
          default: false
        example: false
      - name: page
        in: query
        description: Page number to retrieve (1-based)
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
      - name: per_page
        in: query
        description: Number of records per page (max 1000)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
        example: 100
      responses:
        '200':
          description: Successfully retrieved CDR records
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CdrListResponse"
              example:
                calls:
                - timestamp: '2024-01-15T10:30:00Z'
                  type: sip
                  amount: 0.05
                  duration: 120
                  from: '100'
                  to: "+14155551234"
                  destination_name: United States
                  sip_account: john@sip.provider.com
                  per_minute: 0.025
                - timestamp: '2024-01-15T10:30:00Z'
                  type: incoming
                  amount: 0.02
                  duration: 90
                  from: "+14155551234"
                  to: '100'
                  did_number: "+18005551234"
                - timestamp: '2024-01-15T10:35:00Z'
                  type: incoming
                  amount: 0.0
                  duration: 0
                  from: "+14155559999"
                  to: '100'
                  did_number: "+18005551234"
                - timestamp: '2024-01-15T10:30:00Z'
                  type: web
                  amount: 0.03
                  duration: 60
                  from: web_user_123
                  to: "+14155551234"
                pagination:
                  page: 1
                  per_page: 10
                  total_pages: 325
                  total_records: 3248
            text/csv:
              schema:
                type: string
                description: |
                  CSV formatted call detail records.

                  Columns: Date, Time, SIP ID, Type, From, To, Destination name, Duration, DID inc. fee, Termination, Charge, Balance
              example: |
                Date,Time,SIP ID,Type,From,To,Destination name,Duration,DID inc. fee,Termination,Charge,Balance
                01/15/24,10:30:00 am,john@sip.com,SIP TERM,100,+14155551234,United States,120,0.00000,0.02500,0.05000,99.95000
        '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.

        **Response includes:**
        - Placed calls: total cost and count
        - Received calls: total cost and count
        - Missed calls: count only
        - All calls: combined total cost and count

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Calls
      security:
      - BearerAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-01'
        description: Start date for filtering (YYYY-MM-DD)
      - name: to
        in: query
        required: false
        schema:
          type: string
        example: '2024-12-31'
        description: End date for filtering (YYYY-MM-DD)
      - name: sipfriend
        in: query
        required: false
        schema:
          type: integer
        example: 458
        description: Filter by SIP friend ID
      - name: search
        in: query
        required: false
        schema:
          type: integer
        example: 1234567890
        description: Search term for filtering calls
      responses:
        '200':
          description: returns call statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  placed:
                    type: object
                    properties:
                      total:
                        type: string
                        example: "$15.0000"
                        description: Total cost of placed calls
                      count:
                        type: integer
                        example: 0
                        description: Number of placed calls
                    required:
                    - total
                    - count
                    description: Statistics for placed (outgoing) calls
                  received:
                    type: object
                    properties:
                      total:
                        type: string
                        example: "$20.0000"
                        description: Total cost of received calls
                      count:
                        type: integer
                        example: 0
                        description: Number of received calls
                    required:
                    - total
                    - count
                    description: Statistics for received (incoming) calls
                  missed:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 0
                        description: Number of missed calls
                    required:
                    - count
                    description: Statistics for missed calls
                  all:
                    type: object
                    properties:
                      total:
                        type: string
                        example: "$35.0000"
                        description: Total cost of all calls
                      count:
                        type: integer
                        example: 0
                        description: Total number of all calls
                    required:
                    - total
                    - count
                    description: Combined statistics for all calls
                required:
                - placed
                - received
                - missed
                - all
              example:
                placed:
                  total: "$15.0000"
                  count: 0
                received:
                  total: "$20.0000"
                  count: 0
                missed:
                  count: 0
                all:
                  total: "$35.0000"
                  count: 0
        '403':
          description: returns forbidden error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
  "/api/v1/calls/recording/{callid}":
    get:
      summary: Download call recordings
      description: |
        Retrieves a single call recording file by its Call ID.

        > ⚠️ **Important:** this endpoint is a fallback mechanism designed for
        > recovering missing recordings when a delivery webhook failed or its
        > short-lived URL expired. For production workflows, always use
        > [Call Recording Webhooks](https://docs.didlogic.com/docs/guides/apps-developer-tools/webhooks)
        > instead of polling this API.

        The Call ID is all you need — the recording is searched for across the
        whole period your account retains recordings, so a client that stored only
        the Call ID can download the file.

        ### Rate limits & quotas

        To prevent system overload, strict limits are enforced per user:

        - **Request frequency:** max 1 request per second.
        - **Recording lookups:** max 1 lookup per minute.

        The per-minute quota is consumed by every search query, regardless of
        whether a recording is found or the request returns `404 Not Found` —
        searching for the file is the operation that costs resources.

        ### Authentication

        Requires a Bearer token in the Authorization header:
        `Authorization: Bearer <token>`
      tags:
      - Calls
      security:
      - BearerAuth: []
      parameters:
      - name: callid
        in: path
        required: true
        schema:
          type: string
        example: raw.call-id-1@example.com
        description: Call ID of the recording (required). Inbound callids are the
          encrypted webhook value.
      responses:
        '302':
          description: Redirects to a short-lived AWS S3 pre-signed URL for the recording
            (`.mp3`). Follow the redirect — for example with `curl -L` — to download
            the file.
          content:
            text/html:
              schema:
                type: string
              example: ''
        '403':
          description: The API token is missing or invalid, or call recording is not
            enabled for this account.
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    error:
                      type: string
                  required:
                  - error
              examples:
                Unauthorized:
                  value:
                    error: Unauthorized
                Recording disabled:
                  value:
                    errors:
                      base:
                      - call recording is not enabled for your account
        '404':
          description: No recording matches this Call ID. The call does not exist,
            belongs to another account, or is older than the account's recording retention
            period.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
        '429':
          description: A rate limit was exceeded — either the one-request-per-second
            frequency limit or the one-lookup-per-minute quota. Carries `Retry-After`
            with the seconds to wait, alongside `X-RateLimit-Limit`, `X-RateLimit-Remaining`
            and `X-RateLimit-Reset`.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              examples:
                Lookup quota exceeded:
                  value:
                    errors:
                      base:
                      - Recording lookup limit reached. Maximum 1 lookup per minute
                        is allowed. Please use a webhook for production workflows.
                Too many requests:
                  value:
                    errors:
                      base:
                      - Recording lookup limit reached. Maximum 1 request per second
                        is allowed.
  "/api/v1/asr_report":
    get:
      summary: Get ASR (Answer-Seizure Ratio) report
      description: |
        Retrieve the Answer-Seizure Ratio (ASR) report in CSV format for specified date range.

        **ASR Metrics:**
        - Number of calls
        - Talk time in minutes
        - ASR: Percentage of calls successfully connected
        - Average call duration (ACD)

        **Requirements:**
        - Date range is required (start_date and end_date)
        - Dates must be in YYYY-MM-DD format
        - On success returns CSV; 400 and 403 errors return JSON

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Reports
      parameters:
      - name: start_date
        in: query
        required: true
        schema:
          type: string
        example: '2024-01-01'
        description: Report start date (YYYY-MM-DD format)
      - name: end_date
        in: query
        required: true
        schema:
          type: string
        example: '2024-12-31'
        description: Report end date (YYYY-MM-DD format)
      responses:
        '200':
          description: Successfully returns ASR metrics report in CSV format
          content:
            text/csv:
              schema:
                type: string
              example: 'Country,Minutes,Calls,ASR,ACD

                '
        '400':
          description: Returns 400 error when end_date or start_date parameter is
            missing
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - start_date and end_date are required
        '403':
          description: Returns 403 error when the API token is incorrect or the account
            is not permitted to export the ASR report
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    error:
                      type: string
                  required:
                  - error
              examples:
                returns_403_error_when_the_api_token_is_incorrect:
                  summary: Returns 403 error when the API token is incorrect
                  value:
                    error: Unauthorized
                returns_403_error_when_the_api_token_is_incorrect_or_the_account_is_not_permitted_to_export_the_asr_report:
                  summary: Returns 403 error when the API token is incorrect or the
                    account is not permitted to export the ASR report
                  value:
                    errors:
                      base:
                      - ASR report export is not permitted for this account
      security:
      - BearerAuth: []
  "/api/v1/transactions":
    get:
      summary: Export transaction history
      description: |
        Export account transaction history as a CSV file for a date range and
        transaction type(s).

        **Requirements:**
        - start_date, end_date and type are all required
        - Dates must be in YYYY-MM-DD format
        - `type` accepts one or more comma-separated values from the list below

        **Transaction types:** adjustments, paypal_in, paypal_out, cc_in, stripe_in,
        google_pay_in, apple_pay_in, wire_transfer, call, call_fix_fee, connection,
        sip, webcall, sms, inbound_sms, activation, month, subscription, porting,
        surcharge, risk_check, call_recording, hlr_lookup, amd, channel

        **Response:** The caller receives the generated CSV payload. The internal
        redirect used to fetch that file is an implementation detail and is not
        part of the public contract.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Reports
      parameters:
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2024-01-01'
        example: '2024-01-01'
        description: Start of the reporting period (YYYY-MM-DD)
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2024-01-31'
        example: '2024-01-31'
        description: End of the reporting period (YYYY-MM-DD)
      - name: type
        in: query
        required: true
        schema:
          type: string
          example: call
        example: call
        description: Comma-separated transaction type(s); see the operation description
          for the full list of accepted values.
      responses:
        '200':
          description: Returns the generated transactions CSV file
          content:
            text/csv:
              schema:
                type: string
              example: |
                Date,Time,Transaction type,Comment,Amount,Balance,Status
                2024-01-15,10:30,call,Sample call charge,-1.23,98.77,completed
        '400':
          description: Returns 400 with the JSON error envelope when required params
            are missing or malformed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - start_date, end_date and type are required
        '403':
          description: Returns 403 error when the API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
      security:
      - BearerAuth: []
  "/api/v1/purchases":
    get:
      summary: List purchased DID numbers
      description: |
        Retrieve a paginated list of DID numbers purchased by the authenticated user.

        **Features:**
        - Ordered by most recent first
        - Pagination: 100 DIDs per page (max 1000)
        - Available in JSON and CSV formats

        **Returned Information:**
        - DID number and status
        - Purchase and expiration dates
        - Monthly cost and features
        - SMS/voice capabilities

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Purchases
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
        description: Page number for pagination (starts from 1)
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 10
        description: Number of items per page
      responses:
        '200':
          description: Successfully returns paginated list of purchased DID numbers
            in JSON format
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchases:
                    type: array
                    items:
                      type: object
                      properties:
                        number:
                          type: string
                          example: '1234567890'
                          description: DID phone number
                        channels:
                          type: integer
                          example: 1
                          description: Number of channels
                        country:
                          type: string
                          example: Fake country for 1234567890
                          description: DID country
                        area:
                          type: string
                          example: Fake city for 1234567890
                          description: DID area
                        codec:
                          nullable: true
                          description: Audio codec
                        activation:
                          type: number
                          format: float
                          example: 1.17
                          description: Activation fee
                        monthly_fee:
                          type: number
                          format: float
                          example: 1.17
                          description: Monthly cost for the DID
                        per_minute:
                          type: number
                          format: float
                          example: 0.117
                          description: Per minute rate
                        check_state:
                          type: string
                          example: active
                          description: DID status
                        free_minutes:
                          type: integer
                          example: 0
                          description: Free minutes included
                      required:
                      - number
                      - channels
                      - country
                      - area
                      - codec
                      - activation
                      - monthly_fee
                      - per_minute
                      - check_state
                      - free_minutes
                    description: List of purchased DID numbers
                  pagination:
                    type: object
                    properties:
                      pages:
                        type: integer
                      page:
                        type: integer
                      total_records:
                        type: integer
                      per_page:
                        type: integer
                    required:
                    - pages
                    - page
                    - total_records
                    - per_page
                required:
                - purchases
                - pagination
              examples:
                returns_list_of_purchased_dids_in_csv_format_for_spreadsheet_import:
                  summary: Returns list of purchased DIDs in CSV format for spreadsheet
                    import
                  value: |
                    Number,Channels,Country,Area,Check state,Codec,Free minutes,Activation,Monthly fee,Per minute,Paid until,Minutes,Destination
                    1234567890,1,Fake country for 1234567890,Fake city for 1234567890,active,,0,1.1700,1.1700,0.1170,,00:00,""
                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:
                      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
                1234567890,1,Fake country for 1234567890,Fake city for 1234567890,active,,0,1.1700,1.1700,0.1170,,00:00,""
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
      security:
      - BearerAuth: []
  "/api/v1/purchases/{purchase_id}/destinations":
    get:
      summary: List destinations
      description: |
        Retrieve the list of inbound destinations configured for a specific DID number.

        **Destinations** define where incoming calls to a DID should be routed (SIP addresses, phone numbers, etc.).

        **Features:**
        - Returns only current (non-deleted) destinations
        - Each destination includes active status and its dialing mode (`dialing_type`, with the legacy `callhunt` mirror)

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Inbound Destinations
      parameters:
      - name: purchase_id
        in: path
        required: true
        schema:
          type: string
          example: '43800327987'
        example: '43800327987'
        description: DID identifier — the phone **number** (e.g. `43800327987`) or
          the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g.
          `21869`). Both resolve the same DID.
      responses:
        '200':
          description: Successfully returns all current destinations for the specified
            DID
          content:
            application/json:
              schema:
                type: object
                properties:
                  destination:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 287
                          description: Destination ID
                        destination:
                          type: string
                          example: sip:test@example.com
                          description: Forwarding target
                        priority:
                          type: integer
                          example: 1
                          description: Destination priority
                        callhunt:
                          type: boolean
                          description: Whether callhunt is enabled
                        active:
                          type: boolean
                          example: true
                          description: Whether destination is active
                        transport:
                          type: integer
                          enum:
                          - 1
                          - 4
                          - 5
                          - 10
                          example: 1
                          description: Transport type
                        ai_agent_id:
                          nullable: true
                          type: integer
                          description: Linked AI agent ID (null when the destination
                            is not an AI agent)
                        ai_agent_name:
                          nullable: true
                          type: string
                          description: Linked AI agent name (null when the destination
                            is not an AI agent)
                        dialing_type:
                          type: string
                          enum:
                          - sequence
                          - ring_all
                          - random
                          example: sequence
                          description: 'Dialing mode of the group this destination
                            belongs to: `sequence` tries it alone, `ring_all` dials
                            the whole group at once, `random` picks group members
                            in a random order. Mirrors `callhunt` (`ring_all` maps
                            to true).'
                      required:
                      - id
                      - destination
                      - priority
                      - callhunt
                      - active
                      - transport
                      - ai_agent_id
                      - ai_agent_name
                    description: List of destinations
                required:
                - destination
              example:
                destination:
                - id: 287
                  transport: 1
                  destination: sip:test@example.com
                  priority: 1
                  callhunt: false
                  dialing_type: sequence
                  active: true
                  ai_agent_id:
                  ai_agent_name:
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope {"errors":{"base":["data not
            found"]}} when neither the DID phone number nor its inventory id matches
            a DID you own.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
      security:
      - BearerAuth: []
    post:
      summary: Create destination
      description: |
        Add a new inbound destination for a DID number.

        **Destination Types:**
        - SIP addresses (e.g., `sip:user@domain.com`)
        - Phone numbers (e.g., `18005551234`)
        - Extensions (SIP accounts created within didlogic)

        **Parameters:**
        - `destination` - The forwarding target (SIP URI or phone number)
        - `dialing_type` - Dialing mode: `sequence`, `ring_all` or `random`
        - `callhunt` - Legacy two-state mirror of `dialing_type` (boolean); ignored when `dialing_type` is sent
        - `active` - Enable/disable this destination (boolean)
        - `transport` - Transport type code (1 = SIP URI, 4 = Phone number, 5 = SIP device, 10 = Webphone)

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Inbound Destinations
      parameters:
      - name: purchase_id
        in: path
        required: true
        schema:
          type: string
          example: '43800327987'
        example: '43800327987'
        description: DID identifier — the phone **number** (e.g. `43800327987`) or
          the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g.
          `21869`). Both resolve the same DID.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                destination[destination]:
                  type: string
                  description: Forwarding target (SIP URI or phone number)
                  example: sip:test@example.com
                destination[callhunt]:
                  type: string
                  description: Enable callhunt (ring all). Ignored when `destination[dialing_type]`
                    is sent.
                  example: 'false'
                destination[active]:
                  type: string
                  description: Activate this destination
                  example: 'true'
                destination[transport]:
                  type: string
                  description: Transport type (1=SIP URI, 4=Phone number, 5=SIP device,
                    10=Webphone)
                  enum:
                  - '1'
                  - '4'
                  - '5'
                  - '10'
                  example: '1'
                destination[dialing_type]:
                  type: string
                  description: 'Dialing mode of the group this destination belongs
                    to: `sequence` tries it alone, `ring_all` dials the whole group
                    at once, `random` picks group members in a random order. Mirrors
                    `callhunt` (`ring_all` maps to true). Takes precedence over `callhunt`.'
                  enum:
                  - sequence
                  - ring_all
                  - random
              required:
              - destination[destination]
      responses:
        '200':
          description: Successfully creates destination and returns destination details
          content:
            application/json:
              schema:
                type: object
                properties:
                  did_destination:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 290
                        description: Destination ID
                      destination:
                        type: string
                        example: sip:test@example.com
                        description: Forwarding target
                      priority:
                        type: integer
                        example: 1
                        description: Destination priority
                      callhunt:
                        type: boolean
                        description: Whether callhunt is enabled
                      active:
                        type: boolean
                        example: true
                        description: Whether destination is active
                      transport:
                        type: integer
                        enum:
                        - 1
                        - 4
                        - 5
                        - 10
                        example: 1
                        description: Transport type
                      ai_agent_id:
                        nullable: true
                        type: integer
                        description: Linked AI agent ID (null when the destination
                          is not an AI agent)
                      ai_agent_name:
                        nullable: true
                        type: string
                        description: Linked AI agent name (null when the destination
                          is not an AI agent)
                      dialing_type:
                        type: string
                        enum:
                        - sequence
                        - ring_all
                        - random
                        example: sequence
                        description: 'Dialing mode of the group this destination belongs
                          to: `sequence` tries it alone, `ring_all` dials the whole
                          group at once, `random` picks group members in a random
                          order. Mirrors `callhunt` (`ring_all` maps to true).'
                    required:
                    - id
                    - destination
                    - priority
                    - callhunt
                    - active
                    - transport
                    - ai_agent_id
                    - ai_agent_name
                    description: Created destination details
                required:
                - did_destination
              example:
                did_destination:
                  id: 290
                  destination: sip:test@example.com
                  priority: 1
                  callhunt: false
                  active: true
                  transport: 1
                  dialing_type: sequence
                  ai_agent_id:
                  ai_agent_name:
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope {"errors":{"base":["data not
            found"]}} when neither the DID phone number nor its inventory id matches
            a DID you own.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
        '422':
          description: Returns 422 error with validation messages when destination
            is incorrect
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  destination:
                  - can't be blank
      security:
      - BearerAuth: []
  "/api/v1/purchases/{purchase_id}/destinations/{id}":
    patch:
      summary: Update destination
      description: |
        Update an existing inbound destination for a DID number.

        **Updatable Fields:**
        - `dialing_type` - Dialing mode: `sequence`, `ring_all` or `random`
        - `callhunt` - Legacy two-state mirror of `dialing_type`; ignored when `dialing_type` is sent
        - `active` - Enable/disable this destination

        **Note:** The destination address and transport protocol cannot be changed. To change these, delete and create a new destination.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Inbound Destinations
      parameters:
      - name: purchase_id
        in: path
        required: true
        schema:
          type: string
          example: '43800327987'
        example: '43800327987'
        description: DID identifier — the phone **number** (e.g. `43800327987`) or
          the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g.
          `21869`). Both resolve the same DID.
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 296
        description: Destination ID to update
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                destination[callhunt]:
                  type: string
                  description: Enable callhunt (ring all). Ignored when `destination[dialing_type]`
                    is sent.
                  example: 'true'
                destination[active]:
                  type: string
                  description: Activate/deactivate this destination
                  example: 'false'
                destination[dialing_type]:
                  type: string
                  description: 'Dialing mode of the group this destination belongs
                    to: `sequence` tries it alone, `ring_all` dials the whole group
                    at once, `random` picks group members in a random order. Mirrors
                    `callhunt` (`ring_all` maps to true). Takes precedence over `callhunt`.'
                  enum:
                  - sequence
                  - ring_all
                  - random
      responses:
        '200':
          description: Successfully updates destination settings and returns updated
            destination
          content:
            application/json:
              schema:
                type: object
                properties:
                  did_destination:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 294
                        description: Destination ID
                      destination:
                        type: string
                        example: sip:test@example.com
                        description: Forwarding target
                      priority:
                        type: integer
                        example: 1
                        description: Destination priority
                      callhunt:
                        type: boolean
                        example: true
                        description: Whether callhunt is enabled
                      active:
                        type: boolean
                        description: Whether destination is active
                      transport:
                        type: integer
                        enum:
                        - 1
                        - 4
                        - 5
                        - 10
                        example: 1
                        description: Transport type
                      ai_agent_id:
                        nullable: true
                        type: integer
                        description: Linked AI agent ID (null when the destination
                          is not an AI agent)
                      ai_agent_name:
                        nullable: true
                        type: string
                        description: Linked AI agent name (null when the destination
                          is not an AI agent)
                      dialing_type:
                        type: string
                        enum:
                        - sequence
                        - ring_all
                        - random
                        example: ring_all
                        description: 'Dialing mode of the group this destination belongs
                          to: `sequence` tries it alone, `ring_all` dials the whole
                          group at once, `random` picks group members in a random
                          order. Mirrors `callhunt` (`ring_all` maps to true).'
                    required:
                    - id
                    - destination
                    - priority
                    - callhunt
                    - active
                    - transport
                    - ai_agent_id
                    - ai_agent_name
                    description: Updated destination details
                required:
                - did_destination
              example:
                did_destination:
                  id: 294
                  destination: sip:test@example.com
                  priority: 1
                  callhunt: true
                  active: false
                  transport: 1
                  dialing_type: ring_all
                  ai_agent_id:
                  ai_agent_name:
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope {"errors":{"base":["data not
            found"]}} when neither the DID phone number nor its inventory id matches
            a DID you own.
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    error:
                      type: string
                  required:
                  - error
              examples:
                returns_404_error_when_destination_does_not_exist_or_belongs_to_another_user:
                  summary: Returns 404 error when destination does not exist or belongs
                    to another user
                  value:
                    error: destination not found
                ? returns_the_404_error_envelope_errors_base_data_not_found_when_neither_the_did_phone_number_nor_its_inventory_id_matches_a_did_you_own
                : summary: Returns the 404 error envelope {"errors":{"base":["data
                    not found"]}} when neither the DID phone number nor its inventory
                    id matches a DID you own.
                  value:
                    errors:
                      base:
                      - data not found
      security:
      - BearerAuth: []
    delete:
      summary: Delete destination
      description: |
        Delete an existing inbound destination from a DID number.

        **Important:**
        - Destination is permanently removed from the DID configuration
        - Deletion is logged for audit purposes

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Inbound Destinations
      parameters:
      - name: purchase_id
        in: path
        required: true
        schema:
          type: string
          example: '43800327987'
        example: '43800327987'
        description: DID identifier — the phone **number** (e.g. `43800327987`) or
          the numeric **inventory id** returned by v2 `GET /api/v2/numbers` (e.g.
          `21869`). Both resolve the same DID.
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 293
        description: Destination ID to delete
      responses:
        '204':
          description: Successfully deletes destination and returns 204 No Content
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope {"errors":{"base":["data not
            found"]}} when neither the DID phone number nor its inventory id matches
            a DID you own.
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    error:
                      type: string
                  required:
                  - error
              examples:
                returns_404_error_when_destination_does_not_exist_or_belongs_to_another_user:
                  summary: Returns 404 error when destination does not exist or belongs
                    to another user
                  value:
                    error: destination not found
                ? returns_the_404_error_envelope_errors_base_data_not_found_when_neither_the_did_phone_number_nor_its_inventory_id_matches_a_did_you_own
                : summary: Returns the 404 error envelope {"errors":{"base":["data
                    not found"]}} when neither the DID phone number nor its inventory
                    id matches a DID you own.
                  value:
                    errors:
                      base:
                      - data not found
      security:
      - BearerAuth: []
  "/api/v1/sipaccounts":
    get:
      summary: List SIP accounts
      description: |
        Retrieve list of SIP accounts (trunks) configured for the authenticated user.

        **SIP Accounts** allow making/receiving calls through the platform using SIP protocol.

        **Returned Information:**
        - Account credentials and settings
        - Call routing configuration
        - Usage limits and restrictions
        - Allowed IP addresses (if configured)

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      responses:
        '200':
          description: Successfully returns list of SIP accounts with configuration
            details
          content:
            application/json:
              schema:
                type: object
                properties:
                  sipaccounts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 459
                          description: Unique SIP account identifier
                        name:
                          type: string
                          example: '21491'
                          description: SIP account username
                        callerid:
                          type: string
                          example: ''
                          description: Caller ID
                        label:
                          type: string
                          example: some-label-351
                          description: Account label
                        host:
                          type: string
                          example: dynamic
                          description: SIP server host
                        rewrite_enabled:
                          type: boolean
                          description: Whether number rewriting is enabled
                        rewrite_cond:
                          type: string
                          example: ''
                          description: Rewrite condition pattern (regular expression)
                        rewrite_prefix:
                          type: string
                          example: ''
                          description: Prefix to add when rewriting numbers
                        didinfo_enabled:
                          type: boolean
                          example: true
                          description: Whether DID info is included in SIP headers
                        ip_restrict:
                          type: boolean
                          description: Whether access is restricted by IP address
                        call_restrict:
                          type: boolean
                          description: Whether per-call cost limits are enabled
                        call_limit:
                          type: integer
                          example: 60
                          description: Maximum cost per call in cents
                        channels_restrict:
                          type: boolean
                          description: Whether concurrent channel limits are enabled
                        max_channels:
                          type: integer
                          example: 1
                          description: Maximum number of concurrent channels allowed
                        cost_limit:
                          type: boolean
                          description: Whether maximum call cost limit is enabled
                        max_call_cost:
                          type: string
                          example: '0.0'
                          description: Maximum allowed cost per call
                        created_at:
                          type: string
                          example: 2026-04-10 11:11:10 UTC
                          description: Account creation timestamp
                        low_balance:
                          type: boolean
                          description: Whether account has low balance
                        allowed_ips:
                          type: array
                          items: {}
                          description: List of IP addresses allowed to authenticate
                        charge:
                          type: string
                          example: '0.0'
                          description: Total charges accumulated on this account
                        talk_time:
                          type: integer
                          example: 0
                          description: Total talk time in seconds
                        spend_limit:
                          type: string
                          example: '0.0'
                          description: Maximum total spend amount
                        spend_limit_enabled:
                          type: boolean
                          description: Whether spending limit is enabled
                        available_amount:
                          type: string
                          example: '0.0'
                          description: Amount available for spending
                        call_recording_enabled:
                          type: boolean
                      required:
                      - id
                      - name
                      - callerid
                      - label
                      - host
                      - rewrite_enabled
                      - rewrite_cond
                      - rewrite_prefix
                      - didinfo_enabled
                      - ip_restrict
                      - call_restrict
                      - call_limit
                      - channels_restrict
                      - max_channels
                      - cost_limit
                      - max_call_cost
                      - created_at
                      - low_balance
                      - allowed_ips
                      - charge
                      - talk_time
                      - spend_limit
                      - spend_limit_enabled
                      - available_amount
                    description: List of SIP accounts
                required:
                - sipaccounts
              example:
                sipaccounts:
                - id: 11
                  name: '01121'
                  callerid: ''
                  label: some-label-211
                  host: dynamic
                  rewrite_enabled: false
                  rewrite_cond: ''
                  rewrite_prefix: ''
                  didinfo_enabled: true
                  ip_restrict: false
                  call_restrict: false
                  call_limit: 60
                  channels_restrict: false
                  max_channels: 1
                  cost_limit: false
                  max_call_cost: '0.0'
                  created_at: 2026-08-12 11:39:35 UTC
                  charge: '0.0'
                  talk_time: 0
                  low_balance: false
                  spend_limit: '0.0'
                  spend_limit_enabled: false
                  available_amount: '0.0'
                  call_recording_enabled: false
                  allowed_ips: []
        '403':
          description: Returns 403 error when SIP accounts are disabled for this user
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    error:
                      type: string
                  required:
                  - error
              examples:
                returns_403_error_when_api_token_is_incorrect:
                  summary: Returns 403 error when API token is incorrect
                  value:
                    error: Unauthorized
                returns_403_error_when_sip_accounts_are_disabled_for_this_user:
                  summary: Returns 403 error when SIP accounts are disabled for this
                    user
                  value:
                    errors:
                      base:
                      - Access denied
      security:
      - BearerAuth: []
    post:
      summary: Create SIP account
      description: |
        Create a new SIP account (trunk) for making/receiving calls.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sipaccount[label]:
                  type: string
                  description: Account label/name
                  example: Test SIP Account
                sipaccount[password]:
                  type: string
                  description: SIP password
                  example: SecurePass123
                sipaccount[callerid]:
                  type: string
                  description: Caller ID to display on outbound calls
                  example: '1234567890'
                sipaccount[rewrite_enabled]:
                  type: string
                  description: Enable number rewriting
                  example: 'false'
                sipaccount[rewrite_cond]:
                  type: string
                  description: Rewrite condition pattern (regular expression)
                sipaccount[rewrite_prefix]:
                  type: string
                  description: Prefix to add when rewriting numbers
                sipaccount[didinfo_enabled]:
                  type: string
                  description: Enable DID info in SIP headers
                  example: 'true'
                sipaccount[ip_restrict]:
                  type: string
                  description: Restrict access by IP address (requires allowed IPs)
                  example: 'false'
                sipaccount[call_restrict]:
                  type: string
                  description: Enable per-call cost limits
                  example: 'true'
                sipaccount[call_limit]:
                  type: string
                  description: Maximum cost per call in cents
                  example: '1000'
                sipaccount[channels_restrict]:
                  type: string
                  description: Enable concurrent channel limits
                  example: 'true'
                sipaccount[max_channels]:
                  type: string
                  description: Maximum concurrent channels allowed
                  example: '5'
                sipaccount[cost_limit]:
                  type: string
                  description: Enable maximum call cost limit
                  example: 'false'
                sipaccount[max_call_cost]:
                  type: string
                  description: Maximum allowed cost per call in cents
                sipaccount[spend_limit_enabled]:
                  type: string
                  description: Enable total spending limit
                  example: 'false'
                sipaccount[spend_limit]:
                  type: string
                  description: Maximum total spend amount in cents
                sipaccount[reset_available_amount]:
                  type: string
                  description: Amount available for spend limit reset in cents
                sipaccount[call_recording_enabled]:
                  type: string
                  description: Enable or disable recording of outbound calls made
                    via a selected SIP account
              required:
              - sipaccount[label]
              - sipaccount[password]
      responses:
        '200':
          description: Successfully creates SIP account and returns credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  sipaccount:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 466
                        description: SIP account ID
                      name:
                        type: string
                        example: '61737'
                        description: SIP account username
                      callerid:
                        type: string
                        example: ''
                        description: Caller ID
                      label:
                        type: string
                        example: Test SIP Account
                        description: Account label
                      host:
                        type: string
                        example: dynamic
                        description: SIP server host
                      rewrite_enabled:
                        type: boolean
                        description: Whether number rewriting is enabled
                      rewrite_cond:
                        type: string
                        example: ''
                        description: Rewrite condition pattern (regular expression)
                      rewrite_prefix:
                        type: string
                        example: ''
                        description: Prefix to add when rewriting numbers
                      didinfo_enabled:
                        type: boolean
                        example: true
                        description: Whether DID info is included in SIP headers
                      ip_restrict:
                        type: boolean
                        description: Whether access is restricted by IP address
                      call_restrict:
                        type: boolean
                        example: true
                        description: Whether per-call cost limits are enabled
                      call_limit:
                        type: integer
                        example: 1000
                        description: Maximum cost per call in cents
                      channels_restrict:
                        type: boolean
                        example: true
                        description: Whether concurrent channel limits are enabled
                      max_channels:
                        type: integer
                        example: 5
                        description: Maximum number of concurrent channels allowed
                      cost_limit:
                        type: boolean
                        description: Whether maximum call cost limit is enabled
                      max_call_cost:
                        type: string
                        example: '0.0'
                        description: Maximum allowed cost per call
                      created_at:
                        type: string
                        example: 2026-04-10 11:11:15 UTC
                        description: Creation timestamp
                      low_balance:
                        type: boolean
                        description: Whether account has low balance
                      allowed_ips:
                        type: array
                        items: {}
                        description: List of IP addresses allowed to authenticate
                      charge:
                        type: string
                        example: '0.0'
                        description: Total charges accumulated on this account
                      talk_time:
                        type: integer
                        example: 0
                        description: Total talk time in seconds
                      spend_limit:
                        type: string
                        example: '0.0'
                        description: Maximum total spend amount
                      spend_limit_enabled:
                        type: boolean
                        description: Whether spending limit is enabled
                      available_amount:
                        type: string
                        example: '0.0'
                        description: Amount available for spending
                      call_recording_enabled:
                        type: boolean
                    required:
                    - id
                    - name
                    - callerid
                    - label
                    - host
                    - rewrite_enabled
                    - rewrite_cond
                    - rewrite_prefix
                    - didinfo_enabled
                    - ip_restrict
                    - call_restrict
                    - call_limit
                    - channels_restrict
                    - max_channels
                    - cost_limit
                    - max_call_cost
                    - created_at
                    - low_balance
                    - allowed_ips
                    - charge
                    - talk_time
                    - spend_limit
                    - spend_limit_enabled
                    - available_amount
                    description: Created SIP account details
                  warnings:
                    type: array
                    description: Non-fatal notices for parts of the request that were
                      accepted but silently skipped (e.g. an unverified caller ID).
                      Present only when non-empty.
                    items:
                      "$ref": "#/components/schemas/Warning"
                required:
                - sipaccount
              example:
                sipaccount:
                  id: 466
                  name: '61737'
                  callerid: ''
                  label: Test SIP Account
                  host: dynamic
                  rewrite_enabled: false
                  rewrite_cond: ''
                  rewrite_prefix: ''
                  didinfo_enabled: true
                  ip_restrict: false
                  call_restrict: true
                  call_limit: 1000
                  channels_restrict: true
                  max_channels: 5
                  cost_limit: false
                  max_call_cost: '0.0'
                  created_at: 2026-04-10 11:11:15 UTC
                  low_balance: false
                  allowed_ips: []
                  charge: '0.0'
                  talk_time: 0
                  spend_limit: '0.0'
                  spend_limit_enabled: false
                  available_amount: '0.0'
                  call_recording_enabled: false
                warnings:
                - resource: caller_id
                  identifier: '1234567890'
                  code: not_an_owned_or_verified_caller_id
                  message: is not an owned or verified caller ID and was ignored
        '403':
          description: Returns 403 error when SIP account creation is disabled
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    error:
                      type: string
                  required:
                  - error
              examples:
                returns_403_error_when_api_token_is_incorrect:
                  summary: Returns 403 error when API token is incorrect
                  value:
                    error: Unauthorized
                returns_403_error_when_sip_account_creation_is_disabled:
                  summary: Returns 403 error when SIP account creation is disabled
                  value:
                    errors:
                      base:
                      - Access denied
      security:
      - BearerAuth: []
  "/api/v1/sipaccounts/{id}":
    get:
      summary: Get SIP account details
      description: |
        Retrieve details of a specific SIP account.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: '01234'
        example: '01234'
        description: SIP account identifier — the account **name** (e.g. `01234`,
          which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve
          the same account.
      responses:
        '200':
          description: Successfully returns SIP account configuration and settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  sipaccount:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 464
                        description: Unique SIP account identifier
                      name:
                        type: string
                        example: '75303'
                        description: SIP account username
                      callerid:
                        type: string
                        example: ''
                        description: Caller ID
                      label:
                        type: string
                        example: some-label-456
                        description: Account label
                      host:
                        type: string
                        example: dynamic
                        description: SIP server host
                      rewrite_enabled:
                        type: boolean
                        description: Whether number rewriting is enabled
                      rewrite_cond:
                        type: string
                        example: ''
                        description: Rewrite condition pattern (regular expression)
                      rewrite_prefix:
                        type: string
                        example: ''
                        description: Prefix to add when rewriting numbers
                      didinfo_enabled:
                        type: boolean
                        example: true
                        description: Whether DID info is included in SIP headers
                      ip_restrict:
                        type: boolean
                        description: Whether access is restricted by IP address
                      call_restrict:
                        type: boolean
                        description: Whether per-call cost limits are enabled
                      call_limit:
                        type: integer
                        example: 60
                        description: Maximum cost per call in cents
                      channels_restrict:
                        type: boolean
                        description: Whether concurrent channel limits are enabled
                      max_channels:
                        type: integer
                        example: 1
                        description: Maximum number of concurrent channels allowed
                      cost_limit:
                        type: boolean
                        description: Whether maximum call cost limit is enabled
                      max_call_cost:
                        type: string
                        example: '0.0'
                        description: Maximum allowed cost per call
                      created_at:
                        type: string
                        example: 2026-04-10 11:11:15 UTC
                        description: Account creation timestamp
                      low_balance:
                        type: boolean
                        description: Whether account has low balance
                      allowed_ips:
                        type: array
                        items: {}
                        description: List of IP addresses allowed to authenticate
                      charge:
                        type: string
                        example: '0.0'
                        description: Total charges accumulated on this account
                      talk_time:
                        type: integer
                        example: 0
                        description: Total talk time in seconds
                      spend_limit:
                        type: string
                        example: '0.0'
                        description: Maximum total spend amount
                      spend_limit_enabled:
                        type: boolean
                        description: Whether spending limit is enabled
                      available_amount:
                        type: string
                        example: '0.0'
                        description: Amount available for spending
                      call_recording_enabled:
                        type: boolean
                    required:
                    - id
                    - name
                    - callerid
                    - label
                    - host
                    - rewrite_enabled
                    - rewrite_cond
                    - rewrite_prefix
                    - didinfo_enabled
                    - ip_restrict
                    - call_restrict
                    - call_limit
                    - channels_restrict
                    - max_channels
                    - cost_limit
                    - max_call_cost
                    - created_at
                    - low_balance
                    - allowed_ips
                    - charge
                    - talk_time
                    - spend_limit
                    - spend_limit_enabled
                    - available_amount
                    description: SIP account details
                required:
                - sipaccount
              example:
                sipaccount:
                  id: 464
                  name: '75303'
                  callerid: ''
                  label: some-label-456
                  host: dynamic
                  rewrite_enabled: false
                  rewrite_cond: ''
                  rewrite_prefix: ''
                  didinfo_enabled: true
                  ip_restrict: false
                  call_restrict: false
                  call_limit: 60
                  channels_restrict: false
                  max_channels: 1
                  cost_limit: false
                  max_call_cost: '0.0'
                  created_at: 2026-04-10 11:11:15 UTC
                  low_balance: false
                  allowed_ips: []
                  charge: '0.0'
                  talk_time: 0
                  spend_limit: '0.0'
                  spend_limit_enabled: false
                  available_amount: '0.0'
                  call_recording_enabled: false
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope {"errors":{"base":["data not
            found"]}} when neither the SIP account name nor id matches an account
            you own.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
      security:
      - BearerAuth: []
    patch:
      summary: Update SIP account
      description: |
        Update SIP account settings.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: '01234'
        example: '01234'
        description: SIP account identifier — the account **name** (e.g. `01234`,
          which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve
          the same account.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sipaccount[label]:
                  type: string
                  description: Account label/name
                  example: Updated Label
                sipaccount[password]:
                  type: string
                  description: SIP password
                sipaccount[callerid]:
                  type: string
                  description: Caller ID to display on outbound calls
                  example: '9876543210'
                sipaccount[rewrite_enabled]:
                  type: string
                  description: Enable number rewriting
                sipaccount[rewrite_cond]:
                  type: string
                  description: Rewrite condition pattern (regular expression)
                sipaccount[rewrite_prefix]:
                  type: string
                  description: Prefix to add when rewriting numbers
                sipaccount[didinfo_enabled]:
                  type: string
                  description: Enable DID info in SIP headers
                  example: 'true'
                sipaccount[ip_restrict]:
                  type: string
                  description: Restrict access by IP address (requires allowed IPs)
                sipaccount[call_restrict]:
                  type: string
                  description: Enable per-call cost limits
                  example: 'true'
                sipaccount[call_limit]:
                  type: string
                  description: Maximum cost per call in cents
                  example: '2000'
                sipaccount[channels_restrict]:
                  type: string
                  description: Enable concurrent channel limits
                  example: 'true'
                sipaccount[max_channels]:
                  type: string
                  description: Maximum concurrent channels allowed
                  example: '10'
                sipaccount[cost_limit]:
                  type: string
                  description: Enable maximum call cost limit
                sipaccount[max_call_cost]:
                  type: string
                  description: Maximum allowed cost per call in cents
                sipaccount[spend_limit_enabled]:
                  type: string
                  description: Enable total spending limit
                sipaccount[spend_limit]:
                  type: string
                  description: Maximum total spend amount in cents
                sipaccount[reset_available_amount]:
                  type: string
                  description: Amount available for spend limit reset in cents
                sipaccount[call_recording_enabled]:
                  type: string
                  description: Enable or disable recording of outbound calls made
                    via a selected SIP account
      responses:
        '200':
          description: Successfully updates SIP account settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  sipaccount:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 468
                        description: Unique SIP account identifier
                      name:
                        type: string
                        example: '83256'
                        description: SIP account username
                      callerid:
                        type: string
                        example: ''
                        description: Caller ID
                      label:
                        type: string
                        example: Updated Label
                        description: Account label
                      host:
                        type: string
                        example: dynamic
                        description: SIP server host
                      rewrite_enabled:
                        type: boolean
                        description: Whether number rewriting is enabled
                      rewrite_cond:
                        type: string
                        example: ''
                        description: Rewrite condition pattern (regular expression)
                      rewrite_prefix:
                        type: string
                        example: ''
                        description: Prefix to add when rewriting numbers
                      didinfo_enabled:
                        type: boolean
                        example: true
                        description: Whether DID info is included in SIP headers
                      ip_restrict:
                        type: boolean
                        description: Whether access is restricted by IP address
                      call_restrict:
                        type: boolean
                        example: true
                        description: Whether per-call cost limits are enabled
                      call_limit:
                        type: integer
                        example: 2000
                        description: Maximum cost per call in cents
                      channels_restrict:
                        type: boolean
                        example: true
                        description: Whether concurrent channel limits are enabled
                      max_channels:
                        type: integer
                        example: 5
                        description: Maximum number of concurrent channels allowed
                      cost_limit:
                        type: boolean
                        description: Whether maximum call cost limit is enabled
                      max_call_cost:
                        type: string
                        example: '0.0'
                        description: Maximum allowed cost per call
                      created_at:
                        type: string
                        example: 2026-04-10 11:11:23 UTC
                        description: Account creation timestamp
                      low_balance:
                        type: boolean
                        description: Whether account has low balance
                      allowed_ips:
                        type: array
                        items: {}
                        description: List of IP addresses allowed to authenticate
                      charge:
                        type: string
                        example: '0.0'
                        description: Total charges accumulated on this account
                      talk_time:
                        type: integer
                        example: 0
                        description: Total talk time in seconds
                      spend_limit:
                        type: string
                        example: '10000.0'
                        description: Maximum total spend amount
                      spend_limit_enabled:
                        type: boolean
                        description: Whether spending limit is enabled
                      available_amount:
                        type: string
                        example: '10000.0'
                        description: Amount available for spending
                      call_recording_enabled:
                        type: boolean
                    required:
                    - id
                    - name
                    - callerid
                    - label
                    - host
                    - rewrite_enabled
                    - rewrite_cond
                    - rewrite_prefix
                    - didinfo_enabled
                    - ip_restrict
                    - call_restrict
                    - call_limit
                    - channels_restrict
                    - max_channels
                    - cost_limit
                    - max_call_cost
                    - created_at
                    - low_balance
                    - allowed_ips
                    - charge
                    - talk_time
                    - spend_limit
                    - spend_limit_enabled
                    - available_amount
                    description: Updated SIP account details
                  warnings:
                    type: array
                    description: Non-fatal notices for parts of the request that were
                      accepted but silently skipped (e.g. an unverified caller ID).
                      Present only when non-empty.
                    items:
                      "$ref": "#/components/schemas/Warning"
                required:
                - sipaccount
              example:
                sipaccount:
                  id: 468
                  name: '83256'
                  callerid: ''
                  label: Updated Label
                  host: dynamic
                  rewrite_enabled: false
                  rewrite_cond: ''
                  rewrite_prefix: ''
                  didinfo_enabled: true
                  ip_restrict: false
                  call_restrict: true
                  call_limit: 2000
                  channels_restrict: true
                  max_channels: 5
                  cost_limit: false
                  max_call_cost: '0.0'
                  created_at: 2026-04-10 11:11:23 UTC
                  low_balance: false
                  allowed_ips: []
                  charge: '0.0'
                  talk_time: 0
                  spend_limit: '10000.0'
                  spend_limit_enabled: false
                  available_amount: '10000.0'
                  call_recording_enabled: false
                warnings:
                - resource: caller_id
                  identifier: '9876543210'
                  code: not_an_owned_or_verified_caller_id
                  message: is not an owned or verified caller ID and was ignored
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope {"errors":{"base":["data not
            found"]}} when neither the SIP account name nor id matches an account
            you own.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
      security:
      - BearerAuth: []
    delete:
      summary: Delete SIP account
      description: |
        Delete a SIP account.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: '01234'
        example: '01234'
        description: SIP account identifier — the account **name** (e.g. `01234`,
          which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve
          the same account.
      responses:
        '204':
          description: Successfully deletes SIP account
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope {"errors":{"base":["data not
            found"]}} when neither the SIP account name nor id matches an account
            you own.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
      security:
      - BearerAuth: []
  "/api/v1/sipaccounts/{sipaccount_id}/allowed_ips":
    get:
      summary: List allowed IP addresses
      description: |
        Retrieve list of IP addresses allowed to authenticate this SIP account.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      parameters:
      - name: sipaccount_id
        in: path
        required: true
        schema:
          type: string
          example: '01234'
        example: '01234'
        description: Parent SIP account identifier — the account **name** (e.g. `01234`,
          which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve
          the same account.
      responses:
        '200':
          description: Successfully returns list of allowed IP addresses
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowed_ips:
                    type: array
                    items:
                      type: string
                    description: List of allowed IP address strings
                required:
                - allowed_ips
              example:
                allowed_ips:
                - 1.2.3.4
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope when neither the SIP account
            name nor id matches an account you own
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
      security:
      - BearerAuth: []
    post:
      summary: Add allowed IP address
      description: |
        Add IP address to SIP account whitelist.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      parameters:
      - name: sipaccount_id
        in: path
        required: true
        schema:
          type: string
          example: '01234'
        example: '01234'
        description: Parent SIP account identifier — the account **name** (e.g. `01234`,
          which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve
          the same account.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                ip:
                  type: string
                  description: IP address to allow
                  example: 1.2.3.4
              required:
              - ip
      responses:
        '200':
          description: Successfully adds IP to whitelist
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowed_ips:
                    type: array
                    items:
                      type: string
                    description: List of allowed IP addresses after creation
                required:
                - allowed_ips
              example:
                allowed_ips:
                - 1.2.3.4
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope when neither the SIP account
            name nor id matches an account you own
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
        '422':
          description: Returns 422 error when IP address format is invalid
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  ip:
                  - can't be blank
                  - only ip format xxx.xxx.xxx.xxx
      security:
      - BearerAuth: []
    delete:
      summary: Remove allowed IP address
      description: |
        Remove IP address from SIP account whitelist.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SIP Accounts
      parameters:
      - name: sipaccount_id
        in: path
        required: true
        schema:
          type: string
          example: '01234'
        example: '01234'
        description: Parent SIP account identifier — the account **name** (e.g. `01234`,
          which may start with `0`) or the numeric **id** (e.g. `73`). Both resolve
          the same account.
      - name: ip
        in: query
        required: true
        schema:
          type: string
        description: IP address to remove
        example: 1.2.3.4
      responses:
        '204':
          description: Successfully removes IP from whitelist
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: Returns the 404 error envelope when neither the SIP account
            name nor id matches an account you own
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
      security:
      - BearerAuth: []
  "/api/v1/sms":
    get:
      summary: List sent SMS messages
      description: |
        Retrieve paginated list of SMS messages sent by the authenticated user.
        Note: Contact your account manager to set up a Relay URL for inbound messages.
      tags:
      - SMS
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: string
          minimum: 1
          default: 1
        description: Page number for pagination (starts from 1)
      - name: per_page
        in: query
        required: false
        schema:
          type: string
          minimum: 1
          maximum: 100
          default: 20
        description: Number of items per page
      responses:
        '200':
          description: Successfully returns paginated list of sent SMS messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  sms:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 100
                          description: SMS ID
                        destination:
                          type: string
                          example: '1234567890'
                          description: Destination number
                        message:
                          type: string
                          example: Test
                          description: Message content
                        status:
                          type: string
                          enum:
                          - created
                          - failed
                          - sent
                          - dlr_error
                          - delivered
                          - not_delivered
                          - interrupted
                          example: created
                          description: Delivery status
                        charge:
                          type: number
                          format: float
                          example: 0.0
                          description: SMS cost
                        segments_count:
                          type: integer
                          example: 1
                          description: Number of segments
                      required:
                      - id
                      - destination
                      - message
                      - status
                      - charge
                      - segments_count
                    description: List of SMS messages
                  pagination:
                    type: object
                    properties:
                      pages:
                        type: integer
                      page:
                        type: integer
                      total_records:
                        type: integer
                      per_page:
                        type: integer
                    required:
                    - pages
                    - page
                    - total_records
                    - per_page
                required:
                - sms
                - pagination
              example:
                sms:
                - id: 100
                  destination: '1234567890'
                  message: Test
                  status: created
                  charge: 0.0
                  segments_count: 1
                pagination:
                  pages: 1
                  page: 1
                  total_records: 1
                  per_page: 100
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
      security:
      - BearerAuth: []
    post:
      summary: Send SMS message
      description: |
        Send an SMS message from a DID number owned by the authenticated user.

        **Requirements:**
        - Source DID must be owned by user
        - Source DID must have SMS enabled
        - Sufficient account balance for SMS cost
        - Valid destination phone number

        **Cost:**
        - Charged per segment (160 characters)
        - Price varies by destination country

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SMS
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sm[source]:
                  type: string
                  description: Source DID number (must be SMS-enabled and owned by
                    user)
                  example: '1234567890'
                sm[destination]:
                  type: string
                  description: Destination phone number (must be a valid international
                    number)
                  example: ''
                sm[message]:
                  type: string
                  description: SMS text content (160 chars per segment)
                  example: Test message
                dlr[callback_endpoint]:
                  type: string
                  description: Optional DLR (Delivery Receipt) callback URL
                  example: https://example.com/webhook
              required:
              - sm[source]
              - sm[destination]
              - sm[message]
      responses:
        '200':
          description: Successfully sends SMS message and returns details with ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  sms:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 99
                        description: SMS ID
                      destination:
                        type: string
                        example: '12012025555'
                        description: Destination number
                      message:
                        type: string
                        example: Test message from API
                        description: Message content
                      status:
                        type: string
                        enum:
                        - created
                        - failed
                        - sent
                        - dlr_error
                        - delivered
                        - not_delivered
                        - interrupted
                        example: created
                        description: Delivery status
                      charge:
                        type: number
                        format: float
                        example: 0.0001
                        description: SMS cost
                      segments_count:
                        type: integer
                        example: 1
                        description: Number of segments
                    required:
                    - id
                    - destination
                    - message
                    - status
                    - charge
                    - segments_count
                    description: Created SMS details
                required:
                - sms
              example:
                sms:
                  id: 99
                  destination: '12012025555'
                  message: Test message from API
                  status: created
                  charge: 0.0001
                  segments_count: 1
        '400':
          description: The request body must be valid JSON.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example: {}
        '403':
          description: Returns 403 error when destination number is blocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              examples:
                returns_403_error_when_api_token_is_incorrect:
                  summary: Returns 403 error when API token is incorrect
                  value:
                    error: Unauthorized
                returns_403_error_when_destination_number_is_blocked:
                  summary: Returns 403 error when destination number is blocked
                  value:
                    error: SMS delivery to this destination is currently restricted
        '422':
          description: Returns 422 error when destination phone number is invalid
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    error:
                      type: string
                  required:
                  - error
              examples:
                returns_422_error_when_destination_parameter_is_missing_or_empty:
                  summary: Returns 422 error when destination parameter is missing
                    or empty
                  value:
                    errors:
                      destination:
                      - Required
                returns_422_error_when_destination_phone_number_is_invalid:
                  summary: Returns 422 error when destination phone number is invalid
                  value:
                    error: 'SMS delivery failed: Invalid phone number'
      security:
      - BearerAuth: []
  "/api/v1/sms/{id}":
    get:
      summary: Get SMS message details
      description: |
        Retrieve details of a specific SMS message sent by the authenticated user.

        **Returned Information:**
        - SMS ID and status
        - Source and destination numbers
        - Message content
        - Delivery status and timestamps
        - Cost and segment count

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - SMS
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 103
        description: SMS message ID
      responses:
        '200':
          description: Successfully returns SMS message details including status and
            timestamps
          content:
            application/json:
              schema:
                type: object
                properties:
                  sms:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 102
                        description: SMS ID
                      destination:
                        type: string
                        example: '1234567890'
                        description: Destination number
                      message:
                        type: string
                        example: Test message
                        description: Message content
                      status:
                        type: string
                        enum:
                        - created
                        - failed
                        - sent
                        - dlr_error
                        - delivered
                        - not_delivered
                        - interrupted
                        example: created
                        description: Delivery status
                      charge:
                        type: number
                        format: float
                        example: 0.0
                        description: SMS cost
                      segments_count:
                        type: integer
                        example: 1
                        description: Number of segments
                    required:
                    - id
                    - destination
                    - message
                    - status
                    - charge
                    - segments_count
                    description: SMS message details
                required:
                - sms
              example:
                sms:
                  id: 102
                  destination: '1234567890'
                  message: Test message
                  status: created
                  charge: 0.0
                  segments_count: 1
        '403':
          description: Returns 403 error when API token is incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: The requested resource could not be found.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
      security:
      - BearerAuth: []
  "/api/v2/numbers/countries":
    get:
      summary: List countries
      description: |
        Retrieve a list of all countries where DID numbers are available.

        **When to use:**
        - Building country selection interface
        - Checking number availability by country
        - Starting the DID purchase flow

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      responses:
        '200':
          description: returns list of available countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1907
                          description: Country identifier
                        name:
                          type: string
                          example: United States
                          description: Country name
                        short_name:
                          type: string
                          example: US
                          description: ISO 3166-1 alpha-2 country code
                        has_provinces_or_states:
                          type: boolean
                          description: Whether country has states or provinces
                      required:
                      - id
                      - name
                      - short_name
                      - has_provinces_or_states
                    description: List of countries with available DID numbers
                required:
                - countries
              example:
                countries:
                - id: 1907
                  name: United States
                  short_name: US
                  has_provinces_or_states: false
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access denied
  "/api/v2/numbers/countries/{country_id}/cities":
    get:
      summary: List cities
      description: |
        Retrieve a list of cities within a country where DID numbers are available.

        **Important notes:**
        - For countries with states/provinces, use region-specific endpoint instead
        - Each city includes count of available DIDs
        - Cities are returned with area codes

        **When to use:**
        - Building city selection for countries without states
        - Checking DID availability by city
        - Displaying available locations to users

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      parameters:
      - name: country_id
        in: path
        required: true
        schema:
          type: integer
        example: 0
        description: Country identifier
      responses:
        '200':
          description: returns list of cities
          content:
            application/json:
              schema:
                type: object
                properties:
                  cities:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1955
                          description: City identifier
                        name:
                          type: string
                          example: New York
                          description: City name and state/province
                        area_code:
                          type: string
                          example: '212200'
                          description: Area code for this city
                        count:
                          type: integer
                          minimum: 0
                          example: 1
                          description: Number of available DIDs in this city
                      required:
                      - id
                      - name
                      - area_code
                      - count
                    description: List of cities with available DID numbers
                required:
                - cities
              example:
                cities:
                - id: 1955
                  name: New York
                  area_code: '212200'
                  count: 1
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access denied
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
  "/api/v2/numbers/countries/{country_id}/regions":
    get:
      summary: List NANP regions
      description: |
        Retrieve a list of states or provinces within a country (e.g., US states, Canadian provinces).

        **Important notes:**
        - Only applicable for countries with `has_provinces_or_states: true`
        - Returns 404 for countries without regional divisions
        - Use this before querying cities in countries with states/provinces

        **When to use:**
        - Building state/province selection for US, Canada, etc.
        - Filtering DID search by region

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      parameters:
      - name: country_id
        in: path
        required: true
        schema:
          type: integer
        example: 1926
        description: Country identifier
      responses:
        '200':
          description: returns list of regions
          content:
            application/json:
              schema:
                type: object
                properties:
                  regions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                          description: Region/state identifier
                        name:
                          type: string
                          example: New York
                          description: State or province name
                        short_name:
                          type: string
                          example: NY
                          description: State abbreviation
                      required:
                      - id
                      - name
                      - short_name
                    description: List of states/provinces with available DID numbers
                required:
                - regions
              example:
                regions:
                - id: 1
                  name: New York
                  short_name: NY
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access denied
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
  "/api/v2/numbers/countries/{country_id}/locations":
    get:
      summary: Search locations by prefix
      description: |
        Search for locations (cities) that have DID numbers starting with a specific prefix.

        **Important notes:**
        - Useful for finding locations with specific area codes
        - Prefix can be partial number (e.g., "212" for NYC area code)
        - Returns combined location information (country, state, city)

        **When to use:**
        - Implementing "vanity number" search by prefix
        - Finding locations with specific area codes
        - Reverse lookup of number to location

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      parameters:
      - name: country_id
        in: path
        required: true
        schema:
          type: integer
        example: 1962
        description: Country identifier
      - name: prefix
        in: query
        required: true
        schema:
          type: integer
        example: 212
        description: Number prefix to search for
      - name: sms_enabled
        in: query
        required: false
        schema:
          type: string
        example: 'true'
        description: Filter locations by SMS capability
      responses:
        '200':
          description: returns list of locations
          content:
            application/json:
              schema:
                type: object
                properties:
                  locations:
                    type: array
                    items:
                      type: object
                      properties:
                        city_id:
                          type: integer
                          example: 1975
                          description: City identifier
                        city_name:
                          type: string
                          example: New York
                          description: City name
                        country_name:
                          type: string
                          example: United States
                          description: Country name
                        state_id:
                          type: integer
                          example: 12
                          description: State identifier (if applicable)
                        country_id:
                          type: integer
                          example: 1959
                          description: Country identifier
                        label:
                          type: string
                          example: New York 212200, United States
                          description: Combined location label for display
                        city_code:
                          type: integer
                          example: 212200
                          description: City code/area code
                        state_name:
                          type: string
                          example: New York
                          description: State name (if applicable)
                      required:
                      - city_id
                      - city_name
                      - country_name
                      - state_id
                      - country_id
                      - label
                      - city_code
                      - state_name
                    description: List of locations matching search criteria
                required:
                - locations
              example:
                locations:
                - city_id: 1975
                  city_name: New York
                  country_name: United States
                  state_id: 12
                  country_id: 1959
                  label: New York 212200, United States
                  city_code: 212200
                  state_name: New York
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access denied
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
  "/api/v2/numbers/countries/{country_id}/cities/{city_id}/dids":
    get:
      summary: List numbers by city
      description: |
        Retrieve paginated list of available DID numbers in a specific city.

        **Important notes:**
        - For countries without regions (UK, Netherlands, etc.)
        - Results are paginated (default 25 per page)
        - Includes full pricing and feature details for each number
        - Use for countries where regions are not applicable

        **When to use:**
        - Displaying available numbers after city selection
        - Browsing DID inventory by location
        - Non-US/Canada purchase flows

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      parameters:
      - name: country_id
        in: path
        required: true
        schema:
          type: integer
        example: 0
        description: Country identifier
      - name: city_id
        in: path
        required: true
        schema:
          type: integer
        example: 1950
        description: City identifier
      responses:
        '200':
          description: returns list of available dids
          content:
            application/json:
              schema:
                type: object
                properties:
                  dids:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                            example: 1
                            description: Total number of items
                          total_pages:
                            type: integer
                            example: 1
                            description: Total number of pages
                          current_page:
                            type: integer
                            example: 1
                            description: Current page number
                        required:
                        - total
                        - total_pages
                        - current_page
                        description: Pagination metadata
                      dids:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 2622
                              description: DID identifier
                            country:
                              type: string
                              example: United States
                              description: Country name
                            city:
                              type: string
                              example: New York
                              description: City name
                            sms_enabled:
                              type: boolean
                              description: Whether SMS is available for this number
                            no_local_cli:
                              type: boolean
                              description: Whether number does not support local caller
                                ID
                            channels:
                              type: integer
                              example: 1
                              description: Maximum simultaneous calls
                            free_min:
                              type: integer
                              example: 0
                              description: Free minutes included per month
                            cnam:
                              type: boolean
                              description: Caller Name (CNAM) support
                            commitment_months:
                              type: integer
                              example: 12
                              description: Minimum service term in months
                            activation:
                              type: number
                              format: float
                              example: 1.17
                              description: One-time activation fee (USD)
                            monthly:
                              type: number
                              format: float
                              example: 1.755
                              description: Monthly recurring fee (USD)
                            per_minute:
                              type: number
                              format: float
                              example: 0.117
                              description: Per-minute inbound call rate (USD)
                            origination_per_min:
                              type: number
                              format: float
                              example: 0.585
                              description: Per-minute origination rate (USD)
                            required_documents:
                              type: array
                              items:
                                type: object
                                properties:
                                  type:
                                    type: integer
                                    example: 22
                                    description: Document type ID
                                  name:
                                    type: string
                                    example: Proof of Address
                                    description: Document type name
                                required:
                                - type
                                - name
                              description: List of required documents for this number
                            state:
                              type: string
                              example: New York
                              description: State name (if applicable)
                            country_short_name:
                              type: string
                              example: US
                              description: ISO country code
                            number:
                              type: string
                              example: '12122001234'
                              description: Phone number
                            never_sold:
                              type: integer
                              example: 1
                              description: Whether number has never been sold before
                                (1=yes, 0=no)
                            call_recording_enabled:
                              type: boolean
                          required:
                          - id
                          - country
                          - city
                          - sms_enabled
                          - no_local_cli
                          - channels
                          - free_min
                          - cnam
                          - commitment_months
                          - activation
                          - monthly
                          - per_minute
                          - origination_per_min
                          - required_documents
                          - state
                          - country_short_name
                          - number
                          - never_sold
                        description: Array of available DID numbers
                    required:
                    - pagination
                    - dids
                    description: Paginated list of available DID numbers
                required:
                - dids
              example:
                dids:
                  pagination:
                    total: 1
                    total_pages: 1
                    current_page: 1
                  dids:
                  - id: 2622
                    country: United States
                    city: New York
                    sms_enabled: false
                    no_local_cli: false
                    channels: 1
                    free_min: 0
                    cnam: false
                    commitment_months: 12
                    required_documents:
                    - type: 22
                      name: Proof of Address
                    activation: 1.17
                    monthly: 1.755
                    per_minute: 0.117
                    origination_per_min: 0.585
                    state: New York
                    country_short_name: US
                    number: '12122001234'
                    never_sold: 1
                    call_recording_enabled: false
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access denied
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
  "/api/v2/numbers/search":
    get:
      summary: Search numbers (advanced)
      description: |
        Advanced search for available DID numbers with multiple filter criteria.

        **Important notes:**
        - Supports pagination (page, per_page parameters)
        - All filter parameters are optional
        - Combine multiple filters for precise results
        - Use for complex search scenarios beyond location-based browsing

        **When to use:**
        - Implementing vanity number search
        - Finding numbers with specific features
        - Custom number selection interfaces
        - Bulk number lookup

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      parameters:
      - name: id_in
        in: query
        required: false
        schema:
          type: integer
        example: 2653
        description: Search for specific DID IDs (comma-separated)
      - name: number_in
        in: query
        required: false
        schema:
          type: string
        example: '12125551234,12125559876'
        description: Search for specific numbers (exact match, comma-separated)
      - name: number_contains
        in: query
        required: false
        schema:
          type: integer
        example: 555
        description: Search for numbers containing this pattern
      - name: begins_with
        in: query
        required: false
        schema:
          type: integer
        example: 121
        description: Search for numbers beginning with this pattern
      - name: ends_with
        in: query
        required: false
        schema:
          type: integer
        example: 1234
        description: Search for numbers ending with this pattern
      - name: city_name_contains
        in: query
        required: false
        schema:
          type: string
        example: YORK
        description: Filter by city name (partial match)
      - name: country_name_contains
        in: query
        required: false
        schema:
          type: string
        example: United States
        description: Filter by country name (partial match)
      - name: state_name_contains
        in: query
        required: false
        schema:
          type: string
        example: York
        description: Filter by state/region name (partial match, US only)
      - name: sms_enabled
        in: query
        required: false
        schema:
          type: string
        example: 'true'
        description: Filter by SMS capability (true/false)
      - name: no_local_cli
        in: query
        required: false
        schema:
          type: string
        example: 'false'
        description: Filter by local caller ID capability (true/false)
      - name: vendor_id
        in: query
        required: false
        schema:
          type: integer
        example: 6241
        description: Filter by vendor ID (requires special permission)
      - name: city_id
        in: query
        required: false
        schema:
          type: integer
        example: 1972
        description: Filter by city ID
      - name: region_id
        in: query
        required: false
        schema:
          type: integer
        example: 11
        description: Filter by region ID
      - name: require_docs
        in: query
        required: false
        schema:
          type: integer
        example: 1
        description: Filter by document requirements
      - name: commitment_months
        in: query
        required: false
        schema:
          type: integer
        example: 12
        description: Filter by commitment period in months
      - name: cheap_sorting
        in: query
        required: false
        schema:
          type: string
        example: 'false'
        description: Sort by price (activation + monthly fee) ascending
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
        description: Page number for pagination
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 25
        description: Number of items per page
      responses:
        '200':
          description: returns search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  dids:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                            example: 1
                            description: Total number of items
                          total_pages:
                            type: integer
                            example: 1
                            description: Total number of pages
                          current_page:
                            type: integer
                            example: 1
                            description: Current page number
                        required:
                        - total
                        - total_pages
                        - current_page
                        description: Pagination metadata
                      dids:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 2651
                              description: DID identifier
                            country:
                              type: string
                              example: United States
                              description: Country name
                            city:
                              type: string
                              example: NEW YORK CITY
                              description: City name
                            sms_enabled:
                              type: boolean
                              example: true
                              description: Whether SMS is available for this number
                            no_local_cli:
                              type: boolean
                              description: Whether number does not support local caller
                                ID
                            channels:
                              type: integer
                              example: 2
                              description: Maximum simultaneous calls
                            free_min:
                              type: integer
                              example: 100
                              description: Free minutes included per month
                            cnam:
                              type: boolean
                              description: Caller Name (CNAM) support
                            commitment_months:
                              type: integer
                              example: 12
                              description: Minimum service term in months
                            activation:
                              type: number
                              format: float
                              example: 2.925
                              description: One-time activation fee (USD)
                            monthly:
                              type: number
                              format: float
                              example: 0.9945
                              description: Monthly recurring fee (USD)
                            per_minute:
                              type: number
                              format: float
                              example: 0.117
                              description: Per-minute inbound call rate (USD)
                            origination_per_min:
                              nullable: true
                              description: Per-minute origination rate (USD)
                            required_documents:
                              type: array
                              items:
                                type: object
                                properties:
                                  type:
                                    type: integer
                                    example: 34
                                    description: Document type ID
                                  name:
                                    type: string
                                    example: Proof of Address
                                    description: Document type name
                                required:
                                - type
                                - name
                              description: List of required documents for this number
                            state:
                              type: string
                              example: ''
                              description: State name (if applicable)
                            country_short_name:
                              type: string
                              example: US
                              description: ISO country code
                            number:
                              type: string
                              example: '12125551234'
                              description: Phone number
                            never_sold:
                              type: integer
                              example: 1
                              description: Whether number has never been sold before
                                (1=yes, 0=no)
                            call_recording_enabled:
                              type: boolean
                          required:
                          - id
                          - country
                          - city
                          - sms_enabled
                          - no_local_cli
                          - channels
                          - free_min
                          - cnam
                          - commitment_months
                          - activation
                          - monthly
                          - per_minute
                          - origination_per_min
                          - required_documents
                          - state
                          - country_short_name
                          - number
                          - never_sold
                        description: Array of available DID numbers
                    required:
                    - pagination
                    - dids
                    description: Paginated search results
                required:
                - dids
              example:
                dids:
                  pagination:
                    total: 1
                    total_pages: 1
                    current_page: 1
                  dids:
                  - id: 2651
                    country: United States
                    city: NEW YORK CITY
                    sms_enabled: true
                    no_local_cli: false
                    channels: 2
                    free_min: 100
                    cnam: false
                    commitment_months: 12
                    required_documents:
                    - type: 34
                      name: Proof of Address
                    activation: 2.925
                    monthly: 0.9945
                    per_minute: 0.117
                    origination_per_min:
                    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.

        **Important notes:**
        - Returns only active numbers by default
        - Use `show_all=true` to include numbers pending document approval
        - Includes service information (SMS, etc.)
        - Shows current status of each number

        **When to use:**
        - Displaying user's number inventory
        - Checking number status
        - Listing numbers for configuration
        - Dashboard display

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      parameters:
      - name: show_all
        in: query
        required: false
        schema:
          type: string
        example: 'true'
        description: Include numbers pending documentation approval
      responses:
        '200':
          description: returns DIDs
          content:
            application/json:
              schema:
                type: object
                properties:
                  dids:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 2654
                          description: Unique DID identifier
                        number:
                          type: string
                          example: '1234567890'
                          description: Phone number
                        country:
                          type: string
                          example: United States
                          description: Country name where the number is located
                        area:
                          type: string
                          example: New York
                          description: City or area name
                        channels:
                          type: integer
                          example: 1
                          description: Number of simultaneous call channels
                        activation:
                          type: number
                          format: float
                          example: 1.17
                          description: One-time activation fee
                        monthly_fee:
                          type: number
                          format: float
                          example: 1.17
                          description: Monthly recurring fee
                        per_minute:
                          type: number
                          format: float
                          example: 0.117
                          description: Per-minute rate for incoming calls
                        services:
                          type: array
                          items:
                            type: string
                            enum:
                            - sms
                          description: List of enabled services (e.g., sms)
                        status:
                          type: string
                          enum:
                          - active
                          - pending_docs
                          example: active
                          description: Current status of the number
                        destination_count:
                          type: integer
                          example: 0
                          description: Number of configured routing destinations
                        call_recording_enabled:
                          type: boolean
                        commitment_months:
                          type: integer
                          example: 6
                          description: Minimum commitment period in months
                        identity_id:
                          type: integer
                          example: 198
                          description: Associated identity/document ID for verification
                      required:
                      - id
                      - number
                      - country
                      - area
                      - channels
                      - activation
                      - monthly_fee
                      - per_minute
                      - services
                      - status
                      - destination_count
                      - call_recording_enabled
                      - commitment_months
                      - identity_id
                    description: List of DID numbers owned by the user
                required:
                - dids
              example:
                dids:
                - id: 2654
                  number: '1234567890'
                  country: United States
                  area: New York
                  channels: 1
                  activation: 1.17
                  monthly_fee: 1.17
                  per_minute: 0.117
                  services:
                  - sms
                  status: active
                  destination_count: 0
                  call_recording_enabled: false
                  commitment_months: 6
                  identity_id: 198
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
  "/api/v2/numbers/purchase":
    post:
      summary: Purchase numbers
      description: |
        Purchase one or more DID numbers with identity document association.

        **Important notes:**
        - Can purchase multiple numbers in a single request
        - Identities must contain required documents for the number's country

        **When to use:**
        - Purchasing numbers with document verification
        - Bulk number purchase with identity association

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                id_in:
                  type: array
                  items:
                    type: string
                  description: Array of DID IDs to purchase
                  example:
                  - 2531
                  - 2532
                  - 2533
                did_numbers:
                  type: array
                  items:
                    type: string
                  description: Array of DID numbers to purchase
                  example:
                  - '1111111111'
                  - '2222222222'
                  - '3333333333'
                identities:
                  type: array
                  items:
                    type: object
                  description: Array of identity objects with document associations
                  example:
                  - id: 1188
                    did_ids:
                    - 12972
                  - id: 1189
                    did_numbers:
                    - '2222222222'
      responses:
        '200':
          description: purchase DIDs and link documents attached to identity
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchase:
                    type: object
                    properties:
                      errors:
                        type: object
                        properties: {}
                        description: Errors that occurred during purchase
                      purchases:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 12966
                              description: DID identifier
                            number:
                              type: string
                              example: '1111111111'
                              description: Purchased phone number
                            sms_enabled:
                              type: boolean
                              description: Whether SMS is enabled
                            no_local_cli:
                              type: boolean
                              description: Whether local caller ID is disabled
                            channels:
                              type: integer
                              example: 1
                              description: Maximum simultaneous calls
                            country:
                              type: string
                              example: c1
                              description: Country name
                            area:
                              type: string
                              example: Fake city for 1111111111
                              description: City/area name
                            free_minutes:
                              type: integer
                              example: 0
                              description: Free minutes included per month
                            codec:
                              nullable: true
                              description: Audio codec
                            require_docs:
                              type: string
                              example: '1,2,3'
                              description: Comma-separated list of required document
                                type IDs
                            commitment_months:
                              type: integer
                              example: 12
                              description: Minimum service term in months (omitted
                                when the commitment policy is disabled)
                            activation:
                              type: number
                              format: float
                              example: 1.17
                              description: One-time activation fee (USD)
                            monthly_fee:
                              type: number
                              format: float
                              example: 0.585
                              description: Monthly recurring fee (USD)
                            per_minute:
                              type: number
                              format: float
                              example: 0.117
                              description: Per-minute inbound call rate (USD)
                            origination_per_min:
                              type: number
                              format: float
                              example: 0.0
                              description: Per-minute origination rate (USD)
                            never_sold:
                              type: integer
                              example: 1
                              description: Whether number has never been sold before
                                (1=yes, 0=no)
                          required:
                          - id
                          - number
                          - sms_enabled
                          - no_local_cli
                          - channels
                          - country
                          - area
                          - free_minutes
                          - codec
                          - require_docs
                          - activation
                          - monthly_fee
                          - per_minute
                          - origination_per_min
                          - never_sold
                        description: Successfully purchased numbers
                    required:
                    - errors
                    - purchases
                    description: Purchase response object
                required:
                - purchase
              example:
                purchase:
                  errors: {}
                  purchases:
                  - id: 12966
                    number: '1111111111'
                    sms_enabled: false
                    no_local_cli: false
                    channels: 1
                    country: c1
                    area: Fake city for 1111111111
                    free_minutes: 0
                    codec:
                    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.0
                  - id: 12967
                    number: '2222222222'
                    sms_enabled: false
                    no_local_cli: false
                    channels: 1
                    country: c2
                    area: Fake city for 2222222222
                    free_minutes: 0
                    codec:
                    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.0
                  - id: 12968
                    number: '3333333333'
                    sms_enabled: false
                    no_local_cli: false
                    channels: 1
                    country: c2
                    area: Fake city for 3333333333
                    free_minutes: 0
                    codec:
                    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.0
        '400':
          description: returns bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                required:
                - error
              example:
                error: true
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '422':
          description: returns errors for unprocessed entities
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - type: object
                  properties:
                    purchase:
                      type: object
                      properties:
                        errors:
                          type: object
                          properties:
                            base:
                              type: array
                              items:
                                type: string
                          required:
                          - base
                          description: Errors that occurred during purchase
                        purchases:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 12972
                                description: DID identifier
                              number:
                                type: string
                                example: '1111111111'
                                description: Purchased phone number
                              sms_enabled:
                                type: boolean
                                description: Whether SMS is enabled
                              no_local_cli:
                                type: boolean
                                description: Whether local caller ID is disabled
                              channels:
                                type: integer
                                example: 1
                                description: Maximum simultaneous calls
                              country:
                                type: string
                                example: c1
                                description: Country name
                              area:
                                type: string
                                example: Fake city for 1111111111
                                description: City/area name
                              free_minutes:
                                type: integer
                                example: 0
                                description: Free minutes included per month
                              codec:
                                nullable: true
                                description: Audio codec
                              require_docs:
                                type: string
                                example: '1,2,3'
                                description: Comma-separated list of required document
                                  type IDs
                              commitment_months:
                                type: integer
                                example: 12
                                description: Minimum service term in months
                              activation:
                                type: number
                                format: float
                                example: 1.17
                                description: One-time activation fee (USD)
                              monthly_fee:
                                type: number
                                format: float
                                example: 0.585
                                description: Monthly recurring fee (USD)
                              per_minute:
                                type: number
                                format: float
                                example: 0.117
                                description: Per-minute inbound call rate (USD)
                              origination_per_min:
                                type: number
                                format: float
                                example: 0.0
                                description: Per-minute origination rate (USD)
                              never_sold:
                                type: integer
                                example: 1
                                description: Whether number has never been sold before
                                  (1=yes, 0=no)
                            required:
                            - id
                            - number
                            - sms_enabled
                            - no_local_cli
                            - channels
                            - country
                            - area
                            - free_minutes
                            - codec
                            - require_docs
                            - commitment_months
                            - activation
                            - monthly_fee
                            - per_minute
                            - origination_per_min
                            - never_sold
                          description: Successfully purchased numbers
                      required:
                      - errors
                      - purchases
                      description: Purchase response object
                  required:
                  - purchase
              examples:
                the_request_could_not_be_processed_because_one_or_more_fields_are_missing_or_invalid_see_errors_for_details:
                  summary: The request could not be processed because one or more
                    fields are missing or invalid. See `errors` for details.
                  value:
                    errors:
                      identities:
                      - is missing or malformed
                returns_errors_for_unprocessed_entities:
                  summary: returns errors for unprocessed entities
                  value:
                    purchase:
                      errors:
                        base:
                        - Low balance
                      purchases:
                      - id: 10145
                        number: '1111111111'
                        sms_enabled: false
                        no_local_cli: false
                        channels: 1
                        country: c1
                        area: Fake city for 1111111111
                        free_minutes: 0
                        codec:
                        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.0
                      - id: 10146
                        number: '2222222222'
                        sms_enabled: false
                        no_local_cli: false
                        channels: 1
                        country: c2
                        area: Fake city for 2222222222
                        free_minutes: 0
                        codec:
                        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.0
                      - id: 10147
                        number: '3333333333'
                        sms_enabled: false
                        no_local_cli: false
                        channels: 1
                        country: c2
                        area: Fake city for 3333333333
                        free_minutes: 0
                        codec:
                        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.0
    put:
      summary: Update purchased number settings
      description: |
        Update a purchased DID number's identity association or call recording setting.

        **Important notes:**
        - New identity must contain required documents for the number
        - `call_recording_enabled` requires the account-level "Allow call recording" setting to be on; returns 422 otherwise

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: DID ID
                  example: 13001
                identity_id:
                  type: integer
                  description: Identity ID to associate with the number
                  example: 1207
                call_recording_enabled:
                  type: string
                  description: Enable or disable inbound call recording for this DID
      responses:
        '200':
          description: updates purchased number
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchase:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 12998
                        description: DID identifier
                      number:
                        type: string
                        example: '1234567890'
                        description: Phone number
                      country:
                        type: string
                        example: US
                        description: Country name
                      area:
                        type: string
                        example: Fake city for 1234567890
                        description: City/area name
                      channels:
                        type: integer
                        example: 1
                        description: Maximum simultaneous calls
                      activation:
                        type: number
                        format: float
                        example: 1.17
                        description: One-time activation fee (USD)
                      monthly_fee:
                        type: number
                        format: float
                        example: 1.17
                        description: Monthly recurring fee (USD)
                      per_minute:
                        type: number
                        format: float
                        example: 0.117
                        description: Per-minute inbound call rate (USD)
                      services:
                        type: array
                        items: {}
                        description: Enabled services for this number
                      status:
                        type: string
                        enum:
                        - active
                        - pending_docs
                        example: pending_docs
                        description: Number status
                      destination_count:
                        type: integer
                        example: 0
                        description: Number of configured routing destinations
                      commitment_months:
                        type: integer
                        example: 12
                        description: Minimum service term in months (omitted when
                          the commitment policy is disabled)
                      identity_id:
                        type: integer
                        example: 1198
                        description: Associated identity ID
                      call_recording_enabled:
                        type: boolean
                        description: Whether inbound call recording is enabled for
                          this DID
                    required:
                    - id
                    - number
                    - country
                    - area
                    - channels
                    - activation
                    - monthly_fee
                    - per_minute
                    - services
                    - status
                    - destination_count
                    - identity_id
                    description: Updated purchase details
                  invalid_doc_types:
                    type: object
                    properties: {}
                    description: Document types that are invalid or missing
                required:
                - purchase
                - invalid_doc_types
              example:
                purchase:
                  id: 12998
                  number: '1234567890'
                  country: US
                  area: Fake city for 1234567890
                  channels: 1
                  activation: 1.17
                  monthly_fee: 1.17
                  per_minute: 0.117
                  services: []
                  status: pending_docs
                  destination_count: 0
                  commitment_months: 12
                  identity_id: 1198
                  call_recording_enabled: false
                invalid_doc_types: {}
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '422':
          description: returns unprocessable entity with validation error
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  identity_id:
                  - Identity not found or not accessible
        '500':
          description: The server could not complete the request. Retry later or contact
            support if the problem persists.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - internal server error
    delete:
      summary: Delete purchased numbers
      description: |
        Cancel purchase of DID numbers and return them to inventory.

        **Important notes:**
        - Can cancel multiple numbers in a single request
        - Numbers are returned to seller's inventory
        - Optional quarantine period before number becomes available again
        - Refund policy depends on service terms

        **When to use:**
        - User wants to cancel number purchase
        - Returning numbers after unsuccessful activation
        - Bulk number release

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`

        **Partial cancellation:** Numbers not present in your cancelable inventory
        are skipped (not cancelled) and reported in the `warnings` array with code
        `not_in_inventory`. If none of the requested numbers are cancelable, the
        request returns `422`.
      tags:
      - Numbers & Inventory
      security:
      - BearerAuth: []
      parameters:
      - name: id_in
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
        description: Array of DID IDs to cancel
        example:
        - 12903
        - 12904
        - 12905
        - 999999
      - name: did_numbers
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Array of DID numbers to cancel
        example:
        - '79090160041'
        - '79090160042'
        - '79090160043'
      responses:
        '200':
          description: cancels owned numbers and reports skipped ones as warnings
          content:
            application/json:
              schema:
                type: object
                properties:
                  dids:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 12897
                          description: DID identifier
                        number:
                          type: string
                          example: '79090160035'
                          description: Phone number
                        sms_enabled:
                          type: boolean
                          description: Whether SMS is enabled
                        no_local_cli:
                          type: boolean
                          description: Whether local caller ID is disabled
                        channels:
                          type: integer
                          example: 1
                          description: Maximum simultaneous calls
                        country:
                          type: string
                          example: Fake country for 79090160035
                          description: Country name
                        area:
                          type: string
                          example: Fake city for 79090160035
                          description: City/area name
                        free_minutes:
                          type: integer
                          example: 0
                          description: Free minutes included per month
                        codec:
                          nullable: true
                          description: Audio codec
                        require_docs:
                          type: string
                          example: ''
                          description: Comma-separated list of required document type
                            IDs
                        commitment_months:
                          type: integer
                          example: 12
                          description: Minimum service term in months
                        activation:
                          type: number
                          format: float
                          example: 1.17
                          description: One-time activation fee (USD)
                        monthly_fee:
                          type: number
                          format: float
                          example: 1.17
                          description: Monthly recurring fee (USD)
                        per_minute:
                          type: number
                          format: float
                          example: 0.117
                          description: Per-minute inbound call rate (USD)
                        origination_per_min:
                          type: number
                          format: float
                          example: 0.0
                          description: Per-minute origination rate (USD)
                        never_sold:
                          type: integer
                          example: 0
                          description: Whether number has never been sold before (1=yes,
                            0=no)
                      required:
                      - id
                      - number
                      - sms_enabled
                      - no_local_cli
                      - channels
                      - country
                      - area
                      - free_minutes
                      - codec
                      - require_docs
                      - commitment_months
                      - activation
                      - monthly_fee
                      - per_minute
                      - origination_per_min
                      - never_sold
                    description: List of cancelled DIDs returned to inventory
                  warnings:
                    type: array
                    description: Non-fatal notices for requested numbers that were
                      not in your cancelable inventory and were skipped. Present only
                      when non-empty.
                    items:
                      "$ref": "#/components/schemas/Warning"
                required:
                - dids
              example:
                dids:
                - id: 12897
                  number: '79090160035'
                  sms_enabled: false
                  no_local_cli: false
                  channels: 1
                  country: Fake country for 79090160035
                  area: Fake city for 79090160035
                  free_minutes: 0
                  codec:
                  require_docs: ''
                  commitment_months: 12
                  never_sold: 0
                  activation: 1.17
                  monthly_fee: 1.17
                  per_minute: 0.117
                  origination_per_min: 0.0
                - id: 12898
                  number: '79090160036'
                  sms_enabled: false
                  no_local_cli: false
                  channels: 1
                  country: Fake country for 79090160035
                  area: Fake city for 79090160035
                  free_minutes: 0
                  codec:
                  require_docs: ''
                  commitment_months: 12
                  never_sold: 0
                  activation: 1.17
                  monthly_fee: 1.17
                  per_minute: 0.117
                  origination_per_min: 0.0
                - id: 12899
                  number: '79090160037'
                  sms_enabled: false
                  no_local_cli: false
                  channels: 1
                  country: Fake country for 79090160035
                  area: Fake city for 79090160035
                  free_minutes: 0
                  codec:
                  require_docs: ''
                  commitment_months: 12
                  never_sold: 0
                  activation: 1.17
                  monthly_fee: 1.17
                  per_minute: 0.117
                  origination_per_min: 0.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.

        Returns information about all risk check tasks created by your organization,
        including task status, number counts, and processing timestamps. Supports filtering by various criteria and pagination.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Risk Checks
      security:
      - BearerAuth: []
      parameters:
      - name: task_ids
        in: query
        required: false
        schema:
          type: string
        example: '15,16'
        description: Filter tasks by task IDs (comma-separated)
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
        example: completed,pending,failed
        description: Filter by status
      - name: created_at_from
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-15'
        description: Filter created from this date (YYYY-MM-DD)
      - name: created_at_to
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-17'
        description: Filter created until this date (YYYY-MM-DD)
      - name: processed_at_from
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-15'
        description: Filter processed from this date (YYYY-MM-DD)
      - name: processed_at_to
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-17'
        description: Filter processed until this date (YYYY-MM-DD)
      - name: order_by
        in: query
        required: false
        schema:
          type: string
        example: created_at
        description: Field to sort by
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: desc
        description: Sort order
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
        description: Page number for pagination (starts from 1)
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 10
        description: Number of items per page
      responses:
        '200':
          description: returns risk check tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 8
                          description: Task identifier
                        status:
                          type: string
                          enum:
                          - pending
                          - completed
                          - failed
                          example: pending
                          description: Task status
                        total_numbers:
                          type: integer
                          example: 1
                          description: Total numbers in the task
                        completed_count:
                          type: integer
                          example: 0
                          description: Number of completed checks
                        failed_count:
                          type: integer
                          example: 0
                          description: Number of failed checks
                        pending_count:
                          type: integer
                          example: 1
                          description: Number of pending checks
                        processed_at:
                          type: string
                          example: '2026-04-16T09:28:16Z'
                          description: Processing completion timestamp
                        created_at:
                          type: string
                          example: '2026-04-16T09:28:16Z'
                          description: Task creation timestamp
                      required:
                      - id
                      - status
                      - total_numbers
                      - completed_count
                      - failed_count
                      - pending_count
                      - processed_at
                      - created_at
                    description: List of risk check tasks
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 2
                        description: Total number of items
                      total_pages:
                        type: integer
                        example: 1
                        description: Total number of pages
                      current_page:
                        type: integer
                        example: 1
                        description: Current page number
                      per_page:
                        type: integer
                        example: 10
                        description: Items per page
                    required:
                    - total
                    - total_pages
                    - current_page
                    - per_page
                    description: Pagination metadata
                required:
                - tasks
                - pagination
              example:
                tasks:
                - id: 8
                  status: pending
                  processed_at: '2026-04-16T09:28:16Z'
                  created_at: '2026-04-16T09:28:16Z'
                  total_numbers: 1
                  completed_count: 0
                  failed_count: 0
                  pending_count: 1
                - id: 7
                  status: completed
                  processed_at: '2026-04-16T09:28:16Z'
                  created_at: '2026-04-16T09:28:16Z'
                  total_numbers: 5
                  completed_count: 5
                  failed_count: 0
                  pending_count: 0
                pagination:
                  total: 2
                  total_pages: 1
                  current_page: 1
                  per_page: 10
        '401':
          description: returns unauthorized for without authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden for without access to risk checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access to API V2 risk checks is forbidden
    post:
      summary: Create risk check
      description: |
        Creates a new risk check task for the provided phone numbers (maximum 1500 numbers per request).

        Use the returned task ID to check the status and retrieve results via the tasks and logs endpoints.

        **Note:** Results are informational only. Use at your own discretion.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Risk Checks
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                numbers:
                  type: array
                  items:
                    type: string
                  description: Array of phone numbers to check for risk
                  example:
                  - '79991234567'
                  - '79991234568'
      responses:
        '201':
          description: returns created risk check task
          content:
            application/json:
              schema:
                type: object
                properties:
                  risk_check_request:
                    type: object
                    properties:
                      task_id:
                        type: integer
                        example: 19
                        description: Task identifier
                      status:
                        type: string
                        enum:
                        - pending
                        - completed
                        - failed
                        example: pending
                        description: Task status
                      total_numbers:
                        type: integer
                        example: 2
                        description: Total numbers in the request
                      processed_at:
                        nullable: true
                        description: Processing completion timestamp
                      created_at:
                        type: string
                        example: '2026-04-16T09:28:20Z'
                        description: Task creation timestamp
                    required:
                    - task_id
                    - status
                    - total_numbers
                    - processed_at
                    - created_at
                    description: Created risk check task details
                required:
                - risk_check_request
              example:
                risk_check_request:
                  task_id: 19
                  status: pending
                  total_numbers: 2
                  processed_at:
                  created_at: '2026-04-16T09:28:20Z'
        '401':
          description: returns unauthorized for without authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden for without access to risk checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access to API V2 risk checks is forbidden
        '422':
          description: returns unprocessable entity when another risk check is already
            running
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/Error"
                - oneOf:
                  - type: object
                    properties:
                      errors:
                        type: object
                        properties:
                          numbers:
                            type: array
                            items:
                              type: string
                        required:
                        - numbers
                    required:
                    - errors
                  - type: object
                    properties:
                      error:
                        type: string
                    required:
                    - error
              examples:
                returns_unprocessable_entity_for_empty_numbers:
                  summary: returns unprocessable entity for empty numbers
                  value:
                    errors:
                      numbers:
                      - Required
                returns_unprocessable_entity_when_another_risk_check_is_already_running:
                  summary: returns unprocessable entity when another risk check is
                    already running
                  value:
                    error: Previous check is still in progress
  "/api/v2/numbers/risk_checks/logs":
    get:
      summary: List risk check logs
      description: |
        Retrieves risk check logs for individual phone numbers.

        Returns detailed information about each number that was checked, including its risk level,
        status, and processing time. Supports filtering by various criteria and pagination.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Risk Checks
      security:
      - BearerAuth: []
      parameters:
      - name: ids
        in: query
        required: false
        schema:
          type: string
        example: '9,10'
        description: Filter logs by log IDs (comma-separated)
      - name: task_ids
        in: query
        required: false
        schema:
          type: integer
        example: 5
        description: Filter logs by task IDs (comma-separated)
      - name: number
        in: query
        required: false
        schema:
          type: string
        example: '79991234567,79991234568'
        description: Filter logs by specific phone numbers (comma-separated)
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
        example: completed,pending,failed
        description: Filter by status
      - name: risk_level
        in: query
        required: false
        schema:
          type: string
          enum:
          - Low
          - High
        example: High,Low
        description: Filter logs by risk level
      - name: created_at_from
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-15'
        description: Filter created from this date (YYYY-MM-DD)
      - name: created_at_to
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-17'
        description: Filter created until this date (YYYY-MM-DD)
      - name: processed_at_from
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-15'
        description: Filter processed from this date (YYYY-MM-DD)
      - name: processed_at_to
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-17'
        description: Filter processed until this date (YYYY-MM-DD)
      - name: order_by
        in: query
        required: false
        schema:
          type: string
        example: created_at
        description: Field to sort by
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: desc
        description: Sort order
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
        description: Page number for pagination (starts from 1)
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 10
        description: Number of items per page
      responses:
        '200':
          description: returns risk check logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 2
                          description: Log identifier
                        number:
                          type: string
                          example: '79991234568'
                          description: Phone number that was checked
                        status:
                          type: string
                          enum:
                          - pending
                          - completed
                          - failed
                          example: completed
                          description: Check status
                        risk_level:
                          type: string
                          enum:
                          - Low
                          - High
                          example: Low
                          description: Risk assessment level
                        category:
                          nullable: true
                          description: Risk category
                        task_id:
                          type: integer
                          example: 1
                          description: Parent task identifier
                        processed_at:
                          type: string
                          example: '2026-04-16T09:28:07Z'
                          description: Processing completion timestamp
                        created_at:
                          type: string
                          example: '2026-04-16T09:28:07Z'
                          description: Log creation timestamp
                      required:
                      - id
                      - number
                      - status
                      - risk_level
                      - category
                      - task_id
                      - processed_at
                      - created_at
                    description: List of risk check logs
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 2
                        description: Total number of items
                      total_pages:
                        type: integer
                        example: 1
                        description: Total number of pages
                      current_page:
                        type: integer
                        example: 1
                        description: Current page number
                      per_page:
                        type: integer
                        example: 10
                        description: Items per page
                    required:
                    - total
                    - total_pages
                    - current_page
                    - per_page
                    description: Pagination metadata
                required:
                - logs
                - pagination
              example:
                logs:
                - id: 2
                  number: '79991234568'
                  status: completed
                  risk_level: Low
                  category:
                  task_id: 1
                  processed_at: '2026-04-16T09:28:07Z'
                  created_at: '2026-04-16T09:28:07Z'
                - id: 1
                  number: '79991234567'
                  status: completed
                  risk_level: High
                  category: SPAMMER
                  task_id: 1
                  processed_at: '2026-04-16T09:28:07Z'
                  created_at: '2026-04-16T09:28:07Z'
                pagination:
                  total: 2
                  total_pages: 1
                  current_page: 1
                  per_page: 10
        '401':
          description: returns unauthorized for without authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden for without access to risk checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access to API V2 risk checks is forbidden
  "/api/v2/hlr":
    post:
      summary: Create HLR lookup
      description: |
        Submits phone numbers for an HLR (Home Location Register) lookup
        (maximum 1500 numbers per request).

        Numbers must be supplied in **E.164 format** (e.g. `+14155552671`); a leading `+`
        is added automatically when omitted.

        A single number resolves synchronously; larger batches are processed asynchronously — poll
        the history endpoint (`GET /api/v2/hlr/history`) for results. Lookups are performed
        independently of call setup and do not affect PDD. Results are not cached: each request
        re-queries the provider.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - HLR Lookups
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                numbers:
                  type: array
                  items:
                    type: string
                  description: Array of phone numbers in E.164 format (e.g. +14155552671)
                  example:
                  - '12125551234'
      responses:
        '201':
          description: returns the created HLR lookup task
          content:
            application/json:
              schema:
                type: object
                properties:
                  hlr_request:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - pending
                        - completed
                        - failed
                        example: pending
                        description: Task status
                      processed_at:
                        nullable: true
                        description: Processing completion timestamp
                      created_at:
                        type: string
                        example: '2026-06-18T07:29:01Z'
                        description: Task creation timestamp
                      task_id:
                        type: integer
                        example: 51
                        description: Task identifier
                      total_numbers:
                        type: integer
                        example: 2
                        description: Total numbers in the request
                    required:
                    - status
                    - processed_at
                    - created_at
                    - task_id
                    - total_numbers
                    description: Created HLR lookup task details
                required:
                - hlr_request
              example:
                hlr_request:
                  status: pending
                  processed_at:
                  created_at: '2026-06-18T07:29:01Z'
                  task_id: 51
                  total_numbers: 2
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '403':
          description: returns forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Access to API V2 HLR is forbidden
        '422':
          description: returns unprocessable entity for validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              examples:
                returns_unprocessable_entity:
                  summary: returns unprocessable entity
                  value:
                    error: Previous check is still in progress
                returns_unprocessable_entity_for_validation_errors:
                  summary: returns unprocessable entity for validation errors
                  value:
                    error: No phone numbers provided
                returns_unprocessable_entity_for_validation_errors_3:
                  summary: returns unprocessable entity for validation errors
                  value:
                    error: Phone number is too long (max 50 characters)
  "/api/v2/hlr/history":
    get:
      summary: List HLR lookup history
      description: |
        Returns the caller's HLR lookup logs — one per number checked — with the lookup result
        (validity, carrier, MCC/MNC, phone type, ported and risky flags, country). Supports
        filtering by number prefix, status, and date ranges, plus pagination.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - HLR Lookups
      security:
      - BearerAuth: []
      parameters:
      - name: ids
        in: query
        required: false
        schema:
          type: string
        description: Filter logs by log IDs (comma-separated)
      - name: task_ids
        in: query
        required: false
        schema:
          type: string
        description: Filter logs by task IDs (comma-separated)
      - name: number
        in: query
        required: false
        schema:
          type: string
        description: Filter logs by specific phone numbers (comma-separated)
      - name: number_start
        in: query
        required: false
        schema:
          type: integer
        example: 1212
        description: Filter logs by phone-number prefix (starts-with)
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
        example: completed,pending,failed
        description: Filter by status
      - name: created_at_from
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-06-17'
        description: Filter created from this date (YYYY-MM-DD)
      - name: created_at_to
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-06-19'
        description: Filter created until this date (YYYY-MM-DD)
      - name: processed_at_from
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter processed from this date (YYYY-MM-DD)
      - name: processed_at_to
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter processed until this date (YYYY-MM-DD)
      - name: order_by
        in: query
        required: false
        schema:
          type: string
        example: created_at
        description: Field to sort by
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: desc
        description: Sort order
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
        description: Page number for pagination (starts from 1)
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 10
        description: Number of items per page
      responses:
        '200':
          description: returns the caller HLR logs filtered by number prefix
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 57
                          description: Log identifier
                        number:
                          type: string
                          example: '12125551234'
                          description: Phone number that was checked
                        status:
                          type: string
                          enum:
                          - pending
                          - completed
                          - failed
                          example: completed
                          description: Lookup status
                        phone_type:
                          type: string
                          example: mobile
                          description: Line type (e.g. mobile, fixed)
                        carrier:
                          type: string
                          example: Acme Telecom
                          description: Carrier / operator name
                        mcc:
                          type: string
                          example: '310'
                          description: Mobile Country Code
                        mnc:
                          type: string
                          example: '260'
                          description: Mobile Network Code
                        ported:
                          type: boolean
                          description: Whether the number was ported
                        risky:
                          type: boolean
                          description: Whether the destination is flagged risky
                        country:
                          type: string
                          example: US
                          description: Country
                        task_id:
                          type: integer
                          example: 45
                          description: Parent task identifier
                        processed_at:
                          type: string
                          example: '2026-06-18T07:29:00Z'
                          description: Processing completion timestamp
                        created_at:
                          type: string
                          example: '2026-06-18T07:29:00Z'
                          description: Log creation timestamp
                        valid:
                          type: boolean
                          example: true
                          description: Whether the number is valid
                        price:
                          type: string
                          example: '0.07'
                          description: Client price charged for this lookup (USD)
                        error_code:
                          nullable: true
                          enum:
                          - '000'
                          - '113'
                          - '121'
                          - '199'
                          description: 'Normalized lookup error code: 000 — OK, 113
                            — Internal service error, 121 — Invalid phone number length
                            or format, 199 — Unexpected error. null when no result
                            is available yet.'
                          type: string
                      required:
                      - id
                      - number
                      - status
                      - phone_type
                      - carrier
                      - mcc
                      - mnc
                      - ported
                      - risky
                      - country
                      - task_id
                      - processed_at
                      - created_at
                      - valid
                      - price
                      - error_code
                    description: List of HLR lookup logs
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 1
                        description: Total number of items
                      total_pages:
                        type: integer
                        example: 1
                        description: Total number of pages
                      current_page:
                        type: integer
                        example: 1
                        description: Current page number
                      per_page:
                        type: integer
                        example: 10
                        description: Items per page
                    required:
                    - total
                    - total_pages
                    - current_page
                    - per_page
                    description: Pagination metadata
                required:
                - logs
                - pagination
              example:
                logs:
                - id: 57
                  number: '12125551234'
                  status: completed
                  phone_type: mobile
                  carrier: Acme Telecom
                  mcc: '310'
                  mnc: '260'
                  ported: false
                  risky: false
                  country: US
                  task_id: 45
                  processed_at: '2026-06-18T07:29:00Z'
                  created_at: '2026-06-18T07:29:00Z'
                  valid: true
                  price: '0.07'
                  error_code:
                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.

        **Important notes:**
        - Supports filtering by approval status, identity ID, and date range
        - Results can be sorted and paginated

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - KYC Documents
      security:
      - BearerAuth: []
      parameters:
      - name: ids
        in: query
        required: false
        schema:
          type: string
        example: '1022,1023'
        description: Filter documents by IDs (comma-separated)
      - name: identity_id
        in: query
        required: false
        schema:
          type: integer
        example: 1134
        description: Filter documents by identity ID
      - name: approvement_status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - expired
        example: approved
        description: Filter documents by approval status
      - name: upload_date_from
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-09T11:11:13Z'
        description: Filter documents created from this date
      - name: upload_date_to
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-11T11:11:13Z'
        description: Filter documents created until this date
      - name: order_by
        in: query
        required: false
        schema:
          type: string
        example: created_at
        description: Field to sort by
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: asc
        description: Sort order
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
        description: Page number for pagination (starts from 1)
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 10
        description: Number of items per page
      responses:
        '200':
          description: returns documents from specified identity
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: Document 1
                          description: Document name
                        id:
                          type: integer
                          example: 1016
                          description: Document identifier
                        user_id:
                          type: integer
                          example: 15374
                          description: Owner user ID
                        country:
                          type: string
                          example: US
                          description: Country code
                        created_at:
                          type: string
                          example: '2026-04-10T11:11:13Z'
                          description: Upload timestamp
                        doc_type:
                          type: string
                          enum:
                          - Personal ID
                          - Proof of address
                          example: Proof of address
                          description: Document type identifier
                        approvement_status:
                          type: string
                          enum:
                          - pending
                          - approved
                          - rejected
                          - expired
                          example: verified
                          description: Document approval status
                        identity_id:
                          type: integer
                          example: 1132
                          description: Associated identity ID
                        identity:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1132
                              description: Identity identifier
                            name:
                              type: string
                              example: Paper Box 23
                              description: Identity name
                            user_id:
                              type: integer
                              example: 15374
                              description: Owner user ID
                            created_at:
                              type: string
                              example: '2026-04-10T11:11:13Z'
                              description: Identity creation timestamp
                            persistence_status:
                              type: string
                              enum:
                              - active
                              - archived
                              - active-immortal
                              example: active
                              description: Identity persistence status
                            is_default:
                              type: boolean
                              description: Is default identity flag
                          required:
                          - id
                          - name
                          - user_id
                          - created_at
                          - persistence_status
                          - is_default
                          description: Identity details
                        expired_at:
                          type: string
                          example: '2027-04-10T11:11:13Z'
                          description: Document expiration timestamp
                        files:
                          type: array
                          items:
                            type: object
                            properties:
                              role:
                                type: string
                                example: frontside
                                description: File role (frontside, backside)
                              label:
                                type: string
                                example: File
                                description: File label
                              url:
                                type: string
                                example: "/api/v2/documents/1016/files/frontside"
                                description: File download URL
                              name:
                                type: string
                                example: test.png
                                description: Original file name
                            required:
                            - role
                            - label
                            - url
                            - name
                          description: Document files
                      required:
                      - name
                      - id
                      - user_id
                      - country
                      - created_at
                      - doc_type
                      - approvement_status
                      - identity_id
                      - identity
                      - expired_at
                      - files
                    description: List of documents
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 2
                        description: Total number of items
                      total_pages:
                        type: integer
                        example: 1
                        description: Total number of pages
                      current_page:
                        type: integer
                        example: 1
                        description: Current page number
                      per_page:
                        type: integer
                        example: 10
                        description: Items per page
                    required:
                    - total
                    - total_pages
                    - current_page
                    - per_page
                    description: Pagination metadata
                required:
                - documents
                - pagination
              example:
                documents:
                - name: Document 1
                  id: 1016
                  user_id: 15374
                  country: US
                  created_at: '2026-04-10T11:11:13Z'
                  expired_at: '2027-04-10T11:11:13Z'
                  approvement_status: verified
                  doc_type: Proof of address
                  identity_id: 1132
                  identity:
                    id: 1132
                    name: Paper Box 23
                    user_id: 15374
                    created_at: '2026-04-10T11:11:13Z'
                    persistence_status: active
                    is_default: false
                  files:
                  - role: frontside
                    label: File
                    url: "/api/v2/documents/1016/files/frontside"
                    name: test.png
                - name: Document 2
                  id: 1017
                  user_id: 15374
                  country: US
                  created_at: '2026-04-10T11:11:13Z'
                  expired_at: '2027-04-10T11:11:13Z'
                  approvement_status: verified
                  doc_type: Proof of address
                  identity_id: 1132
                  identity:
                    id: 1132
                    name: Paper Box 23
                    user_id: 15374
                    created_at: '2026-04-10T11:11:13Z'
                    persistence_status: active
                    is_default: false
                  files:
                  - role: frontside
                    label: File
                    url: "/api/v2/documents/1017/files/frontside"
                    name: test.png
                pagination:
                  total: 2
                  total_pages: 1
                  current_page: 1
                  per_page: 10
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
    post:
      summary: Upload document
      description: |
        Upload a new document for identity verification.

        **Document Types:**
        - `personal_id` - Personal ID
        - `address_proof` - Proof of address

        **File Requirements:**
        - Allowed extensions: jpg, jpeg, png, pdf
        - Accepted MIME types: ["image/jpeg", "image/png", "application/pdf"]

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - KYC Documents
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document[name]:
                  type: string
                  description: Document name
                  example: Test Document
                document[doc_type]:
                  type: string
                  description: Document type
                  enum:
                  - personal_id
                  - address_proof
                  example: personal_id
                document[files][frontside]:
                  type: string
                  format: binary
                  description: Frontside file upload (binary)
                document[files][backside]:
                  type: string
                  format: binary
                  description: Backside file upload (binary, Personal ID only)
                document[identity_id]:
                  type: integer
                  description: Identity ID to associate the document with
                  example: 1093
                document[country]:
                  type: string
                  description: Country code (optional)
                  example: UK
              required:
              - document[name]
              - document[doc_type]
              - document[files][frontside]
              - document[identity_id]
      responses:
        '200':
          description: creates a new document
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Document created
                    description: Success message
                  document_id:
                    type: integer
                    example: 977
                    description: Created document ID
                  document:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Test Document
                        description: Document name
                      id:
                        type: integer
                        example: 977
                        description: Document identifier
                      user_id:
                        type: integer
                        example: 15122
                        description: Owner user ID
                      country:
                        type: string
                        example: UK
                        description: Country code
                      created_at:
                        type: string
                        example: '2026-04-10T11:10:52Z'
                        description: Upload timestamp
                      doc_type:
                        type: string
                        enum:
                        - Personal ID
                        - Proof of address
                        example: Personal ID
                        description: Document type identifier
                      approvement_status:
                        type: string
                        enum:
                        - pending
                        - approved
                        - rejected
                        - expired
                        example: in review
                        description: Document approval status
                      identity_id:
                        type: integer
                        example: 1088
                        description: Associated identity ID
                      identity:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1088
                            description: Identity identifier
                          name:
                            type: string
                            example: Paper Box 4
                            description: Identity name
                          user_id:
                            type: integer
                            example: 15122
                            description: Owner user ID
                          created_at:
                            type: string
                            example: '2026-04-10T11:10:52Z'
                            description: Identity creation timestamp
                          persistence_status:
                            type: string
                            enum:
                            - active
                            - archived
                            - active-immortal
                            example: active
                            description: Identity persistence status
                          is_default:
                            type: boolean
                            description: Is default identity flag
                        required:
                        - id
                        - name
                        - user_id
                        - created_at
                        - persistence_status
                        - is_default
                        description: Identity details
                      expired_at:
                        nullable: true
                        description: Document expiration timestamp
                      files:
                        type: array
                        items:
                          type: object
                          properties:
                            role:
                              type: string
                            label:
                              type: string
                            url:
                              type: string
                            name:
                              type: string
                          required:
                          - role
                          - label
                          - url
                          - name
                        description: Uploaded document files
                    required:
                    - name
                    - id
                    - user_id
                    - country
                    - created_at
                    - doc_type
                    - approvement_status
                    - identity_id
                    - identity
                    - expired_at
                    - files
                    description: Created document details
                required:
                - message
                - document_id
                - document
              example:
                message: Document created
                document_id: 977
                document:
                  name: Test Document
                  id: 977
                  user_id: 15122
                  country: UK
                  created_at: '2026-04-10T11:10:52Z'
                  doc_type: Personal ID
                  approvement_status: in review
                  identity_id: 1088
                  identity:
                    id: 1088
                    name: Paper Box 4
                    user_id: 15122
                    created_at: '2026-04-10T11:10:52Z'
                    persistence_status: active
                    is_default: false
                  expired_at:
                  files:
                  - role: backside
                    label: Backside
                    url: "/api/v2/documents/977/files/backside"
                    name: test.png
                  - role: backside
                    label: Backside
                    url: "/api/v2/documents/977/files/backside"
                    name: test.png
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '422':
          description: returns unprocessable entity
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              examples:
                field_validation:
                  summary: One or more document fields failed validation
                  value:
                    errors:
                      name:
                      - Required
                      country:
                      - Is missing
                      backside:
                      - Required
                malformed_document:
                  summary: The document payload is missing or malformed
                  value:
                    errors:
                      document:
                      - is missing or malformed
              example:
                errors:
                  name:
                  - Required
                  country:
                  - Is missing
                  backside:
                  - Required
  "/api/v2/documents/{id}":
    put:
      summary: Update document
      description: |
        Update an existing document's name or identity.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - KYC Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 988
        description: Document ID
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document[name]:
                  type: string
                  description: Updated document name
                  example: Updated Name
                document[identity_id]:
                  type: integer
                  description: Updated identity ID
                  example: 1112
      responses:
        '200':
          description: updates the document
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Document updated
                    description: Success message
                  document_id:
                    type: integer
                  document:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Updated Name
                        description: Document name
                      id:
                        type: integer
                        example: 984
                        description: Document identifier
                      user_id:
                        type: integer
                        example: 15214
                        description: Owner user ID
                      country:
                        type: string
                        example: US
                        description: Country code
                      created_at:
                        type: string
                        example: '2026-04-10T11:11:02Z'
                        description: Upload timestamp
                      doc_type:
                        type: string
                        enum:
                        - Personal ID
                        - Proof of address
                        example: Personal ID
                        description: Document type identifier
                      approvement_status:
                        type: string
                        enum:
                        - pending
                        - approved
                        - rejected
                        - expired
                        example: in review
                        description: Document approval status
                      identity_id:
                        type: integer
                        example: 1105
                        description: Associated identity ID
                      identity:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1105
                            description: Identity identifier
                          name:
                            type: string
                            example: New Box
                            description: Identity name
                          user_id:
                            type: integer
                            example: 15214
                            description: Owner user ID
                          created_at:
                            type: string
                            example: '2026-04-10T11:11:02Z'
                            description: Identity creation timestamp
                          persistence_status:
                            type: string
                            enum:
                            - active
                            - archived
                            - active-immortal
                            example: active
                            description: Identity persistence status
                          is_default:
                            type: boolean
                            description: Is default identity flag
                        required:
                        - id
                        - name
                        - user_id
                        - created_at
                        - persistence_status
                        - is_default
                        description: Identity details
                      expired_at:
                        type: string
                        example: '2026-04-20T11:11:02Z'
                        description: Document expiration timestamp
                      files:
                        type: array
                        items:
                          type: object
                          properties:
                            role:
                              type: string
                            label:
                              type: string
                            url:
                              type: string
                            name:
                              type: string
                          required:
                          - role
                          - label
                          - url
                          - name
                    required:
                    - name
                    - id
                    - user_id
                    - country
                    - created_at
                    - doc_type
                    - approvement_status
                    - identity_id
                    - identity
                    - expired_at
                    - files
                    description: Updated document details
                required:
                - message
                - document_id
                - document
              example:
                message: Document updated
                document_id: 984
                document:
                  name: Updated Name
                  id: 984
                  user_id: 15214
                  country: US
                  created_at: '2026-04-10T11:11:02Z'
                  doc_type: Personal ID
                  approvement_status: in review
                  identity_id: 1105
                  identity:
                    id: 1105
                    name: New Box
                    user_id: 15214
                    created_at: '2026-04-10T11:11:02Z'
                    persistence_status: active
                    is_default: false
                  expired_at: '2026-04-20T11:11:02Z'
                  files:
                  - role: frontside
                    label: File
                    url: "/api/v2/documents/984/files/frontside"
                    name: test.png
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
        '422':
          description: returns unprocessable entity
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  name:
                  - Required
    delete:
      summary: Delete document
      description: |
        Delete a document by ID.

        **Important notes:**
        - Document is permanently removed
        - Cannot be undone

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - KYC Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 1034
        description: Document ID
      responses:
        '204':
          description: deletes the document
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
    get:
      summary: Get document
      description: |
        Get a document by ID.

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - KYC Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 1028
        description: Document ID
      responses:
        '200':
          description: returns the document details
          content:
            application/json:
              schema:
                type: object
                properties:
                  document:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Test Document 6b82649a
                        description: Document name
                      id:
                        type: integer
                        example: 1025
                        description: Document identifier
                      user_id:
                        type: integer
                      country:
                        type: string
                      created_at:
                        type: string
                      doc_type:
                        type: string
                        example: Personal ID
                        description: Document type identifier
                      approvement_status:
                        type: string
                        example: in review
                        description: Document approval status
                      identity_id:
                        nullable: true
                      identity:
                        nullable: true
                      expired_at:
                        type: string
                      files:
                        type: array
                        items:
                          type: object
                          properties:
                            role:
                              type: string
                            label:
                              type: string
                            url:
                              type: string
                            name:
                              type: string
                          required:
                          - role
                          - label
                          - url
                          - name
                        description: Uploaded document files
                    required:
                    - name
                    - id
                    - user_id
                    - country
                    - created_at
                    - doc_type
                    - approvement_status
                    - identity_id
                    - identity
                    - expired_at
                    - files
                required:
                - document
              example:
                document:
                  name: Test Document 6b82649a
                  id: 1025
                  user_id: 15391
                  country: US
                  created_at: '2026-04-10T11:11:14Z'
                  doc_type: Personal ID
                  approvement_status: in review
                  identity_id:
                  identity:
                  expired_at: '2026-04-20T11:11:14Z'
                  files:
                  - role: frontside
                    label: File
                    url: "/api/v2/documents/1025/files/frontside"
                    name: test.png
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: The requested resource could not be found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
  "/api/v2/documents/countries":
    get:
      summary: List document countries
      description: |
        Retrieve a list of countries available for document filtering.

        **When to use:**
        - Building country filter dropdown for documents
        - Finding documents by country
        - Searching countries by name pattern

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - KYC Documents
      security:
      - BearerAuth: []
      parameters:
      - name: name_contains
        in: query
        required: false
        schema:
          type: string
        example: land
        description: Filter countries by name pattern (case-insensitive substring
          match)
      responses:
        '200':
          description: returns list of countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: Poland
                          description: Country name
                      required:
                      - name
                    description: List of countries available for document filtering
                required:
                - countries
              example:
                countries:
                - name: Poland
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
  "/api/v2/documents/{id}/files/{role}":
    get:
      summary: Download document file by role
      description: |
        Download a specific document file by role (frontside/backside).

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - KYC Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 1065
        description: Document ID
      - name: role
        in: path
        required: true
        schema:
          type: string
          enum:
          - frontside
          - backside
        example: frontside
        description: File role
      responses:
        '200':
          description: returns file with proper headers and content
          content:
            image/png:
              schema:
                type: string
                format: binary
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  base:
                  - data not found
  "/api/v2/identities":
    get:
      summary: List identities
      description: |
        Retrieve a list of identities with filtering and pagination.

        **Important notes:**
        - Supports filtering by name, IDs, and date range
        - Results can be sorted and paginated

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Identities
      security:
      - BearerAuth: []
      parameters:
      - name: ids
        in: query
        required: false
        schema:
          type: string
        example: '1159,1160'
        description: Filter identities by IDs (comma-separated)
      - name: name
        in: query
        required: false
        schema:
          type: string
        example: box
        description: Filter identities by name (partial match)
      - name: created_at_from
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-09T11:11:20Z'
        description: Filter identities created from this date (YYYY-MM-DD)
      - name: created_at_to
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2026-04-11T11:11:20Z'
        description: Filter identities created until this date (YYYY-MM-DD)
      - name: order_by
        in: query
        required: false
        schema:
          type: string
        example: name
        description: Field to sort by
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: asc
        description: Sort order
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
        description: Page number for pagination (starts from 1)
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 10
        description: Number of items per page
      responses:
        '200':
          description: returns identities with documents count
          content:
            application/json:
              schema:
                type: object
                properties:
                  identities:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1150
                          description: Identity identifier
                        name:
                          type: string
                          example: Box 1
                          description: Identity name
                        user_id:
                          type: integer
                          example: 15478
                          description: Owner user ID
                        created_at:
                          type: string
                          example: '2026-04-10T11:11:20Z'
                          description: Creation timestamp
                        persistence_status:
                          type: string
                        is_default:
                          type: boolean
                        documents_count:
                          type: integer
                          example: 2
                          description: Number of documents in this identity
                      required:
                      - id
                      - name
                      - user_id
                      - created_at
                      - persistence_status
                      - is_default
                      - documents_count
                    description: List of identities
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 2
                        description: Total number of items
                      total_pages:
                        type: integer
                        example: 1
                        description: Total number of pages
                      current_page:
                        type: integer
                        example: 1
                        description: Current page number
                      per_page:
                        type: integer
                        example: 10
                        description: Items per page
                    required:
                    - total
                    - total_pages
                    - current_page
                    - per_page
                    description: Pagination metadata
                required:
                - identities
                - pagination
              example:
                identities:
                - id: 1150
                  name: Box 1
                  user_id: 15478
                  created_at: '2026-04-10T11:11:20Z'
                  persistence_status: active
                  is_default: false
                  documents_count: 2
                - id: 1151
                  name: Box 2
                  user_id: 15478
                  created_at: '2026-04-10T11:11:20Z'
                  persistence_status: active
                  is_default: false
                  documents_count: 1
                pagination:
                  total: 2
                  total_pages: 1
                  current_page: 1
                  per_page: 10
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
    post:
      summary: Create identity
      description: |
        Create a new identity for document organization.

        **Required Fields:**
        - name - Identity name

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Identities
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                identity[name]:
                  type: string
                  description: Identity name
                  example: ''
      responses:
        '200':
          description: creates a new identity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Identity created
                    description: Success message
                  identity_id:
                    type: integer
                    example: 1099
                    description: Created identity ID
                  identity:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1099
                        description: Identity identifier
                      name:
                        type: string
                        example: New Box
                        description: Identity name
                      user_id:
                        type: integer
                        example: 15165
                        description: Owner user ID
                      created_at:
                        type: string
                      persistence_status:
                        type: string
                      is_default:
                        type: boolean
                      documents_count:
                        type: integer
                    required:
                    - id
                    - name
                    - user_id
                    - created_at
                    - persistence_status
                    - is_default
                    - documents_count
                    description: Created identity details
                required:
                - message
                - identity_id
                - identity
              example:
                message: Identity created
                identity_id: 1099
                identity:
                  id: 1099
                  name: New Box
                  user_id: 15165
                  created_at: '2026-04-10T11:10:55Z'
                  persistence_status: active
                  is_default: false
                  documents_count: 0
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '422':
          description: returns unprocessable entity
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                errors:
                  name:
                  - Required
  "/api/v2/identities/{id}":
    delete:
      summary: Archive identity
      description: |
        Archive an identity.

        **Important notes:**
        - Identity is archived and becomes inactive
        - Cannot delete primary/default identity
        - Associated documents are preserved

        **Authentication:**
        - Requires Bearer token in Authorization header: `Authorization: Bearer <token>`
      tags:
      - Identities
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 1169
        description: Identity ID
      responses:
        '200':
          description: archives the identity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Identity deleted
                    description: Success message
                  identity_id:
                    type: integer
                    example: 1163
                    description: Archived identity ID
                required:
                - message
                - identity_id
              example:
                message: Identity deleted
                identity_id: 1163
        '401':
          description: returns unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: Unauthorized
        '404':
          description: returns not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
              example:
                error: data not found
        '422':
          description: returns forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
                required:
                - errors
              example:
                errors:
                - Primary identity cannot be archived
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authenticate API requests via API key like "Bearer YOUR_TOKEN"
  schemas:
    Error:
      type: object
      description: Standard error response. `errors` maps a field name (or `base`
        for errors not tied to a specific field) to an array of human-readable messages.
      required:
      - errors
      properties:
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            base:
            - data not found
    Warning:
      type: object
      description: A non-fatal notice that part of the request was accepted but a
        specific item was silently skipped. Additive and non-breaking; clients may
        branch on `code`.
      properties:
        resource:
          type: string
          description: Entity kind the warning is about (e.g. "caller_id", "did").
          example: caller_id
        identifier:
          type: string
          description: The value the client sent that was skipped.
          example: '19999999999'
        code:
          type: string
          description: Stable machine-readable token for the reason.
          example: not_an_owned_or_verified_caller_id
        message:
          type: string
          description: Human-readable explanation.
          example: is not an owned or verified caller ID and was ignored
      required:
      - resource
      - identifier
      - code
      - message
    BaseCdr:
      type: object
      description: Base call detail record with common fields
      required:
      - timestamp
      - type
      - amount
      - duration
      - from
      - to
      properties:
        timestamp:
          type: string
          format: date-time
          description: Call start time in ISO 8601 format (UTC)
          example: '2024-01-15T10:30:00Z'
        type:
          type: string
          description: Call type
          enum:
          - sip
          - incoming
          - web
          - api
          example: sip
        amount:
          type: number
          format: float
          description: Call cost (charged/credited amount)
          example: 0.05
        duration:
          type: integer
          description: Call duration in seconds. 0 = missed call
          minimum: 0
          example: 120
        from:
          type: string
          description: Caller number/identifier
          example: '100'
        to:
          type: string
          description: Destination number/identifier
          example: "+14155551234"
    SipCdr:
      allOf:
      - "$ref": "#/components/schemas/BaseCdr"
      - type: object
        description: Outbound SIP call detail record
        properties:
          destination_name:
            type: string
            description: Destination country/region name
            example: United States
          sip_account:
            type: string
            nullable: true
            description: SIP account used for the call
            example: john@sip.provider.com
          per_minute:
            type: number
            format: float
            nullable: true
            description: Per-minute rate. null = unknown, 0 = free
            example: 0.025
    IncomingCdr:
      allOf:
      - "$ref": "#/components/schemas/BaseCdr"
      - type: object
        description: Incoming call detail record
        properties:
          did_number:
            type: string
            nullable: true
            description: DID number that received the call (purchased virtual number)
            example: "+18005551234"
    WebCdr:
      allOf:
      - "$ref": "#/components/schemas/BaseCdr"
      - type: object
        description: Web call detail record (no additional fields)
    CdrListResponse:
      type: object
      description: Paginated list of CDR records
      required:
      - calls
      - pagination
      properties:
        calls:
          type: array
          description: Array of call detail records
          items:
            oneOf:
            - "$ref": "#/components/schemas/SipCdr"
            - "$ref": "#/components/schemas/IncomingCdr"
            - "$ref": "#/components/schemas/WebCdr"
        pagination:
          "$ref": "#/components/schemas/Pagination"
    Pagination:
      type: object
      description: Pagination metadata for list responses
      required:
      - page
      - per_page
      - total_pages
      - total_records
      properties:
        page:
          type: integer
          description: Current page number (1-based)
          minimum: 1
          example: 1
        per_page:
          type: integer
          description: Number of records per page
          minimum: 1
          example: 10
        total_pages:
          type: integer
          description: Total number of pages available
          minimum: 0
          example: 325
        total_records:
          type: integer
          description: Total number of records
          minimum: 0
          example: 3248
tags:
- name: Account Balance
  x-version: v1
- name: Calls
  x-version: v1
- name: Reports
  x-version: v1
- name: Purchases
  x-version: v1
- name: Inbound Destinations
  x-version: v1
- name: SIP Accounts
  x-version: v1
- name: SMS
  x-version: v1
- name: Numbers & Inventory
  x-version: v2
- name: Risk Checks
  x-version: v2
- name: HLR Lookups
  x-version: v2
- name: KYC Documents
  x-version: v2
- name: Identities
  x-version: v2
