{
  "openapi": "3.1.0",
  "info": {
    "title": "Telkit Phone API",
    "version": "1.0.0",
    "description": "Phone API reference. First-connect bootstrap creates the workspace credential used as Bearer for account operations."
  },
  "servers": [
    {
      "description": "Production",
      "url": "https://api.telkit.io"
    }
  ],
  "paths": {
    "/v1/account/link": {
      "post": {
        "description": "A workspace key can only ask for the link: connections are cut and the account is closed on the signed page,\nafter sign-in and an MFA check. The response is a pending `account` task. When the person withdraws, the task\ncompletes with the withdrawal result (owner handoff, scheduled items, balance, released numbers). Read it with\n`GET /v1/human-tasks/{id}`; the key stops working at withdrawal, so call that route without the key from then on.\nThe result stays readable for at least 10 minutes after the task completed; the account is not removed before that.\nAfter that the task disappears with the account when the deletion is finalized (a job that runs every 5 minutes, and\nonly once no number is left to reclaim), and the route answers 404. Read it as soon as the task shows `completed`.\nOnly an owner key can ask for this link, and the `X-Telkit-Workspace` header is not accepted.",
        "operationId": "create_account_link",
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectLink"
                }
              }
            },
            "description": "Pending account task and human URL. Nothing has changed yet."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Create a one-hour link to the account page, where the person lists and cuts agent connections or withdraws.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/api-keys": {
      "post": {
        "description": "Only the secret hash is retained; the API key cannot be retrieved later.",
        "operationId": "exchange_connect_token",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewApiKey"
                }
              }
            },
            "description": "New API key. Store the secret securely; it is shown once."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Exchange a connect token once.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/api-keys/{id}": {
      "delete": {
        "description": "Any API key of the same workspace may call this, including the key being revoked.\nNo operation lists keys: the id is the `id` returned when the key was created.",
        "operationId": "revoke_api_key",
        "parameters": [
          {
            "description": "API key id: the `id` in the 201 response of POST /v1/api-keys.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Key revoked. A key that is already revoked also returns 204."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`api_key_not_found`: no key with this id belongs to the caller's workspace."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Revoke an owned API key. Future requests using the key fail authentication.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/balance/top-ups": {
      "post": {
        "description": "The person chooses the amount and approves payment on the human link page. return_url is\ncurrently ignored. The request takes no amount: the body accepts only an optional return_url,\nand any other field, including an amount, is rejected.",
        "operationId": "create_topup_link",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopupLinkRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectLink"
                }
              }
            },
            "description": "Pending top_up task and human link. No charge has been queued."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Create a one-hour human link for manual top-up approval without charging a card.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/billing/auto-topup": {
      "get": {
        "description": "Changes require a human link, not an agent API write.\nThe threshold is strict below. Cap windows are 30 days from the first card registration.",
        "operationId": "get_auto_topup_settings",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "null"
                    },
                    {
                      "$ref": "#/components/schemas/AutoTopupSettings"
                    }
                  ]
                }
              }
            },
            "description": "Configured settings or null when the person has not configured them."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Read auto top-up settings.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/billing/auto-topup/defaults": {
      "get": {
        "operationId": "get_auto_topup_defaults",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopupPrefill"
                }
              }
            },
            "description": "Provisional human-form prefill from live settings or server environment."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Read editable server defaults for the human link form; these never enable auto top-up.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/billing/balance": {
      "get": {
        "operationId": "get_billing_balance",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balance"
                }
              }
            },
            "description": "Current credit, charged balance, and card registration guidance."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Return credit and charged balance excluding VAT; credit is spent first.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/billing/summary": {
      "get": {
        "operationId": "get_billing_summary",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSummary"
                }
              }
            },
            "description": "The billing state; a monthly estimate will be added after monthly number fees are available through the database function."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Read the billing summary.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/billing/topups": {
      "post": {
        "description": "Direct agent card charging is disabled. Create a top_up human task and ask the person to approve\nit through the human link.",
        "operationId": "request_balance_topup",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopupRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "human_required: use a top_up human link; this endpoint never charges a card."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Reject direct agent card charging.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/billing/topups/{id}": {
      "get": {
        "operationId": "get_balance_topup",
        "parameters": [
          {
            "description": "Top-up request UUID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Topup"
                }
              }
            },
            "description": "Payment state; succeeded means balance has been credited once."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Read the definitive or pending result of your top-up request.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/caller-ids": {
      "get": {
        "description": "Returns purchased numbers and external registrations, oldest first, with status and next action.\nA caller ID must have outbound SIP trunk calling enabled to be selected for another number.\nUse `next_cursor` to read the next page.",
        "operationId": "list_caller_ids",
        "parameters": [
          {
            "description": "The previous page's `next_cursor`; omit for the first page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Page size, from 1 to 100; defaults to 20.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "format": "int32",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallerIdList"
                }
              }
            },
            "description": "One page of caller IDs."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid `cursor` (`invalid_cursor`) or `limit` (`invalid_request`, 1-100)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token (`missing_token`, `invalid_token`, `token_expired`)."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Too many requests (`rate_limited`); wait for the `Retry-After` duration in seconds."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected server error (`internal_error`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`not_available`: SIP trunk calling is disabled. `temporarily_unavailable`: retry later. `api_unavailable`: API database is unavailable."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "List caller IDs.",
        "tags": [
          "caller-ids"
        ]
      },
      "post": {
        "description": "Purchased Telkit numbers are already caller IDs (`409 caller_id_exists`). Mobile numbers are refused\nwith `422 mobile_not_allowed`. External non-mobile numbers (including 031, 050x, 02, 1588 and other carriers' 070) require ownership\nverification: returns `201` with `status: pending` and an upload-documents next action.",
        "operationId": "register_caller_id",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterCallerIdRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallerId"
                }
              }
            },
            "description": "Registration created; upload proof of ownership for operator review."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_number` (unsupported domestic number) or `invalid_request`."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token (`missing_token`, `invalid_token`, `token_expired`)."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`caller_id_exists`: the purchased Telkit number is already a caller ID."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`mobile_not_allowed`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Too many requests (`rate_limited`); wait for the `Retry-After` duration in seconds."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected server error (`internal_error`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`api_unavailable`: API database is unavailable. `not_available`: SIP trunk calling is disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Register a caller ID.",
        "tags": [
          "caller-ids"
        ]
      }
    },
    "/v1/caller-ids/{id}": {
      "get": {
        "description": "IDs belonging to another account also return `404`.",
        "operationId": "get_caller_id",
        "parameters": [
          {
            "description": "Caller ID identifier.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallerId"
                }
              }
            },
            "description": "A caller ID."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token (`missing_token`, `invalid_token`, `token_expired`)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`caller_id_not_found`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Too many requests (`rate_limited`); wait for the `Retry-After` duration in seconds."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected server error (`internal_error`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`not_available`: SIP trunk calling is disabled. `temporarily_unavailable`: retry later. `api_unavailable`: API database is unavailable."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Get a caller ID.",
        "tags": [
          "caller-ids"
        ]
      }
    },
    "/v1/caller-ids/{id}/documents": {
      "post": {
        "description": "Maximum 10 MiB; JPEG, PNG, WebP or PDF. The private document is retained for operator review.\nPending, rejected and expired registrations accept documents; approved and revoked ones do not.\nStatus stays pending until an operator approves it. Storage paths and credentials are never returned.",
        "operationId": "upload_caller_id_document",
        "parameters": [
          {
            "description": "External caller ID registration identifier.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/pdf": {
              "schema": {
                "type": "string"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string"
              }
            },
            "image/png": {
              "schema": {
                "type": "string"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallerId"
                }
              }
            },
            "description": "Document stored; awaiting operator review."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Authentication required."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`caller_id_not_found`."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`caller_id_not_resubmittable`."
          },
          "413": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`document_too_large`: maximum 10 MiB."
          },
          "415": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_document_type`: unsupported or mismatched bytes."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`not_available` or `document_storage_unavailable`; retry later."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Upload proof of ownership as a raw binary body, not multipart.",
        "tags": [
          "caller-ids"
        ]
      }
    },
    "/v1/calls/{telkit_call_id}": {
      "get": {
        "description": "Pass the `X-Telkit-Call-ID` value from `data.sip_headers` of the OpenAI webhook\n(`live.transport.incoming`) as the path parameter to read that call's record. Use it to join a\nwebhook session to its call record (duration and charge). URL-encode special characters such as\n`@`.\n\nA call record appears only after the call ends, about 30 seconds later; before that the response\nis `404`. An unknown ID and another account's call also return `404`.",
        "operationId": "get_call",
        "parameters": [
          {
            "description": "The `X-Telkit-Call-ID` header value received in the webhook.",
            "example": "9bbb56e8486f0cb13c46b9c64a45ae6d2e87a172c6fd7d670-0007-6998",
            "in": "path",
            "name": "telkit_call_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Call"
                }
              }
            },
            "description": "One call record."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`call_not_found`; the record appears about 30 seconds after the call ends."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Get one call by its Telkit call ID.",
        "tags": [
          "calls"
        ]
      }
    },
    "/v1/connect-links": {
      "post": {
        "description": "No bearer is required. Each request creates a new task; Idempotency-Key is not supported.",
        "operationId": "create_connect_link",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConnectRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectLink"
                }
              }
            },
            "description": "New pending first-connect task and one-time human link."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "summary": "Create a one-hour human link; the first-connect task expires after seven days.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/consents": {
      "post": {
        "description": "콘솔의 동의 단계와 같아요. 문서마다 지금 판에만 동의할 수 있고, 이미 동의한 판을 다시 보내도 괜찮아요.\n한 건이라도 지금 판이 아니면 아무것도 기록하지 않아요.",
        "operationId": "record_consents",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecordConsentsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordConsentsResponse"
                }
              }
            },
            "description": "Consent recorded; either all entries are recorded or none are."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body (`invalid_request`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The document does not exist or the version is not current (`consent_not_current`)."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Record consent to the current terms.",
        "tags": [
          "account"
        ]
      }
    },
    "/v1/human-tasks/{id}": {
      "get": {
        "description": "The first completed response contains the connect token once; save it immediately.\nFirst-connect and account task ids are bearer capabilities. Other kinds require the person's bearer.",
        "operationId": "get_human_task",
        "parameters": [
          {
            "description": "Secret task capability UUID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanTaskStatus"
                }
              }
            },
            "description": "Task status and completed result. Connect token is returned only once."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "summary": "Poll a task.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/human-tasks/{id}/cancel": {
      "post": {
        "operationId": "cancel_human_task",
        "parameters": [
          {
            "description": "Secret task capability UUID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanTaskStatus"
                }
              }
            },
            "description": "The task, now `canceled`."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`human_task_not_found`."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`human_task_closed`: the task is no longer pending."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "summary": "Cancel a pending human task. Its link stops working.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/human-tasks/{id}/link": {
      "post": {
        "operationId": "reissue_human_link",
        "parameters": [
          {
            "description": "Secret task capability UUID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanLink"
                }
              }
            },
            "description": "Replacement human link; the task deadline is unchanged."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "summary": "Issue a fresh one-hour human link, immediately invalidating the previous human link without extending the task.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/identity/verify": {
      "post": {
        "description": "After the person finishes PortOne identity verification in the browser, send the verification\nID. The server re-reads the result from PortOne, confirms it and stores it. A made-up ID, a\nverification started by another account and a verification older than 30 minutes are rejected.\nOne person can verify only one account, so a person already verified on another account gets\n`ci_conflict`. If the server has not enabled this feature, it answers `feature_disabled`.",
        "operationId": "verify_identity",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyIdentityRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyIdentityResponse"
                }
              }
            },
            "description": "Identity verification saved; verifying the same person again on the same account also succeeds."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or verification ID (`invalid_request`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Verification cannot be used: `not_verified` means verification was not completed, `stale` means 30 minutes have passed, `not_owner` means another account started it, `ci_conflict` means the person is already verified on another account, and `already_used` means this verification has already been used."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`feature_disabled`: identity verification is disabled on this server."
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Could not connect to PortOne or read its response (`portone_failed`, `invalid_response`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Verify the result of a PortOne identity verification.",
        "tags": [
          "account"
        ]
      }
    },
    "/v1/legal-documents": {
      "get": {
        "description": "These are the versions that `POST /v1/consents` accepts.",
        "operationId": "list_legal_documents",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegalDocumentList"
                }
              }
            },
            "description": "The current version of each document."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "List the terms versions currently in force.",
        "tags": [
          "account"
        ]
      }
    },
    "/v1/me": {
      "get": {
        "description": "Read the identity verification, consent and card-registration state before buying a number to\nsee which steps remain.",
        "operationId": "get_me",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            },
            "description": "The account's current status."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Read the account's current status.",
        "tags": [
          "account"
        ]
      }
    },
    "/v1/numbers": {
      "get": {
        "description": "The most recently bought number comes first.",
        "operationId": "list_numbers",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NumberList"
                }
              }
            },
            "description": "The account's numbers."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "List the caller's numbers.",
        "tags": [
          "numbers"
        ]
      },
      "post": {
        "operationId": "issue_number",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IssueNumberRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Number"
                }
              }
            },
            "description": "The number is already owned by this account and is returned unchanged."
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Number"
                }
              }
            },
            "description": "Number purchased.",
            "headers": {
              "Location": {
                "description": "The URL of the new number.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body (`invalid_request`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`card_required`: no registered card (the response carries a card-registration `next_action`). `payment_failed`: the card payment for the shortfall failed; nothing was bought or charged and the response carries a `next_action` link where the person changes the card."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`identity_required`, `consent_required`, `mfa_required` or `account_deleting` while account deletion is in progress. `mfa_required`: the account has a card but no accepted second factor yet; the response carries a human-link `next_action` (a top-up link whose page first asks for identity re-verification or an SMS code). Retry the purchase after the person finishes."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_unavailable`: the number is owned by another account, in its quarantine period or does not exist."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`payment_pending`: the card payment was not settled while the request waited; read the number before retrying."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Buy a number using granted credit first, then charged balance, then a registered card.\nA registered card is required to buy a number, even when the balance covers the fee; without\none the request fails with `card_required` and `next_action` carries a card-registration link.\nRenewals are due every 30 days.\nIdentity verification and current consents are required, and so is a second factor (`mfa_required` with a human-link\n`next_action`, checked after the card). Repeating an owned number is idempotent.",
        "tags": [
          "numbers"
        ]
      }
    },
    "/v1/numbers/available": {
      "get": {
        "description": "Results are sorted by number. Numbers held by another account or resting after reclaim are not\nlisted.",
        "operationId": "list_available_numbers",
        "parameters": [
          {
            "description": "Part of the number to search for, using digits alone or a format such as `070-1234`; omit it\nto list all numbers.",
            "in": "query",
            "name": "search",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The number of results to return, from 1 to 100, with a default of 30.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 30,
              "format": "int32",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvailableNumberList"
                }
              }
            },
            "description": "Numbers available to buy."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid `search` or `limit` (`invalid_request`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Search the numbers available to buy now.",
        "tags": [
          "numbers"
        ]
      }
    },
    "/v1/numbers/{id}": {
      "delete": {
        "description": "A paid number remains available until the end of its paid period (`cancel_at`).\nThe number fee is not refunded. Canceling twice returns the same schedule.",
        "operationId": "release_number",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Number"
                }
              }
            },
            "description": "Cancellation scheduled; see `cancel_requested_at` and `cancel_at`."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Cancel a number.",
        "tags": [
          "numbers"
        ]
      },
      "get": {
        "description": "Returns connection, outbound readiness, renewal and cancellation dates.",
        "operationId": "get_number",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Number"
                }
              }
            },
            "description": "The requested number."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`: the number does not exist or belongs to another account."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Get one number in detail.",
        "tags": [
          "numbers"
        ]
      }
    },
    "/v1/numbers/{id}/billing/retry": {
      "post": {
        "description": "A balance-funded retry works without card payments; a card shortfall requires payments enabled\nand observe mode off.\nPerson-only: an API key gets 403 human_required, because the retry can charge the card.",
        "operationId": "retry_number_payment",
        "parameters": [
          {
            "description": "Owned number UUID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRetry"
                }
              }
            },
            "description": "A fresh payment attempt was queued; ambiguous attempts are never replayed."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "human_required: an API key cannot retry a number payment. mfa_required: a retry needs a verified second factor and an aal2 session. Nothing was queued or charged."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Retry a definitively failed number renewal within its seven-day retention window.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/numbers/{id}/caller-id": {
      "delete": {
        "description": "New calls present this number again in about one minute. Resetting an unset default is idempotent.",
        "operationId": "reset_number_caller_id",
        "parameters": [
          {
            "description": "Number identifier.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NumberCallerId"
                }
              }
            },
            "description": "Cleared; applies to new calls in about one minute."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token (`missing_token`, `invalid_token`, `token_expired`)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Too many requests (`rate_limited`); wait for the `Retry-After` duration in seconds."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected server error (`internal_error`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`not_available`: SIP trunk calling is disabled. `temporarily_unavailable`: retry later. `api_unavailable`: API database is unavailable."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Reset a number's default caller ID.",
        "tags": [
          "caller-ids"
        ]
      },
      "put": {
        "description": "The callee sees the selected caller ID. With digest authentication, `From` may contain the\ncredential number or its default caller ID. With IP-only authentication, `From` MUST contain\nthe credential number: it identifies the number being used, not a presentation alias. Sending\nanother number in `From` requests that other number under its own authentication and limits.\n`P-Asserted-Identity` may contain the identified credential number or its default; other values\nare rejected with `403 caller_id_not_allowed`. Limits, call records and charges stay with the\nidentified credential number.\n\nSelect another owned number with outbound enabled or an approved, unexpired external registration. Selecting this number itself resets the\ndefault, like `DELETE`. Applies to new calls in about one minute (`policy_sync_status: pending`),\nwithout changing existing calls. Repeating the request is idempotent.",
        "operationId": "put_number_caller_id",
        "parameters": [
          {
            "description": "Number identifier.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PutNumberCallerIdRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NumberCallerId"
                }
              }
            },
            "description": "Saved; applies to new calls in about one minute."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_request`: check `caller_id_id`."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token (`missing_token`, `invalid_token`, `token_expired`)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_suspended`, `sip_trunk_not_enabled` (source outbound disabled), or `caller_id_not_approved` (selected caller ID outbound disabled)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found` or `caller_id_not_found`."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_ready`: the number is not usable."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Too many requests (`rate_limited`); wait for the `Retry-After` duration in seconds."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected server error (`internal_error`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`not_available`: SIP trunk calling is disabled. `temporarily_unavailable`: retry later. `api_unavailable`: API database is unavailable."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Set a number's default caller ID.",
        "tags": [
          "caller-ids"
        ]
      }
    },
    "/v1/numbers/{id}/calls": {
      "get": {
        "description": "Newest first; read the next page with `next_cursor`. A call is recorded after it ends and\nappears about 30 seconds later, so a call in progress is not listed yet. Each call's\n`telkit_call_id` is the `X-Telkit-Call-ID` value received in the webhook when the call came in.\nAnother account's number returns `404`, like a number that does not exist.",
        "operationId": "list_number_calls",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "description": "The previous page's `next_cursor`; omit it for the first page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The page size, from 1 to 100, with a default of 20.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "format": "int32",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallPage"
                }
              }
            },
            "description": "One page of calls, newest first."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid `limit` (`invalid_request`) or `cursor` (`invalid_cursor`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "List the call records of a number.",
        "tags": [
          "calls"
        ]
      }
    },
    "/v1/numbers/{id}/connection": {
      "put": {
        "description": "Forward calls that arrive on this number to your SIP address. A number has one SIP address, and\nsaving again replaces it.\n\nA SIP address is `sip:[user@]host[:port]` (`sips:` is stored as TLS). You can choose the\ntransport (`transport`: `tls`, `tcp`, `udp`), voice encryption (`srtp`: `sdes`, `none`) and the\nnumber format the destination sees (`number_format`: `e164`, `domestic`). The allowed\ncombinations are `tls`+`sdes` (default), `tls`+`none`, `tcp`+`none` and `udp`+`none`. For\nexample, use `sip:proj_…@sip.api.openai.com` for an OpenAI project, the SIP trunk's SIP address\nfor LiveKit, and the PBX's own SIP address for a PBX. The host must be a domain name or a public\nIPv4 address.",
        "operationId": "put_number_connection",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PutConnectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Connection"
                }
              }
            },
            "description": "The saved connection."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body, including unrecognized fields (`invalid_request`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_suspended`: the number is suspended."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_sip_uri`, `invalid_sip_options` or `sip_host_not_allowed`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Save the inbound connection of a number.",
        "tags": [
          "numbers"
        ]
      }
    },
    "/v1/numbers/{id}/max-duration": {
      "put": {
        "description": "When a call reaches this duration (in seconds), the line disconnects both legs. It is a safety\nlimit against runaway billing. The value is an integer from 60 to 14400 (4 hours); the default\nis 3600. A new value applies to calls placed from about one minute later; calls in progress are\nunchanged. A call cut at the limit is recorded with `ended_by` `system` and `reason`\n`max_duration`. When the number is reclaimed after cancellation, the value returns to the\ndefault.",
        "operationId": "put_number_max_duration",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PutMaxDurationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Number"
                }
              }
            },
            "description": "The updated number; see `max_duration_sec`."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body, including a non-integer value (`invalid_request`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_suspended`: the number is suspended."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_max_duration`: the value must be from 60 to 14400."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Set the maximum call duration of a number.",
        "tags": [
          "numbers"
        ]
      }
    },
    "/v1/numbers/{id}/sip-credential": {
      "delete": {
        "description": "Only the password is deleted; the username stays. Once the change reaches the server (1 to 2\nminutes), the old password no longer works. If an allowed IP exists, calls from that address\ncontinue without a password; with no allowed IP either, the number's `state` becomes\n`auth_required`. Create a new password to call again. Deleting when no password exists succeeds\nwithout an error.",
        "operationId": "delete_sip_password",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SipCredential"
                }
              }
            },
            "description": "Deleted; returns the current state."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Delete the outbound password of a number.",
        "tags": [
          "sip-trunk"
        ]
      },
      "post": {
        "description": "Allowed only for numbers with outbound calling enabled (`state` of `GET /v1/sip-trunk` is\n`ready`, `auth_required` or `suspended`). The password is shown only once, in this response. The\nserver stores only a verification hash, not the password. If a password already exists the\nresponse is `password_exists` (409); if it was lost, create a new one with `rotate`. A change\nreaches the server in about one minute, at most two.",
        "operationId": "create_sip_password",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewSipCredential"
                }
              }
            },
            "description": "Created; the password is available only in this response."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`account_deleting`: account deletion is in progress."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`outbound_not_ready` means outbound calling is not enabled, `password_exists` means a password already exists, and `credential_changed` means the credential changed concurrently and the request should be retried."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Create the outbound password of a number.",
        "tags": [
          "sip-trunk"
        ]
      },
      "put": {
        "operationId": "set_sip_username",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetSipUsernameRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewSipCredential"
                }
              }
            },
            "description": "The username was set and a new password issued; the previous credentials stop working after synchronization."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "username_taken or credential_changed"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "invalid_username: the username format is invalid."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Set the SIP username and issue a new password.",
        "tags": [
          "sip-trunk"
        ]
      }
    },
    "/v1/numbers/{id}/sip-credential/rotate": {
      "post": {
        "description": "The old password stops working as soon as the change reaches the server (1 to 2 minutes). The\nnew password is shown only in this response. If no password exists yet the response is\n`no_password` (409); create one instead.",
        "operationId": "rotate_sip_password",
        "parameters": [
          {
            "description": "The number ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewSipCredential"
                }
              }
            },
            "description": "A new password was created; it is available only in this response."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`account_deleting`: account deletion is in progress."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`number_not_found`."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`outbound_not_ready`, `no_password` or `credential_changed`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Replace the outbound password of a number with a new one.",
        "tags": [
          "sip-trunk"
        ]
      }
    },
    "/v1/payment-methods/session": {
      "post": {
        "description": "Workspace keys receive a human link (201).\nBrowser session JWTs receive the existing one-time Payple window session (200).\nHuman links require FIRST_CONNECT; opening the Payple window also requires card configuration.",
        "operationId": "create_card_session",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardSession"
                }
              }
            },
            "description": "One-time Payple window session for the authenticated browser."
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectLink"
                }
              }
            },
            "description": "Pending card-registration task and one-hour human link for the agent."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`feature_disabled`: card registration is disabled on this server."
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Could not connect to the payment provider, or authentication was rejected (`payple_auth_failed`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Start optional card registration.",
        "tags": [
          "billing"
        ]
      }
    },
    "/v1/sip-credentials": {
      "get": {
        "description": "One entry per number that is allowed to call out. It only says whether a username and password\nexist; the password is never returned.",
        "operationId": "list_sip_credentials",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SipCredentialList"
                }
              }
            },
            "description": "The account's credentials."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "List the outbound credentials of the account.",
        "tags": [
          "sip-trunk"
        ]
      }
    },
    "/v1/sip-trunk": {
      "get": {
        "description": "Returns, in one response, the host and port to send to, whether each number may call out, its\nusername, the daily and per-second call limits, the allowed IP list and each number's\nauthentication (`auth`). A number can send calls only when it has an allowed IP or a username\nand password; with neither, its `state` is `auth_required`. The password is never returned.",
        "operationId": "get_sip_trunk",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SipTrunk"
                }
              }
            },
            "description": "Connection details."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Get the SIP trunk connection details and the outbound state of each number.",
        "tags": [
          "sip-trunk"
        ]
      }
    },
    "/v1/sip-trunk/ip-allowlist": {
      "get": {
        "operationId": "list_sip_ip_allowlist",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpAllowList"
                }
              }
            },
            "description": "The account's allowed IPs."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "List the allowed IPs.",
        "tags": [
          "sip-trunk"
        ]
      },
      "post": {
        "description": "An allowed IP applies to every number of the account. A number without a password accepts calls\nfrom this address as authenticated; a number with a password checks the username, the password\nand this address. Calls from a platform where many customers share one IP (clouds, PBXs, voice\nplatforms) cannot be tied to this account by the address alone; also set a username and password\nthere. Telkit does not judge or block shared addresses. IPv4 only, prefix length 24 to 32.\nPrivate, loopback, link-local, multicast and reserved ranges are not allowed. Up to 20 per\naccount. Adding the same range again returns it unchanged (`200`). A change reaches the server\nin about one minute, at most two.",
        "operationId": "add_sip_ip_allow",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddIpAllowRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpAllowEntry"
                }
              }
            },
            "description": "The range already exists and is returned unchanged."
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpAllowEntry"
                }
              }
            },
            "description": "Added."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body (`invalid_request`)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`account_deleting`: account deletion is in progress."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`allowlist_limit`: at most 20 entries are allowed."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_cidr` or `invalid_label`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Add an allowed IP.",
        "tags": [
          "sip-trunk"
        ]
      }
    },
    "/v1/sip-trunk/ip-allowlist/{id}": {
      "delete": {
        "description": "When the list becomes empty, a number with a password checks only its username and password, and\na number without a password becomes `auth_required`. A change reaches the server in about one\nminute, at most two.",
        "operationId": "remove_sip_ip_allow",
        "parameters": [
          {
            "description": "The allowed IP entry ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`allowlist_not_found`: the entry does not exist or belongs to another account."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Delete an allowed IP.",
        "tags": [
          "sip-trunk"
        ]
      }
    },
    "/v1/workspace": {
      "get": {
        "operationId": "get_workspace",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            },
            "description": "Personal workspace limits and identity status."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Return the caller's personal workspace and verified identity status.",
        "tags": [
          "connect"
        ]
      }
    },
    "/v1/workspace/business-verification": {
      "get": {
        "description": "Owner only. `404 business_verification_not_found` when none was ever started.",
        "operationId": "get_business_verification",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessVerification"
                }
              }
            },
            "description": "The latest verification."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`workspace_forbidden` or `person_connection_required`."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`business_verification_not_found`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Read the latest business verification of the workspace.",
        "tags": [
          "workspace"
        ]
      },
      "post": {
        "description": "Owner only. Returns `201` with a `processing` verification and `next_action: upload_document`, or `200` with the open\none when the same values were already submitted. While no document has been uploaded, different values replace\nthe open ones; once a document is waiting for a decision, different values are refused\n(`verification_in_progress`). A rejected or `needs_information` attempt is history: submit again for a new one.",
        "operationId": "start_business_verification",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessVerification"
                }
              }
            },
            "description": "The open verification with the same values."
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessVerification"
                }
              }
            },
            "description": "Verification created."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`workspace_forbidden` (not the owner), `identity_required`, `mfa_required` or `person_connection_required`."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`already_business` or `verification_in_progress`."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_business_registration_number`, `invalid_opened_on` or `invalid_business_values`."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Submit the four values of the business and start a verification.",
        "tags": [
          "workspace"
        ]
      }
    },
    "/v1/workspace/business-verification/document": {
      "post": {
        "description": "Owner only. Maximum 10 MiB; JPEG, PNG, WebP or PDF, with a `Content-Type` that matches the file's first\nbytes. The file is used only to read the four values and is deleted after the decision (a failed delete is\nretried until it succeeds); the size, type and hash of the deleted file stay in the record, and the text read from\nit is not stored, only the comparison result. After the upload, the worker first checks the business standing and,\nonly if the business is operating, sends the whole file to the document-reading provider; every retry sends it\nagain, and a business rejected by the standing check is never sent. Allowed once per verification, while it is\n`processing` and has no document.",
        "operationId": "upload_business_verification_document",
        "requestBody": {
          "content": {
            "application/pdf": {
              "schema": {
                "type": "string"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string"
              }
            },
            "image/png": {
              "schema": {
                "type": "string"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessVerification"
                }
              }
            },
            "description": "Document stored; the decision follows."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Missing, invalid or expired bearer token."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`workspace_forbidden` or `person_connection_required`."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`business_verification_not_found`."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`verification_not_open` or `document_already_uploaded`."
          },
          "413": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`document_too_large`: maximum 10 MiB."
          },
          "415": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "`invalid_document_type`: unsupported or mismatched bytes."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded. Retry after the number of seconds in Retry-After."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unexpected internal error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Service is temporarily unavailable or disabled."
          }
        },
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "summary": "Upload the business registration document as a raw binary body, not multipart.",
        "tags": [
          "workspace"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ConnectLink": {
        "allOf": [
          {
            "$ref": "#/components/schemas/HumanLink"
          },
          {
            "properties": {
              "kind": {
                "type": "string"
              },
              "status": {
                "type": "string"
              }
            },
            "required": [
              "kind",
              "status"
            ],
            "type": "object"
          }
        ]
      },
      "HumanLink": {
        "description": "Returned only when issuing a link. Deliberately has no Debug implementation.",
        "properties": {
          "task_expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "task_id": {
            "format": "uuid",
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "url_expires_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "task_id",
          "url",
          "url_expires_at",
          "task_expires_at"
        ],
        "type": "object"
      },
      "ErrorBody": {
        "properties": {
          "code": {
            "description": "A fixed English snake_case error code used for branching.",
            "example": "card_required",
            "type": "string"
          },
          "message": {
            "description": "An explanation whose wording can change. Branch on `code`, not on this text.",
            "example": "Register a card to pay the balance shortfall.",
            "type": "string"
          },
          "next_action": {}
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "KeyRequest": {
        "additionalProperties": false,
        "properties": {
          "name": {
            "description": "Human-readable API key name (1 to 64 ASCII characters).",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "NewApiKey": {
        "description": "A secret shown once. Never log this response.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Key id. Keep it with the secret: revoking the key needs it, and no operation lists keys.",
            "format": "uuid",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "secret": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "secret",
          "created_at"
        ],
        "type": "object"
      },
      "ErrorResponse": {
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorBody"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "TopupLinkRequest": {
        "additionalProperties": false,
        "properties": {
          "return_url": {
            "description": "Accepted for mock compatibility, but not stored or used for redirection in this release.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "AutoTopupSettings": {
        "description": "Auto top-up settings controlled by the person; absence means not configured, never defaults.",
        "properties": {
          "anchor_at": {
            "format": "date-time",
            "type": "string"
          },
          "consecutive_failures": {
            "format": "int32",
            "type": "integer"
          },
          "disabled_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "monthly_cap_krw": {
            "format": "int64",
            "type": "integer"
          },
          "retry_after": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "target_krw": {
            "format": "int64",
            "type": "integer"
          },
          "threshold_krw": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "enabled",
          "threshold_krw",
          "target_krw",
          "monthly_cap_krw",
          "anchor_at",
          "consecutive_failures"
        ],
        "type": "object"
      },
      "AutoTopupPrefill": {
        "description": "Server-side prefill only. Never enables or overwrites the person's stored policy.",
        "properties": {
          "monthly_cap_krw": {
            "format": "int64",
            "type": "integer"
          },
          "target_krw": {
            "format": "int64",
            "type": "integer"
          },
          "threshold_krw": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "threshold_krw",
          "target_krw",
          "monthly_cap_krw"
        ],
        "type": "object"
      },
      "Balance": {
        "properties": {
          "available_krw": {
            "format": "int64",
            "type": "integer"
          },
          "charged_krw": {
            "format": "int64",
            "type": "integer"
          },
          "credit_krw": {
            "format": "int64",
            "type": "integer"
          },
          "register_card_recommended": {
            "type": "boolean"
          }
        },
        "required": [
          "credit_krw",
          "charged_krw",
          "available_krw",
          "register_card_recommended"
        ],
        "type": "object"
      },
      "BillingSummary": {
        "description": "The billing data available from the database: the registered card, unbilled call charges, each\nnumber's billing dates and recent payments; the response does not include a monthly estimate.",
        "properties": {
          "card": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Card",
                "description": "The registered card, or null if none is registered."
              }
            ]
          },
          "numbers": {
            "description": "The billing dates for each number.",
            "items": {
              "$ref": "#/components/schemas/BillingNumber"
            },
            "type": "array"
          },
          "payments": {
            "description": "The 24 most recent payments, newest first.",
            "items": {
              "$ref": "#/components/schemas/Payment"
            },
            "type": "array"
          },
          "unbilled_usage_krw": {
            "description": "Unbilled call charges in KRW excluding VAT, charged with the next number fee.",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "unbilled_usage_krw",
          "numbers",
          "payments"
        ],
        "type": "object"
      },
      "Card": {
        "properties": {
          "brand": {
            "description": "The card issuer reported by the payment provider.",
            "type": [
              "string",
              "null"
            ]
          },
          "last4": {
            "description": "The last four digits of the card number.",
            "example": "1234",
            "type": [
              "string",
              "null"
            ]
          },
          "registered_at": {
            "description": "The time the card was registered.",
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "registered_at"
        ],
        "type": "object"
      },
      "BillingNumber": {
        "properties": {
          "cancel_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "cancel_requested_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "display": {
            "description": "The display format (`070-1234-5678`).",
            "type": "string"
          },
          "held_until": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "issued_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "next_billing_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/NumberStatus"
          }
        },
        "required": [
          "id",
          "display",
          "status"
        ],
        "type": "object"
      },
      "NumberStatus": {
        "description": "The status of an owned number; transition rules are in the contract document\n(`docs/contracts/web-backend.md` section 2).",
        "enum": [
          "legacy",
          "active",
          "outbound_suspended",
          "inbound_suspended",
          "held",
          "suspended"
        ],
        "type": "string"
      },
      "Payment": {
        "properties": {
          "amount_krw": {
            "description": "The amount actually charged, in KRW including VAT.",
            "format": "int32",
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "paid_at": {
            "description": "The time the payment succeeded.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "period_end": {
            "description": "The exclusive end of the billing period.",
            "format": "date",
            "type": "string"
          },
          "period_start": {
            "description": "The inclusive start of the billing period.",
            "format": "date",
            "type": "string"
          },
          "receipt_url": {
            "description": "The receipt URL.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          }
        },
        "required": [
          "id",
          "period_start",
          "period_end",
          "amount_krw",
          "status",
          "created_at"
        ],
        "type": "object"
      },
      "PaymentStatus": {
        "enum": [
          "pending",
          "succeeded",
          "failed"
        ],
        "type": "string"
      },
      "TopupRequest": {
        "additionalProperties": false,
        "properties": {
          "amount_krw": {
            "description": "Balance added excluding VAT: 5,000 to 500,000 KRW in increments of 100.",
            "format": "int64",
            "type": "integer"
          },
          "request_id": {
            "description": "Client-generated idempotency key; reuse this UUID for retries of the same payment.",
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "request_id",
          "amount_krw"
        ],
        "type": "object"
      },
      "Topup": {
        "properties": {
          "amount_krw": {
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "amount_krw",
          "status"
        ],
        "type": "object"
      },
      "CallerIdList": {
        "description": "One page of caller IDs, oldest first.",
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/CallerId"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass this unchanged as `cursor` for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "items"
        ],
        "type": "object"
      },
      "CallerId": {
        "description": "A number that may be presented to the callee.",
        "properties": {
          "created_at": {
            "description": "Registration time, or the issue time of a purchased number.",
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "description": "Approval expiration, or null for a purchased Telkit number.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "The caller ID identifier, which is the number resource ID for purchased numbers.",
            "format": "uuid",
            "type": "string"
          },
          "next_action": {
            "$ref": "#/components/schemas/CallerIdNextAction"
          },
          "number": {
            "description": "Domestic digits only.",
            "example": "07012345678",
            "pattern": "^(0[2-9][0-9]{7,10}|1[0-9]{7})$",
            "type": "string"
          },
          "reason": {
            "description": "Rejection or expiration reason, or null.",
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "$ref": "#/components/schemas/CallerIdSource"
          },
          "status": {
            "$ref": "#/components/schemas/CallerIdStatus"
          }
        },
        "required": [
          "id",
          "number",
          "source",
          "status",
          "next_action",
          "created_at"
        ],
        "type": "object"
      },
      "CallerIdNextAction": {
        "description": "Next action for this caller ID.",
        "properties": {
          "message": {
            "type": "string"
          },
          "type": {
            "$ref": "#/components/schemas/CallerIdNextActionType"
          }
        },
        "required": [
          "type",
          "message"
        ],
        "type": "object"
      },
      "CallerIdNextActionType": {
        "description": "Type of the next required action.",
        "enum": [
          "upload_documents",
          "wait_for_review",
          "resubmit_documents",
          "renew_verification",
          "none"
        ],
        "type": "string"
      },
      "CallerIdSource": {
        "description": "Origin of a caller ID.",
        "enum": [
          "purchased_070",
          "registered"
        ],
        "type": "string"
      },
      "CallerIdStatus": {
        "description": "The verification status, always `approved` for purchased Telkit numbers.",
        "enum": [
          "pending",
          "revoked",
          "approved",
          "rejected",
          "expired"
        ],
        "type": "string"
      },
      "RegisterCallerIdRequest": {
        "additionalProperties": false,
        "description": "Number to register as a caller ID.",
        "properties": {
          "number": {
            "description": "Domestic number such as `0212345678` or `15881234`; hyphens, spaces and `+82` are accepted.",
            "example": "0212345678",
            "type": "string"
          }
        },
        "required": [
          "number"
        ],
        "type": "object"
      },
      "Call": {
        "properties": {
          "answered_at": {
            "description": "Null for an unanswered call.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "billable": {
            "type": "boolean"
          },
          "billable_seconds": {
            "description": "Billing-unit rounding is already reflected in `charge_krw`.",
            "format": "int32",
            "type": "integer"
          },
          "billed": {
            "description": "Whether the call has already been billed in a payment.",
            "type": "boolean"
          },
          "charge_krw": {
            "description": "The charge in KRW excluding VAT, calculated by the database and zero for calls that are not\nbilled.",
            "format": "int32",
            "type": "integer"
          },
          "destination": {
            "description": "The destination of an inbound call, inferred from the connection when the record is created;\nnull if the call started within two minutes of saving the connection, if the connection\nchanged before recording and the destination cannot be determined, or if an announcement\nended the call without forwarding it; once recorded, the destination is retained after later\nconnection changes.",
            "example": "sip:proj_abc123def456@sip.api.openai.com;transport=tls",
            "type": [
              "string",
              "null"
            ]
          },
          "direction": {
            "$ref": "#/components/schemas/CallDirection"
          },
          "duration_sec": {
            "description": "The call duration in seconds from answer to end, including free calls and zero for\nunanswered calls.",
            "format": "int32",
            "type": "integer"
          },
          "ended_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "ended_by": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EndedBy",
                "description": "The party that ended the call: `caller` is the calling side, `callee` is the receiving side\n(the SIP destination for inbound calls), `system` means the line ended it for reasons such\nas the maximum duration or lost audio, and null means unknown."
              }
            ]
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "number_id": {
            "format": "uuid",
            "type": "string"
          },
          "peer_e164": {
            "description": "The other party's number in E.164 format, or `unknown` if the network did not provide it.",
            "example": "+821012345678",
            "type": "string"
          },
          "peer_type": {
            "$ref": "#/components/schemas/PeerType"
          },
          "reason": {
            "description": "The termination reason: `max_duration` only when the line ends a call at the number's\nmaximum duration with `ended_by` set to `system`, otherwise null; ignore unknown values\nbecause new values may be added.",
            "example": "max_duration",
            "type": [
              "string",
              "null"
            ]
          },
          "result_text": {
            "description": "A one-sentence Korean explanation of the call result, suitable for display. Wording can change;\nbranch on `sip_code` and `ended_by`. Null when there is nothing to report.",
            "type": [
              "string",
              "null"
            ]
          },
          "sip_code": {
            "description": "The destination's final SIP response code, from 100 to 699, or null if unknown.",
            "example": 486,
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "sip_reason": {
            "description": "The standard reason phrase for `sip_code`, such as `Busy Here`, derived from the code rather\nthan the text sent by the network.",
            "example": "Busy Here",
            "type": [
              "string",
              "null"
            ]
          },
          "started_at": {
            "description": "The time the call started.",
            "format": "date-time",
            "type": "string"
          },
          "telkit_call_id": {
            "description": "The Telkit call ID matching the `X-Telkit-Call-ID` header in `data.sip_headers` of the\nincoming OpenAI webhook (`live.transport.incoming`), used to join the webhook session to its\ncall record by exact string comparison without assuming a format, or null if absent.",
            "example": "9bbb56e8486f0cb13c46b9c64a45ae6d2e87a172c6fd7d670-0007-6998",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "number_id",
          "direction",
          "peer_e164",
          "peer_type",
          "started_at",
          "duration_sec",
          "billable",
          "charge_krw",
          "billed",
          "billable_seconds"
        ],
        "type": "object"
      },
      "CallDirection": {
        "enum": [
          "inbound",
          "outbound"
        ],
        "type": "string"
      },
      "EndedBy": {
        "description": "The party that ended the call; see `Call.ended_by`.",
        "enum": [
          "caller",
          "callee",
          "system"
        ],
        "type": "string"
      },
      "PeerType": {
        "enum": [
          "mobile",
          "landline",
          "other"
        ],
        "type": "string"
      },
      "ConnectRequest": {
        "additionalProperties": false,
        "properties": {
          "client": {
            "description": "Agent client name shown on the person's approval page (1 to 64 ASCII characters).",
            "type": "string"
          }
        },
        "required": [
          "client"
        ],
        "type": "object"
      },
      "RecordConsentsRequest": {
        "additionalProperties": false,
        "properties": {
          "consents": {
            "description": "The document versions to accept; only current versions are accepted, and already accepted\nversions are ignored.",
            "items": {
              "$ref": "#/components/schemas/ConsentInput"
            },
            "type": "array"
          }
        },
        "required": [
          "consents"
        ],
        "type": "object"
      },
      "ConsentInput": {
        "additionalProperties": false,
        "properties": {
          "doc": {
            "example": "terms",
            "type": "string"
          },
          "version": {
            "example": "2026-10-01",
            "type": "string"
          }
        },
        "required": [
          "doc",
          "version"
        ],
        "type": "object"
      },
      "RecordConsentsResponse": {
        "properties": {
          "consents_current": {
            "description": "Whether all required terms have been accepted.",
            "type": "boolean"
          }
        },
        "required": [
          "consents_current"
        ],
        "type": "object"
      },
      "HumanTaskStatus": {
        "description": "The polling resource with a kind-specific result; first_connect returns the workspace and\none-time token, and an account task returns the withdrawal result.",
        "properties": {
          "completed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "connect_token_issued_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "result": {
            "description": "First-connect result: workspace_id, identity_verified, auth_tier, connect_token (once, then null)."
          },
          "status": {
            "type": "string"
          },
          "task_expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "url_expires_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "kind",
          "status",
          "task_expires_at",
          "created_at"
        ],
        "type": "object"
      },
      "VerifyIdentityRequest": {
        "additionalProperties": false,
        "description": "The identity verification request.",
        "properties": {
          "identity_verification_id": {
            "description": "The verification ID used to start PortOne identity verification in the browser, in\n`identity-verification-<uuid>` format with 8 to 128 letters, digits, `_` or `-`; set\n`customData` to the calling account's user ID when starting verification.",
            "example": "identity-verification-0b0a5d5e-2a3c-4c55-9f5c-2f3e8f6f7a11",
            "type": "string"
          }
        },
        "required": [
          "identity_verification_id"
        ],
        "type": "object"
      },
      "VerifyIdentityResponse": {
        "description": "The identity verification result.",
        "properties": {
          "identity_verified": {
            "description": "Always `true` on success, including repeated verification by the same person on an already\nverified account.",
            "type": "boolean"
          }
        },
        "required": [
          "identity_verified"
        ],
        "type": "object"
      },
      "LegalDocumentList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/LegalDocument"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "LegalDocument": {
        "properties": {
          "doc": {
            "description": "`terms` or `privacy`.",
            "example": "terms",
            "type": "string"
          },
          "effective_on": {
            "description": "The date the document takes effect.",
            "format": "date",
            "type": "string"
          },
          "required": {
            "description": "Whether consent is required before buying a number.",
            "type": "boolean"
          },
          "title": {
            "description": "The document title.",
            "type": "string"
          },
          "version": {
            "description": "The version to send unchanged to `POST /v1/consents`.",
            "example": "2026-10-01",
            "type": "string"
          }
        },
        "required": [
          "doc",
          "version",
          "title",
          "effective_on",
          "required"
        ],
        "type": "object"
      },
      "MeResponse": {
        "properties": {
          "consents_current": {
            "description": "Whether all currently required terms versions have been accepted.",
            "type": "boolean"
          },
          "has_active_card": {
            "description": "Whether a registered card is available for top-ups or a number-fee balance shortfall.",
            "type": "boolean"
          },
          "identity_verified": {
            "description": "Whether phone identity verification is complete, as required before buying the first number.",
            "type": "boolean"
          },
          "user_id": {
            "description": "로그인한 사용자의 id예요(토큰의 `sub`).",
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "identity_verified",
          "consents_current",
          "has_active_card"
        ],
        "type": "object"
      },
      "NumberList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Number"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "Number": {
        "properties": {
          "cancel_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "cancel_requested_at": {
            "description": "The time cancellation was requested.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "connection": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Connection",
                "description": "The inbound connection, or null before it is saved."
              }
            ]
          },
          "daily_outbound_cap": {
            "description": "The daily outbound call limit, falling back to the default when absent.",
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "display": {
            "description": "The display format (`070-1234-5678`).",
            "example": "070-1234-5678",
            "type": "string"
          },
          "e164": {
            "description": "The E.164 format (`+8270XXXXXXXX`).",
            "example": "+827012345678",
            "type": "string"
          },
          "held_until": {
            "description": "The time a number in the `held` state will be reclaimed.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "issued_at": {
            "description": "The time the number was bought.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "max_duration_sec": {
            "description": "The maximum duration of one call in seconds, from 60 to 14400 with a default of 3600; at\nthis limit the line ends the call with `ended_by` set to `system` and `reason` to\n`max_duration`; update it through `PUT /v1/numbers/{id}/max-duration`.",
            "example": 3600,
            "format": "int32",
            "maximum": 14400,
            "minimum": 60,
            "type": "integer"
          },
          "next_billing_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "outbound": {
            "$ref": "#/components/schemas/Outbound"
          },
          "status": {
            "$ref": "#/components/schemas/NumberStatus"
          }
        },
        "required": [
          "id",
          "e164",
          "display",
          "status",
          "max_duration_sec",
          "outbound"
        ],
        "type": "object"
      },
      "Connection": {
        "properties": {
          "forward_to": {
            "description": "The address to which inbound calls are forwarded, formed from the saved SIP address with the\ntransport appended as `;transport=`.",
            "example": "sip:agent@pbx.example.com;transport=tls",
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/ConnectionKind",
            "description": "Always `sip_uri`."
          },
          "number_format": {
            "$ref": "#/components/schemas/SipNumberFormat",
            "description": "The number format seen by the destination."
          },
          "sip_uri": {
            "description": "The saved SIP address in normalized `sip:[user@]host[:port]` format.",
            "example": "sip:agent@pbx.example.com",
            "type": "string"
          },
          "srtp": {
            "$ref": "#/components/schemas/SipSrtp",
            "description": "The audio encryption method."
          },
          "transport": {
            "$ref": "#/components/schemas/SipTransport",
            "description": "The SIP transport."
          },
          "updated_at": {
            "description": "The time the connection was last saved.",
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "kind",
          "sip_uri",
          "transport",
          "srtp",
          "number_format",
          "forward_to",
          "updated_at"
        ],
        "type": "object"
      },
      "ConnectionKind": {
        "enum": [
          "sip_uri"
        ],
        "type": "string"
      },
      "SipNumberFormat": {
        "description": "The number format seen by the destination: `e164` uses `+827012345678`, and `domestic` uses\n`07012345678`.",
        "enum": [
          "e164",
          "domestic"
        ],
        "type": "string"
      },
      "SipSrtp": {
        "description": "The RTP audio encryption method; `sdes` (SRTP) is available only with `tls` transport.",
        "enum": [
          "sdes",
          "none"
        ],
        "type": "string"
      },
      "SipTransport": {
        "description": "The SIP transport used to forward calls.",
        "enum": [
          "tls",
          "tcp",
          "udp"
        ],
        "type": "string"
      },
      "Outbound": {
        "properties": {
          "enabled": {
            "description": "Whether outbound credentials have been created.",
            "type": "boolean"
          },
          "requested": {
            "description": "Whether this number requires outbound credentials, determined by the database from its\nstatus, cancellation time and card.",
            "type": "boolean"
          },
          "state": {
            "$ref": "#/components/schemas/OutboundState"
          },
          "username": {
            "description": "The outbound SIP username; the password is neither stored nor returned.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requested",
          "enabled",
          "state"
        ],
        "type": "object"
      },
      "OutboundState": {
        "description": "번호 하나의 발신이 어디까지 왔는지예요(콘솔이 보여 주는 세 상태와 같아요).",
        "enum": [
          "opening",
          "open"
        ],
        "type": "string"
      },
      "IssueNumberRequest": {
        "additionalProperties": false,
        "properties": {
          "number_id": {
            "description": "The `id` from `GET /v1/numbers/available`.",
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "number_id"
        ],
        "type": "object"
      },
      "AvailableNumberList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AvailableNumber"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "AvailableNumber": {
        "properties": {
          "display": {
            "description": "The display format (`070-1234-5678`).",
            "example": "070-1234-5678",
            "type": "string"
          },
          "e164": {
            "description": "The E.164 format (`+8270XXXXXXXX`).",
            "example": "+827012345678",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "id",
          "e164",
          "display"
        ],
        "type": "object"
      },
      "PaymentRetry": {
        "properties": {
          "payment_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "payment_id"
        ],
        "type": "object"
      },
      "NumberCallerId": {
        "description": "The default caller ID of a number.",
        "properties": {
          "caller_id_id": {
            "description": "Selected caller ID; null presents `credential_number`.",
            "format": "uuid",
            "type": [
              "string",
              "null"
            ]
          },
          "credential_number": {
            "description": "The credential number in domestic digits, to which CPS, daily usage, call records and\ncharges belong.",
            "example": "07012345678",
            "pattern": "^070[0-9]{8}$",
            "type": "string"
          },
          "effective_caller_id": {
            "description": "Number presented to the callee, in domestic digits.",
            "example": "07087654321",
            "type": "string"
          },
          "number_id": {
            "format": "uuid",
            "type": "string"
          },
          "policy_sync_status": {
            "$ref": "#/components/schemas/PolicySyncStatus"
          }
        },
        "required": [
          "number_id",
          "credential_number",
          "effective_caller_id",
          "policy_sync_status"
        ],
        "type": "object"
      },
      "PolicySyncStatus": {
        "description": "Whether the rail has applied the policy.",
        "enum": [
          "pending",
          "synced"
        ],
        "type": "string"
      },
      "PutNumberCallerIdRequest": {
        "additionalProperties": false,
        "description": "Default caller ID for calls from a number.",
        "properties": {
          "caller_id_id": {
            "description": "A caller ID owned by this account (`GET /v1/caller-ids`).",
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "caller_id_id"
        ],
        "type": "object"
      },
      "CallPage": {
        "properties": {
          "data": {
            "description": "Newest first.",
            "items": {
              "$ref": "#/components/schemas/Call"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass this value unchanged as `cursor` to read the next, older page; null means the last\npage.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "PutConnectionRequest": {
        "additionalProperties": false,
        "properties": {
          "kind": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ConnectionKind",
                "description": "Optional; if provided, it must be `sip_uri`."
              }
            ]
          },
          "number_format": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SipNumberFormat",
                "description": "The number format seen by the destination, defaulting to `domestic` when omitted."
              }
            ]
          },
          "sip_uri": {
            "description": "The SIP destination, starting with `sip:` or `sips:` followed by `[user@]host[:port]`, where\nthe host is a domain name or public IPv4 address; private, loopback or link-local IPs, IPv6\naddresses, `localhost`, Telkit's own domains, URI parameters other than `transport`, and\n`?headers` are rejected; `sips:` is stored as `tls`; use `sip:proj_…@sip.api.openai.com` for\nan OpenAI project.",
            "example": "sip:agent@pbx.example.com",
            "type": "string"
          },
          "srtp": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SipSrtp",
                "description": "The audio encryption method, defaulting to `sdes` for `tls` and `none` otherwise; allowed\ncombinations are `tls`+`sdes`, `tls`+`none`, `tcp`+`none` and `udp`+`none`."
              }
            ]
          },
          "transport": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SipTransport",
                "description": "The transport, defaulting to the address's `;transport=` value when present and `tls`\notherwise."
              }
            ]
          }
        },
        "required": [
          "sip_uri"
        ],
        "type": "object"
      },
      "PutMaxDurationRequest": {
        "additionalProperties": false,
        "properties": {
          "max_duration_sec": {
            "description": "The maximum duration of one call in seconds, an integer from 60 to 14400 (4 hours).",
            "example": 1800,
            "format": "int32",
            "maximum": 14400,
            "minimum": 60,
            "type": "integer"
          }
        },
        "required": [
          "max_duration_sec"
        ],
        "type": "object"
      },
      "SipCredential": {
        "description": "The number's outbound credentials; the password is shown only when created and cannot be\nretrieved later.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "has_password": {
            "description": "Whether a password has been created; false disables username-and-password authentication,\nbut calls from an allowed IP can still use IP authentication (`auth`).",
            "type": "boolean"
          },
          "number": {
            "description": "이 자격으로 걸 수 있는 발신 번호예요(E.164). 다른 번호로는 걸 수 없어요.",
            "example": "+827012345678",
            "type": "string"
          },
          "number_id": {
            "format": "uuid",
            "type": "string"
          },
          "password_set_at": {
            "description": "The time the current password was created or replaced.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "username": {
            "description": "The outbound SIP username, generated by default and null while being prepared; changing it\nwith PUT also issues a new password.",
            "example": "tkt7f3k9a2m5x8q",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "number_id",
          "number",
          "has_password"
        ],
        "type": "object"
      },
      "NewSipCredential": {
        "description": "The response containing a newly created password, visible **only in this response** and\nrequiring immediate storage in a secure location.",
        "properties": {
          "host": {
            "description": "The connection host.",
            "example": "sip.telkit.io",
            "type": "string"
          },
          "number_id": {
            "format": "uuid",
            "type": "string"
          },
          "password": {
            "description": "A 32-character alphanumeric password that cannot be retrieved again; use `rotate` to replace\na lost password.",
            "example": "u3kZ8f0QJp2vXw7LhN4cB9sTa1YeDm6R",
            "type": "string"
          },
          "password_set_at": {
            "format": "date-time",
            "type": "string"
          },
          "port": {
            "description": "The TLS port.",
            "example": 5061,
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "realm": {
            "description": "The digest realm, usually discovered automatically by equipment but provided here for manual\nconfiguration.",
            "example": "sip.telkit.io",
            "type": "string"
          },
          "transport": {
            "description": "Always `tls`.",
            "type": "string"
          },
          "username": {
            "example": "tkt7f3k9a2m5x8q",
            "type": "string"
          }
        },
        "required": [
          "number_id",
          "username",
          "password",
          "realm",
          "host",
          "port",
          "transport",
          "password_set_at"
        ],
        "type": "object"
      },
      "SetSipUsernameRequest": {
        "additionalProperties": false,
        "description": "The custom SIP username; setting it returns a new password once.",
        "properties": {
          "username": {
            "type": "string"
          }
        },
        "required": [
          "username"
        ],
        "type": "object"
      },
      "CardSession": {
        "description": "The values needed to open the card-registration window.",
        "properties": {
          "auth_key": {
            "description": "The one-time key passed to the provider's registration window (`PCD_AUTH_KEY`).",
            "type": "string"
          },
          "pay_url": {
            "description": "The request URL for the provider's registration window (`PCD_PAY_URL`).",
            "type": "string"
          },
          "script_url": {
            "description": "The URL of the provider's registration-window script to load in the browser.",
            "type": "string"
          }
        },
        "required": [
          "auth_key",
          "pay_url",
          "script_url"
        ],
        "type": "object"
      },
      "SipCredentialList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/SipCredential"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "SipTrunk": {
        "description": "The connection details required to place calls through the SIP trunk.",
        "properties": {
          "auth_methods": {
            "description": "The available authentication methods: each number requires `digest` (username and password),\n`ip_allowlist` (allowed IP) or both; when both exist, both are checked; see `numbers[].auth`\nfor each number's state.",
            "items": {
              "$ref": "#/components/schemas/SipTrunkAuthMethod"
            },
            "type": "array"
          },
          "host": {
            "description": "The connection host.",
            "example": "sip.telkit.io",
            "type": "string"
          },
          "ip_allowlist": {
            "description": "The account's allowed IPs, shared by all numbers; a number without a password authenticates\ncalls by source address, a number with a password checks both credentials and source\naddress, and an empty list leaves only credential checks for numbers with passwords.",
            "items": {
              "$ref": "#/components/schemas/IpAllowEntry"
            },
            "type": "array"
          },
          "limits": {
            "$ref": "#/components/schemas/SipTrunkLimits"
          },
          "numbers": {
            "items": {
              "$ref": "#/components/schemas/SipTrunkNumber"
            },
            "type": "array"
          },
          "port": {
            "example": 5061,
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "realm": {
            "example": "sip.telkit.io",
            "type": "string"
          },
          "transport": {
            "description": "Always `tls`.",
            "type": "string"
          }
        },
        "required": [
          "host",
          "port",
          "transport",
          "auth_methods",
          "realm",
          "limits",
          "numbers",
          "ip_allowlist"
        ],
        "type": "object"
      },
      "SipTrunkAuthMethod": {
        "description": "The authentication methods supported by the trunk.",
        "enum": [
          "digest",
          "ip_allowlist"
        ],
        "type": "string"
      },
      "IpAllowEntry": {
        "description": "One allowed IP entry.",
        "properties": {
          "cidr": {
            "description": "The range's starting address and prefix length, such as `203.0.113.0/24`.",
            "example": "203.0.113.0/24",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "cidr",
          "label",
          "created_at"
        ],
        "type": "object"
      },
      "SipTrunkLimits": {
        "description": "The connection limits.",
        "properties": {
          "concurrent": {
            "description": "The maximum concurrent calls, or null for no limit.",
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "cps": {
            "description": "The number of new calls per second.",
            "example": 1,
            "format": "int32",
            "type": "integer"
          }
        },
        "required": [
          "cps"
        ],
        "type": "object"
      },
      "SipTrunkNumber": {
        "description": "The outbound state and credentials of each number.",
        "properties": {
          "auth": {
            "$ref": "#/components/schemas/SipTrunkAuth",
            "description": "The number's authentication state; when `mode` is `none`, a number with outbound calling\nenabled has `state` `auth_required`."
          },
          "credential": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SipCredential",
                "description": "The credential when a username has been assigned, or null while being prepared."
              }
            ]
          },
          "daily_outbound_cap": {
            "description": "The number of calls allowed per day in Korean time, assigned when outbound calling is\nenabled.",
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "number": {
            "example": "+827012345678",
            "type": "string"
          },
          "number_id": {
            "format": "uuid",
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/SipTrunkNumberState"
          },
          "status": {
            "$ref": "#/components/schemas/NumberStatus"
          }
        },
        "required": [
          "number_id",
          "number",
          "status",
          "state",
          "auth"
        ],
        "type": "object"
      },
      "SipTrunkAuth": {
        "description": "The number's authentication state, requiring an allowed IP, username and password, or both; when\nboth methods exist, both are checked.",
        "properties": {
          "credentials": {
            "description": "Whether the number has a password.",
            "type": "boolean"
          },
          "ip_allowlist": {
            "description": "Whether the account has at least one allowed IP; numbers without a password accept calls\nfrom these addresses, while numbers with a password require both the password and an allowed\nsource address.",
            "type": "boolean"
          },
          "mode": {
            "$ref": "#/components/schemas/SipTrunkAuthMode",
            "description": "The number's current authentication mode."
          }
        },
        "required": [
          "mode",
          "credentials",
          "ip_allowlist"
        ],
        "type": "object"
      },
      "SipTrunkAuthMode": {
        "description": "The authentication method used by the number.",
        "enum": [
          "none",
          "ip_allowlist",
          "digest",
          "both"
        ],
        "type": "string"
      },
      "SipTrunkNumberState": {
        "description": "The number's outbound SIP trunk state.",
        "enum": [
          "card_required",
          "preparing",
          "ready",
          "auth_required",
          "suspended",
          "closed"
        ],
        "type": "string"
      },
      "IpAllowList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/IpAllowEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "AddIpAllowRequest": {
        "additionalProperties": false,
        "description": "The request to add an allowed IP.",
        "properties": {
          "cidr": {
            "description": "One IPv4 address (`203.0.113.7`) or range (`203.0.113.0/24`) with a prefix length from 24 to\n32; private, loopback and reserved ranges are not allowed.",
            "example": "203.0.113.0/24",
            "type": "string"
          },
          "label": {
            "description": "A recognizable label of up to 60 characters.",
            "example": "사무실 PBX",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "cidr"
        ],
        "type": "object"
      },
      "Workspace": {
        "description": "The workspace as `GET /v1/workspace` shows it.",
        "properties": {
          "auth_tier": {
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "identity_verified": {
            "type": "boolean"
          },
          "next_action": {
            "description": "A further step the service offers this workspace, when there is one. Follow its method, path and body only when the person's request matches its purpose.",
            "type": [
              "object",
              "null"
            ]
          },
          "number_limit": {
            "format": "int32",
            "type": "integer"
          },
          "usage_tier": {
            "format": "int32",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "auth_tier",
          "usage_tier",
          "number_limit",
          "identity_verified"
        ],
        "type": "object"
      },
      "BusinessVerification": {
        "description": "One business verification attempt.",
        "properties": {
          "business_name": {
            "type": "string"
          },
          "comparison": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ComparisonSummary"
              }
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "decided_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "document_uploaded": {
            "description": "A document is waiting for or has been through a decision.",
            "type": "boolean"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "lookup": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/LookupSummary"
              }
            ]
          },
          "mismatched_fields": {
            "description": "For `value_mismatch`: the names of the submitted values that differ from the document.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "next_action": {
            "description": "What to do next, as an object with a `type`: `upload_document`, `poll`, `wait_for_review`, `none`,\n`resubmit`, `resubmit_after_status_change` (also for a number the lookup does not know yet),\n`ask_representative` (with a `review` step for a name written differently), `ask_owner_to_invite`,\n`ask_workspace_owner` or `contact_support`.",
            "type": "object"
          },
          "opened_on": {
            "type": "string"
          },
          "reason": {
            "description": "Why it was rejected, needs information or is in review: `value_mismatch`, `document_unreadable`,\n`business_suspended`, `business_closed`, `business_unregistered`,\n`business_registration_number_taken`, `representative_name_mismatch`, `requester_not_owner` or\n`workspace_unavailable`. Empty while processing and when approved.",
            "type": [
              "string",
              "null"
            ]
          },
          "registration_number": {
            "type": "string"
          },
          "representative_name": {
            "type": "string"
          },
          "status": {
            "description": "`processing`, `approved`, `rejected`, `needs_information` or `in_review` (a person compares the\nrepresentative name with the identity name).",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "mismatched_fields",
          "document_uploaded",
          "registration_number",
          "opened_on",
          "representative_name",
          "business_name",
          "created_at"
        ],
        "type": "object"
      },
      "ComparisonSummary": {
        "description": "Which submitted values equal the document. Booleans only; the document's values are never returned.",
        "properties": {
          "business_name": {
            "type": "boolean"
          },
          "opened_on": {
            "type": "boolean"
          },
          "registration_number": {
            "type": "boolean"
          },
          "representative_name": {
            "type": "boolean"
          }
        },
        "required": [
          "registration_number",
          "opened_on",
          "representative_name",
          "business_name"
        ],
        "type": "object"
      },
      "LookupSummary": {
        "description": "What the business lookup said when the decision was made. The lookup reports the standing of the registration\nnumber only; it does not confirm any of the four values.",
        "properties": {
          "checked_at": {
            "format": "date-time",
            "type": "string"
          },
          "closed_on": {
            "description": "Closing date as `YYYYMMDD` when the business is closed.",
            "type": [
              "string",
              "null"
            ]
          },
          "provider": {
            "description": "Which provider answered (`hyphen`).",
            "type": "string"
          },
          "standing": {
            "description": "`operating`, `suspended`, `closed` or `unregistered`.",
            "type": "string"
          }
        },
        "required": [
          "provider",
          "standing",
          "checked_at"
        ],
        "type": "object"
      },
      "StartRequest": {
        "description": "The customer's four values. The registration certificate must repeat them and the authorization letter must name\nthe customer by `business_name`.",
        "properties": {
          "business_name": {
            "description": "The customer's business name as on the registration certificate.",
            "type": "string"
          },
          "opened_on": {
            "description": "The customer's opening date as `YYYYMMDD` (`YYYY-MM-DD` is accepted too). Not in the future.",
            "type": "string"
          },
          "registration_number": {
            "description": "The customer's registration number: ten digits, dashes allowed, with a valid check digit.",
            "type": "string"
          },
          "representative_name": {
            "description": "The customer's representative as on the registration certificate (one of them, when it lists several). It is\nnot compared with the submitter's identity.",
            "type": "string"
          }
        },
        "required": [
          "registration_number",
          "opened_on",
          "representative_name",
          "business_name"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "bearer_auth": {
        "bearerFormat": "JWT or opaque token",
        "description": "Send a Supabase session JWT or workspace tk_ API key. POST /v1/api-keys accepts only a one-time tkc_ connect token.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "x-source-sha256": "2a8ca03e91d9358d8c4c84cf2bf0f300148ba532f1e2bc05c575e8dc36a42786"
}
