{
    "openapi": "3.1.0",
    "info": {
        "title": "Ogave SMS Messaging API",
        "version": "1.0.0",
        "description": "Send SMS, WhatsApp messages, voice calls and emails, with fallback between channels; track delivery and receive inbound messages.\nAuthenticate with `Authorization: Bearer <key>`. `live_` keys send and charge; `test_` keys simulate\neverything and never send or charge. Every response carries `X-Request-Id`.\nHuman docs: /docs/api\nHuman docs: https://app.ogave.co/docs/api"
    },
    "servers": [
        {
            "url": "https://app.ogave.co/v1",
            "description": "Ogave SMS API"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "Messages",
            "description": "Send SMS, WhatsApp, voice and email; follow every message."
        },
        {
            "name": "Email",
            "description": "Transactional email with its delivery timeline (accepted, sent, delivered, bounced, opened…)."
        },
        {
            "name": "Account",
            "description": "Balance and prices."
        },
        {
            "name": "Webhooks",
            "description": "Status and inbound webhooks of the account."
        },
        {
            "name": "Verify",
            "description": "One-time codes with fraud protection."
        },
        {
            "name": "Reports",
            "description": "Background exports (CSV / XLSX)."
        },
        {
            "name": "Journeys",
            "description": "Start runs of portal journeys."
        },
        {
            "name": "Number masking",
            "description": "Masked calls between two parties."
        },
        {
            "name": "Integrations",
            "description": "REST hooks (Zapier / Make) and contacts. Guide /docs/integrations"
        },
        {
            "name": "Conversions",
            "description": "Report conversions of sent messages (7-day window)."
        }
    ],
    "paths": {
        "/messages": {
            "post": {
                "tags": [
                    "Messages"
                ],
                "summary": "Send an SMS, WhatsApp message, voice call or email",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "anyOf": [
                                    {
                                        "$ref": "#/components/schemas/MessageRequest"
                                    },
                                    {
                                        "$ref": "#/components/schemas/ChannelMessageRequest"
                                    }
                                ]
                            },
                            "examples": {
                                "sms": {
                                    "value": {
                                        "to": "+573001234567",
                                        "from": "SHOP",
                                        "text": "Your order 42 has shipped",
                                        "client_ref": "order-42"
                                    }
                                },
                                "whatsapp_with_fallback": {
                                    "value": {
                                        "channel": "whatsapp",
                                        "to": "+573001234567",
                                        "template": {
                                            "name": "order_shipped",
                                            "language": "es",
                                            "variables": [
                                                "Ana",
                                                "A123"
                                            ]
                                        },
                                        "fallback": [
                                            {
                                                "channel": "sms",
                                                "after": "5m",
                                                "text": "Ana, tu pedido A123 fue enviado"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Accepted (queued, or scheduled when scheduled_at is in the future)",
                        "headers": {
                            "X-Request-Id": {
                                "$ref": "#/components/headers/RequestId"
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Message"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error"
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "402": {
                        "$ref": "#/components/responses/Error"
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    },
                    "409": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "operationId": "sendMessage"
            },
            "get": {
                "tags": [
                    "Messages"
                ],
                "summary": "List messages (newest first, cursor pagination)",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    },
                    {
                        "name": "starting_after",
                        "in": "query",
                        "description": "id of the last message of the previous page (next_cursor)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "$ref": "#/components/schemas/MessageStatus"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "example": "+573001234567"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "client_ref",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "created_after",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "created_before",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of messages",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Message"
                                            }
                                        },
                                        "has_more": {
                                            "type": "boolean"
                                        },
                                        "next_cursor": {
                                            "type": [
                                                "string",
                                                "null"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "listMessages"
            }
        },
        "/messages/batch": {
            "post": {
                "tags": [
                    "Messages"
                ],
                "summary": "Send to up to 1,000 recipients",
                "description": "Top-level fields are shared; each item may override them. Each recipient is validated and charged independently.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "messages"
                                ],
                                "properties": {
                                    "from": {
                                        "type": "string"
                                    },
                                    "text": {
                                        "type": "string"
                                    },
                                    "template_id": {
                                        "type": "string",
                                        "description": "approved SMS template for every item (items can override)"
                                    },
                                    "scheduled_at": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "validity": {
                                        "type": "integer"
                                    },
                                    "callback_url": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "flash": {
                                        "type": "boolean"
                                    },
                                    "shorten_urls": {
                                        "type": "boolean"
                                    },
                                    "track_clicks": {
                                        "type": "boolean"
                                    },
                                    "category": {
                                        "type": "string",
                                        "enum": [
                                            "marketing",
                                            "transactional"
                                        ],
                                        "default": "transactional"
                                    },
                                    "messages": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 1000,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "to"
                                            ],
                                            "properties": {
                                                "to": {
                                                    "type": "string",
                                                    "description": "E.164 (+573001234567) or national with country",
                                                    "maxLength": 32
                                                },
                                                "country": {
                                                    "type": "string",
                                                    "description": "ISO hint for national numbers",
                                                    "example": "CO"
                                                },
                                                "from": {
                                                    "type": "string",
                                                    "description": "Approved sender ID (≤11 chars) or a number of your account"
                                                },
                                                "text": {
                                                    "type": "string",
                                                    "maxLength": 1600,
                                                    "description": "GSM-7 or Unicode; up to 10 segments"
                                                },
                                                "template_id": {
                                                    "type": "string",
                                                    "description": "Id of an approved SMS template of your account. Without text its text is sent; with text, text must be the template with only its {placeholders} filled in. Required in practice when the plan only allows approved templates (else 422 template_required). Pending/rejected/disabled: template_not_approved; unknown: unknown_template."
                                                },
                                                "client_ref": {
                                                    "type": "string",
                                                    "maxLength": 64
                                                },
                                                "scheduled_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "description": "up to 30 days ahead"
                                                },
                                                "validity": {
                                                    "type": "integer",
                                                    "minimum": 60,
                                                    "maximum": 259200,
                                                    "default": 172800,
                                                    "description": "seconds"
                                                },
                                                "callback_url": {
                                                    "type": "string",
                                                    "format": "uri",
                                                    "description": "overrides the account status URL"
                                                },
                                                "flash": {
                                                    "type": "boolean",
                                                    "default": false,
                                                    "description": "Flash SMS (class 0): shown on screen, not stored. Same price. Some handsets/networks ignore it."
                                                },
                                                "shorten_urls": {
                                                    "type": "boolean",
                                                    "default": false,
                                                    "description": "Replace http(s) links in text by own short links (https://<short domain>/<7 chars>); segments and price count the final text. Destinations that are local/private, other shorteners or blocked are refused (link_refused)."
                                                },
                                                "track_clicks": {
                                                    "type": "boolean",
                                                    "default": false,
                                                    "description": "One short link per recipient (message.clicked webhook, per-recipient click stats). Implies shorten_urls."
                                                },
                                                "category": {
                                                    "type": "string",
                                                    "enum": [
                                                        "marketing",
                                                        "transactional"
                                                    ],
                                                    "default": "transactional",
                                                    "description": "SMS: marketing messages follow the account's sending rules — frequency cap per recipient (over it: 422 frequency_capped, nothing charged) and quiet hours in the recipient's time zone (the message is accepted as scheduled for the end of the quiet hours; delayed_by = quiet_hours). Transactional (default) is never delayed or capped; Verify/OTP is always transactional."
                                                },
                                                "conversion_tracking": {
                                                    "type": "boolean",
                                                    "default": false,
                                                    "description": "Allow reporting a conversion of this message within 7 days (POST /messages/{id}/conversion)."
                                                }
                                            },
                                            "description": "One recipient; any field not given comes from the top level."
                                        }
                                    }
                                }
                            },
                            "example": {
                                "from": "SHOP",
                                "text": "Flash sale today: 20% off",
                                "messages": [
                                    {
                                        "to": "+573001234567"
                                    },
                                    {
                                        "to": "+56987654321",
                                        "text": "Oferta: 20% hoy",
                                        "client_ref": "cl-1"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "At least one recipient accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BatchResult"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "No recipient accepted (or invalid batch shape)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/BatchResult"
                                        },
                                        {
                                            "$ref": "#/components/schemas/Error"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "operationId": "sendBatch"
            }
        },
        "/messages/quote": {
            "post": {
                "tags": [
                    "Messages"
                ],
                "summary": "Price a message and its fallback steps without sending",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "description": "Same body as POST /messages. max_total is the worst case (every step sent). For a plain SMS only the SMS step is returned, without max_total.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ChannelMessageRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Quote",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "quote"
                                        },
                                        "currency": {
                                            "type": "string",
                                            "example": "USD"
                                        },
                                        "max_total": {
                                            "type": "string",
                                            "example": "0.130000"
                                        },
                                        "steps": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "channel": {
                                                        "type": "string"
                                                    },
                                                    "price": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "example": "0.0100",
                                                        "description": "null when the channel is not sold for the destination"
                                                    },
                                                    "after_seconds": {
                                                        "type": "integer",
                                                        "description": "fallback steps only"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "quoteMessage"
            }
        },
        "/messages/{id}": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    },
                    "example": "msg_01m65jn6f5x9jej71dmq941vkb"
                }
            ],
            "get": {
                "tags": [
                    "Messages"
                ],
                "summary": "Get a message",
                "responses": {
                    "200": {
                        "description": "The message",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Message"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "getMessage"
            },
            "delete": {
                "tags": [
                    "Messages"
                ],
                "summary": "Cancel a scheduled message",
                "responses": {
                    "200": {
                        "description": "Canceled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Message"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "cancelMessage"
            }
        },
        "/emails": {
            "post": {
                "tags": [
                    "Email"
                ],
                "summary": "Send one email (transactional by default). From a verified domain of yours, or the platform address with replies to you.",
                "description": "Priced per email (bounces are charged; the address then goes to your suppression list). Test keys simulate the whole timeline and are free. Scope email:send.",
                "operationId": "sendEmail",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "to"
                                ],
                                "properties": {
                                    "to": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "example": "ana@example.com",
                                        "description": "An email address (or the phone number of a contact that has an email)"
                                    },
                                    "from": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "An address of a verified domain of yours (GET /email-identities). Default: your default sender, else the platform address."
                                    },
                                    "from_name": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "reply_to": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Required unless template_id"
                                    },
                                    "html": {
                                        "type": "string",
                                        "description": "Up to 512 KB. Links are tracked and an open pixel added unless track_clicks / track_opens are false."
                                    },
                                    "text": {
                                        "type": "string",
                                        "description": "Plain-text part (made from the HTML when missing; HTML made from it when html is missing)"
                                    },
                                    "template_id": {
                                        "type": "string",
                                        "description": "An email template of yours (Channels › Email › Templates); subject and body from it"
                                    },
                                    "variables": {
                                        "type": "object",
                                        "additionalProperties": {
                                            "type": "string"
                                        },
                                        "description": "Values for {placeholders} in subject, html and text (escaped in HTML)",
                                        "example": {
                                            "first_name": "Ana"
                                        }
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "maxItems": 10,
                                        "description": "5 MB in total by default; executable types (.exe, .js, .bat …) refused",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "filename",
                                                "content"
                                            ],
                                            "properties": {
                                                "filename": {
                                                    "type": "string",
                                                    "maxLength": 150,
                                                    "example": "invoice-1001.pdf"
                                                },
                                                "content": {
                                                    "type": "string",
                                                    "format": "byte",
                                                    "description": "The file in base64"
                                                },
                                                "content_type": {
                                                    "type": "string",
                                                    "example": "application/pdf"
                                                }
                                            }
                                        }
                                    },
                                    "tags": {
                                        "type": "array",
                                        "maxItems": 10,
                                        "items": {
                                            "type": "string",
                                            "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
                                        },
                                        "example": [
                                            "receipt"
                                        ]
                                    },
                                    "metadata": {
                                        "type": "object",
                                        "description": "Up to 20 keys, scalar values, 4 KB; returned on the email and its webhooks",
                                        "example": {
                                            "order_id": "1001"
                                        }
                                    },
                                    "category": {
                                        "type": "string",
                                        "enum": [
                                            "transactional",
                                            "marketing"
                                        ],
                                        "default": "transactional",
                                        "description": "marketing adds an unsubscribe link and List-Unsubscribe headers"
                                    },
                                    "track_opens": {
                                        "type": "boolean",
                                        "default": true
                                    },
                                    "track_clicks": {
                                        "type": "boolean",
                                        "default": true
                                    },
                                    "client_ref": {
                                        "type": "string",
                                        "maxLength": 64
                                    },
                                    "callback_url": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "email.* webhooks of this email go here instead of your status URL"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Accepted and charged; follow it with GET /emails/{id} or the email.* webhooks",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Email"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/Error"
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    },
                    "409": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "get": {
                "tags": [
                    "Email"
                ],
                "summary": "List emails, newest first",
                "operationId": "listEmails",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "accepted",
                                "sent",
                                "deferred",
                                "delivered",
                                "bounced",
                                "failed",
                                "complained",
                                "canceled"
                            ]
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "client_ref",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "created_after",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "created_before",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    },
                    {
                        "name": "starting_after",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of emails with their timelines",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Email"
                                            }
                                        },
                                        "has_more": {
                                            "type": "boolean"
                                        },
                                        "next_cursor": {
                                            "type": [
                                                "string",
                                                "null"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/emails/{id}": {
            "get": {
                "tags": [
                    "Email"
                ],
                "summary": "One email with its timeline",
                "operationId": "getEmail",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "msg_01m6jcgdqgaa9602eh3x9m0d5g"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The email",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Email"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/email-identities": {
            "get": {
                "tags": [
                    "Email"
                ],
                "summary": "What \"from\" may be: your domains, the sender addresses on them, the platform address",
                "operationId": "listEmailIdentities",
                "responses": {
                    "200": {
                        "description": "Sending identities",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/EmailIdentity"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/balance": {
            "get": {
                "tags": [
                    "Account"
                ],
                "summary": "Account balance",
                "responses": {
                    "200": {
                        "description": "Balance",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "balance"
                                        },
                                        "unlimited": {
                                            "type": "boolean"
                                        },
                                        "balance": {
                                            "type": [
                                                "string",
                                                "null"
                                            ],
                                            "example": "48.8390"
                                        },
                                        "currency": {
                                            "type": "string",
                                            "example": "USD"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "operationId": "getBalance"
            }
        },
        "/pricing": {
            "get": {
                "tags": [
                    "Account"
                ],
                "summary": "Price for one destination number",
                "parameters": [
                    {
                        "name": "to",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "+573001234567"
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO country hint for national numbers",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Price per segment",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "to": {
                                            "type": "string"
                                        },
                                        "country": {
                                            "type": "string"
                                        },
                                        "country_name": {
                                            "type": "string"
                                        },
                                        "network": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "description": "original network from the numbering plan when known (not porting-aware)",
                                            "properties": {
                                                "mcc": {
                                                    "type": "string"
                                                },
                                                "mnc": {
                                                    "type": "string"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "source": {
                                                    "type": "string"
                                                }
                                            }
                                        },
                                        "price_per_segment": {
                                            "type": "string",
                                            "example": "0.0120"
                                        },
                                        "currency": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "getPricing"
            }
        },
        "/pricing/countries": {
            "get": {
                "tags": [
                    "Account"
                ],
                "summary": "Price list of the account",
                "responses": {
                    "200": {
                        "description": "Countries enabled for the account",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "country": {
                                                        "type": "string"
                                                    },
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "dial_code": {
                                                        "type": "string"
                                                    },
                                                    "price_per_segment": {
                                                        "type": "string"
                                                    },
                                                    "currency": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "operationId": "listPricingCountries"
            }
        },
        "/webhooks": {
            "get": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "Webhook settings",
                "responses": {
                    "200": {
                        "description": "Settings",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookSettings"
                                }
                            }
                        }
                    }
                },
                "operationId": "getWebhookSettings"
            },
            "put": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "Set status and inbound URLs",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status_url": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "uri"
                                    },
                                    "inbound_url": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "uri"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Settings",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookSettings"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "updateWebhookSettings"
            }
        },
        "/webhooks/rotate-secret": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "Create a new signing secret (returned once)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "New secret in signing_secret"
                    }
                },
                "operationId": "rotateWebhookSecret"
            }
        },
        "/webhooks/deliveries": {
            "get": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "Webhook delivery log",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deliveries",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/WebhookDelivery"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "operationId": "listWebhookDeliveries"
            }
        },
        "/webhooks/deliveries/{id}/retry": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "Resend a webhook now",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookDelivery"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "retryWebhookDelivery"
            }
        },
        "/verify": {
            "post": {
                "tags": [
                    "Verify"
                ],
                "summary": "Send a verification code",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "to"
                                ],
                                "properties": {
                                    "to": {
                                        "type": "string",
                                        "description": "Phone number in international format; with channel email, the email address that receives the code"
                                    },
                                    "country": {
                                        "type": "string"
                                    },
                                    "app_id": {
                                        "type": "string"
                                    },
                                    "channel": {
                                        "type": "string",
                                        "enum": [
                                            "sms",
                                            "whatsapp",
                                            "voice",
                                            "email",
                                            "auto"
                                        ],
                                        "default": "sms",
                                        "description": "email: the code by email (to = address), with the app's email template; auto: SMS first, then the code by email if it is not verified in time (give email)"
                                    },
                                    "channel_order": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 4,
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "sms",
                                                "whatsapp",
                                                "voice",
                                                "email"
                                            ]
                                        },
                                        "description": "channels tried in order; overrides channel; email only as the last one (needs email)"
                                    },
                                    "device_id": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "description": "stable fingerprint of the end user device (per-device fraud limits)"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "description": "end user email for the email fallback (app setting email_fallback, or email in channel_order)"
                                    },
                                    "fallback_after": {
                                        "type": "integer",
                                        "minimum": 30,
                                        "maximum": 600,
                                        "default": 60,
                                        "description": "seconds before the next channel of channel_order"
                                    },
                                    "code_length": {
                                        "type": "integer",
                                        "minimum": 4,
                                        "maximum": 10
                                    },
                                    "code_type": {
                                        "type": "string",
                                        "enum": [
                                            "numeric",
                                            "alphanumeric"
                                        ]
                                    },
                                    "expiry_seconds": {
                                        "type": "integer",
                                        "minimum": 60,
                                        "maximum": 3600
                                    },
                                    "template": {
                                        "type": "string",
                                        "description": "must contain {code}; may use {app_name} and {minutes}"
                                    },
                                    "locale": {
                                        "type": "string",
                                        "enum": [
                                            "en",
                                            "es",
                                            "pt",
                                            "fr",
                                            "de",
                                            "it"
                                        ]
                                    },
                                    "sender_id": {
                                        "type": "string"
                                    },
                                    "ip": {
                                        "type": "string",
                                        "description": "end user's IP (enables per-IP limits)"
                                    }
                                }
                            },
                            "example": {
                                "to": "+573001234567",
                                "locale": "es",
                                "ip": "203.0.113.7"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Pending verification",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Verification"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/Error"
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "operationId": "startVerification"
            },
            "get": {
                "tags": [
                    "Verify"
                ],
                "summary": "List verifications",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100
                        }
                    },
                    {
                        "name": "starting_after",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of verifications"
                    }
                },
                "operationId": "listVerifications"
            }
        },
        "/verify/{id}": {
            "get": {
                "tags": [
                    "Verify"
                ],
                "summary": "Get a verification",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The verification",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Verification"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "getVerification"
            }
        },
        "/verify/{id}/check": {
            "post": {
                "tags": [
                    "Verify"
                ],
                "summary": "Check a code",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "code"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Result of the check",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Verification"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "type": "string",
                                                    "enum": [
                                                        "approved",
                                                        "invalid",
                                                        "expired",
                                                        "max_attempts"
                                                    ]
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "checkVerification"
            }
        },
        "/verify/{id}/resend": {
            "post": {
                "tags": [
                    "Verify"
                ],
                "summary": "Send a new code (after the cooldown)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Verification"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/Error"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "operationId": "resendVerification"
            }
        },
        "/verify/{id}/cancel": {
            "post": {
                "tags": [
                    "Verify"
                ],
                "summary": "Cancel a pending verification",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Canceled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Verification"
                                }
                            }
                        }
                    }
                },
                "operationId": "cancelVerification"
            }
        },
        "/verify/apps": {
            "get": {
                "tags": [
                    "Verify"
                ],
                "summary": "List Verify apps",
                "responses": {
                    "200": {
                        "description": "Apps"
                    }
                },
                "operationId": "listVerifyApps"
            },
            "post": {
                "tags": [
                    "Verify"
                ],
                "summary": "Create a Verify app",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/VerifyApp"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VerifyApp"
                                }
                            }
                        }
                    }
                },
                "operationId": "createVerifyApp"
            }
        },
        "/verify/apps/{id}": {
            "get": {
                "tags": [
                    "Verify"
                ],
                "summary": "Get a Verify app",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "App"
                    }
                },
                "operationId": "getVerifyApp"
            },
            "patch": {
                "tags": [
                    "Verify"
                ],
                "summary": "Update a Verify app",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/VerifyApp"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "App"
                    }
                },
                "operationId": "updateVerifyApp"
            }
        },
        "/verify/templates": {
            "get": {
                "tags": [
                    "Verify"
                ],
                "summary": "Built-in templates by locale",
                "responses": {
                    "200": {
                        "description": "Templates"
                    }
                },
                "operationId": "listVerifyTemplates"
            }
        },
        "/verify/connectors/okta": {
            "post": {
                "tags": [
                    "Verify"
                ],
                "summary": "Okta Telephony Inline Hook: deliver the code Okta made (key with the verify scope)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "app_id",
                        "in": "query",
                        "description": "Verify app (default: the first active one)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "Okta com.okta.telephony.provider request; data.messageProfile.phoneNumber and otpCode are used"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Okta commands (status SUCCESSFUL, transactionId = verification id) or an Okta error object (Okta then uses its own provider)"
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "oktaTelephonyHook"
            }
        },
        "/verify/connectors/auth0": {
            "post": {
                "tags": [
                    "Verify"
                ],
                "summary": "Auth0 custom phone provider: deliver the code Auth0 made (key with the verify scope)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "app_id",
                        "in": "query",
                        "description": "Verify app (default: the first active one)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "event.notification of the Action (recipient, code, delivery_method, locale) or event.message_options of the older Send Phone Message Action"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Code sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string"
                                        },
                                        "object": {
                                            "type": "string"
                                        },
                                        "status": {
                                            "type": "string"
                                        },
                                        "channel": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "auth0PhoneProvider"
            }
        },
        "/journeys/{id}/runs": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "description": "journey id",
                    "schema": {
                        "type": "string"
                    }
                }
            ],
            "post": {
                "tags": [
                    "Journeys"
                ],
                "summary": "Start a run of an active journey for a number",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "to"
                                ],
                                "properties": {
                                    "to": {
                                        "type": "string"
                                    },
                                    "data": {
                                        "type": "object",
                                        "maxProperties": 50,
                                        "additionalProperties": true,
                                        "description": "key/values available to the steps' variables, e.g. {name} in a step text"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The run",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "journey": {
                                            "type": "string"
                                        },
                                        "phone": {
                                            "type": "string"
                                        },
                                        "state": {
                                            "type": "string",
                                            "enum": [
                                                "waiting",
                                                "done",
                                                "failed"
                                            ]
                                        },
                                        "step": {
                                            "type": "string",
                                            "description": "current step id"
                                        },
                                        "created_at": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "live_key_required (test keys)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "409": {
                        "description": "journey_not_active",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "startJourneyRun"
            }
        },
        "/reports": {
            "post": {
                "tags": [
                    "Reports"
                ],
                "summary": "Create a report export (background job)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "description": "Same filters as the portal. Up to 12 months per export, 13 months back. Poll GET /reports/{id} until status is \"ready\", then download from download_url (signed, valid 7 days). Max 3 exports in progress per account (429 too_many_exports).",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ReportRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "429": {
                        "description": "Too many exports in progress"
                    }
                },
                "operationId": "createReport"
            },
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Latest 50 report exports",
                "responses": {
                    "200": {
                        "description": "List"
                    }
                },
                "operationId": "listReports"
            }
        },
        "/reports/{id}": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Status of a report export (with download_url when ready)",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "rep_01m66mpjntv6jy1hph33zh75mt"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Report",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found"
                    }
                },
                "operationId": "getReport"
            }
        },
        "/reports/{id}/cancel": {
            "post": {
                "tags": [
                    "Reports"
                ],
                "summary": "Cancel a queued or running export",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Report"
                    }
                },
                "operationId": "cancelReport"
            }
        },
        "/masking/sessions": {
            "post": {
                "tags": [
                    "Number masking"
                ],
                "summary": "Create a masking session (party A and party B talk through a proxy number)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "party_a",
                                    "party_b"
                                ],
                                "properties": {
                                    "party_a": {
                                        "type": "string",
                                        "example": "+573001234567"
                                    },
                                    "party_b": {
                                        "type": "string",
                                        "example": "+573109876543"
                                    },
                                    "ttl": {
                                        "type": "integer",
                                        "minimum": 300,
                                        "maximum": 2592000,
                                        "default": 21600,
                                        "description": "seconds until the session expires"
                                    },
                                    "number": {
                                        "type": "string",
                                        "description": "proxy number: one of your active voice numbers (Twilio or test); default the first free one"
                                    },
                                    "label": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "client_ref": {
                                        "type": "string",
                                        "maxLength": 64
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MaskingSession"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "no_proxy_available",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "same_party, invalid_ttl, invalid_number, unknown_number, no_channel_account, not_sellable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "operationId": "createMaskingSession"
            },
            "get": {
                "tags": [
                    "Number masking"
                ],
                "summary": "List sessions of the key's mode",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "open",
                                "closed",
                                "expired"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/MaskingSession"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "operationId": "listMaskingSessions"
            }
        },
        "/masking/sessions/{id}": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "example": "mks_01m68hhbrawevwskpkbpx6mhxk"
                    }
                }
            ],
            "get": {
                "tags": [
                    "Number masking"
                ],
                "summary": "A session with its call log",
                "responses": {
                    "200": {
                        "description": "The session with calls",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MaskingSession"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "not_found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "operationId": "getMaskingSession"
            }
        },
        "/masking/sessions/{id}/close": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ],
            "post": {
                "tags": [
                    "Number masking"
                ],
                "summary": "Close a session now",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The closed session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MaskingSession"
                                }
                            }
                        }
                    }
                },
                "operationId": "closeMaskingSession"
            }
        },
        "/masking/sessions/{id}/simulate-call": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ],
            "post": {
                "tags": [
                    "Number masking"
                ],
                "summary": "Simulated call to the proxy (test sessions / test numbers only)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "from": {
                                        "type": "string",
                                        "description": "caller; default party_a"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The call",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MaskingCall"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "live_number",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "operationId": "simulateMaskingCall"
            }
        },
        "/hooks": {
            "get": {
                "tags": [
                    "Integrations"
                ],
                "summary": "REST hook subscriptions (mode of the key)",
                "responses": {
                    "200": {
                        "description": "Hooks",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Hook"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "operationId": "listHooks"
            },
            "post": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Subscribe a URL to an event (Zapier / Make instant triggers)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "description": "Events are delivered like webhooks (same envelope, Webhook-Signature, retries, delivery log), always as JSON POST. Answer 410 Gone to delete the hook. Human docs /docs/integrations",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "event",
                                    "target_url"
                                ],
                                "properties": {
                                    "event": {
                                        "$ref": "#/components/schemas/HookEvent"
                                    },
                                    "target_url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 500
                                    },
                                    "platform": {
                                        "type": "string",
                                        "enum": [
                                            "zapier",
                                            "make",
                                            "other"
                                        ],
                                        "default": "other"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Subscribed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Hook"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "description": "validation_failed (event, target_url) or limit_reached",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "operationId": "createHook"
            }
        },
        "/hooks/{id}": {
            "delete": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Unsubscribe",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "hook_01m68hrytj1g8bfxwpe3w9gmwz"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string"
                                        },
                                        "object": {
                                            "type": "string",
                                            "example": "hook"
                                        },
                                        "deleted": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "deleteHook"
            }
        },
        "/hooks/samples/{event}": {
            "get": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Latest 3 real events of this type for the account (else one example), for field mapping",
                "parameters": [
                    {
                        "name": "event",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "$ref": "#/components/schemas/HookEvent"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Events",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/HookEnvelope"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "getHookSample"
            }
        },
        "/contact-lists": {
            "get": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Your contact lists",
                "responses": {
                    "200": {
                        "description": "Lists",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/ContactList"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "operationId": "listContactLists"
            },
            "post": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Create a contact list",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ContactList"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "createContactList"
            }
        },
        "/contacts": {
            "get": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Search contacts",
                "parameters": [
                    {
                        "name": "list_id",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "phone",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "+573001234567"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Contacts",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "example": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Contact"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "listContacts"
            },
            "post": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Add or update a contact (the phone is the key inside a list)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "description": "Same rules as file imports. Blacklisted numbers are refused (opted_out); a contact that unsubscribed is updated but never re-subscribed.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "allOf": [
                                    {
                                        "type": "object",
                                        "required": [
                                            "list_id",
                                            "phone"
                                        ],
                                        "properties": {
                                            "list_id": {
                                                "type": "string"
                                            },
                                            "phone": {
                                                "type": "string",
                                                "example": "+573001234567"
                                            }
                                        }
                                    },
                                    {
                                        "$ref": "#/components/schemas/ContactFields"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Contact"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Contact"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "description": "invalid_number, opted_out, validation_failed (param fields.<TAG> for unknown fields or values that do not fit the type)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "operationId": "createContact"
            }
        },
        "/contacts/{id}": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ],
            "get": {
                "tags": [
                    "Integrations"
                ],
                "summary": "One contact",
                "responses": {
                    "200": {
                        "description": "Contact",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Contact"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "getContact"
            },
            "patch": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Update fields of a contact",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ContactFields"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Contact",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Contact"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "updateContact"
            },
            "delete": {
                "tags": [
                    "Integrations"
                ],
                "summary": "Delete a contact",
                "responses": {
                    "200": {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string"
                                        },
                                        "object": {
                                            "type": "string",
                                            "example": "contact"
                                        },
                                        "deleted": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "operationId": "deleteContact"
            }
        },
        "/messages/{id}/conversion": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    },
                    "example": "msg_01m65jn6f5x9jej71dmq941vkb"
                }
            ],
            "post": {
                "tags": [
                    "Conversions"
                ],
                "summary": "Report a conversion of a message sent with conversion_tracking (within 7 days)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "operationId": "reportConversion",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "converted_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Default now; between the sending time and now."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "example": 49.9
                                    },
                                    "currency": {
                                        "type": "string",
                                        "minLength": 3,
                                        "maxLength": 3,
                                        "example": "USD",
                                        "description": "ISO 4217, required with value"
                                    },
                                    "event": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "pattern": "^[A-Za-z0-9_.:-]+$",
                                        "example": "purchase"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The conversion (201 the first time, 200 when it was already reported)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Conversion"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "The conversion (201 the first time, 200 when it was already reported)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Conversion"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "409": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/conversions": {
            "post": {
                "tags": [
                    "Conversions"
                ],
                "summary": "Report a conversion by phone number (latest tracked or campaign message to it in the last 7 days)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "operationId": "reportConversionByNumber",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "allOf": [
                                    {
                                        "type": "object",
                                        "properties": {
                                            "converted_at": {
                                                "type": "string",
                                                "format": "date-time",
                                                "description": "Default now; between the sending time and now."
                                            },
                                            "value": {
                                                "type": "number",
                                                "minimum": 0,
                                                "example": 49.9
                                            },
                                            "currency": {
                                                "type": "string",
                                                "minLength": 3,
                                                "maxLength": 3,
                                                "example": "USD",
                                                "description": "ISO 4217, required with value"
                                            },
                                            "event": {
                                                "type": "string",
                                                "maxLength": 40,
                                                "pattern": "^[A-Za-z0-9_.:-]+$",
                                                "example": "purchase"
                                            }
                                        }
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "to"
                                        ],
                                        "properties": {
                                            "to": {
                                                "type": "string",
                                                "example": "+573001234567"
                                            },
                                            "country": {
                                                "type": "string",
                                                "minLength": 2,
                                                "maxLength": 2
                                            }
                                        }
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The conversion (201 the first time, 200 when it was already reported)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Conversion"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "The conversion (201 the first time, 200 when it was already reported)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Conversion"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "409": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "get": {
                "tags": [
                    "Conversions"
                ],
                "summary": "List conversions, newest first",
                "operationId": "listConversions",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "starting_after",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "message_id",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of conversions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "object": {
                                            "type": "string",
                                            "const": "list"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Conversion"
                                            }
                                        },
                                        "has_more": {
                                            "type": "boolean"
                                        },
                                        "next_cursor": {
                                            "type": [
                                                "string",
                                                "null"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "live_… or test_… key"
            }
        },
        "headers": {
            "RequestId": {
                "description": "Request id (send your own in X-Request-Id to correlate)",
                "schema": {
                    "type": "string"
                }
            }
        },
        "parameters": {
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "description": "Optional on every POST. Same key + same body (compared as JSON) within 24 h returns the first response (Idempotent-Replayed: true) and never acts twice. Same key with another body: 409 idempotency_conflict.",
                "schema": {
                    "type": "string",
                    "maxLength": 64
                }
            }
        },
        "responses": {
            "Error": {
                "description": "Error",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Too many requests for this key",
                "headers": {
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        }
                    },
                    "X-RateLimit-Limit": {
                        "schema": {
                            "type": "integer"
                        }
                    },
                    "X-RateLimit-Remaining": {
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "ReportRequest": {
                "type": "object",
                "required": [
                    "date_from",
                    "date_to"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "messages",
                            "summary",
                            "transactions"
                        ],
                        "default": "messages"
                    },
                    "format": {
                        "type": "string",
                        "enum": [
                            "csv",
                            "xlsx"
                        ],
                        "default": "csv",
                        "description": "xlsx up to 200,000 rows"
                    },
                    "date_from": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-10-01"
                    },
                    "date_to": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-10-31",
                        "description": "inclusive"
                    },
                    "timezone": {
                        "type": "string",
                        "example": "America/Bogota",
                        "description": "IANA zone; default = account time zone"
                    },
                    "group_by": {
                        "type": "string",
                        "enum": [
                            "day",
                            "week",
                            "month",
                            "country",
                            "network",
                            "sender",
                            "campaign",
                            "source",
                            "api_key",
                            "error",
                            "delivery_time",
                            "status",
                            "account"
                        ],
                        "description": "summary only"
                    },
                    "columns": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "message_id",
                                "client_ref",
                                "campaign_id",
                                "campaign_name",
                                "source",
                                "api_key",
                                "sender",
                                "destination",
                                "country",
                                "network_code",
                                "network_name",
                                "text",
                                "encoding",
                                "segments",
                                "flash",
                                "price_per_segment",
                                "cost",
                                "currency",
                                "accepted_at",
                                "sent_at",
                                "final_at",
                                "delivery_seconds",
                                "status",
                                "dlr_status",
                                "error_code",
                                "error_description",
                                "scheduled_at",
                                "validity_until",
                                "account",
                                "sender_ip"
                            ]
                        }
                    },
                    "text_mode": {
                        "type": "string",
                        "enum": [
                            "full",
                            "masked",
                            "none"
                        ],
                        "default": "full",
                        "description": "Verify codes are always masked"
                    },
                    "delimiter": {
                        "type": "string",
                        "enum": [
                            "comma",
                            "semicolon"
                        ],
                        "default": "comma"
                    },
                    "gzip": {
                        "type": "boolean",
                        "default": false
                    },
                    "filters": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "enum": [
                                        "delivered",
                                        "undelivered",
                                        "expired",
                                        "rejected",
                                        "failed",
                                        "pending"
                                    ]
                                }
                            },
                            "country": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "example": "CO"
                                }
                            },
                            "network": {
                                "type": "string",
                                "example": "732-101",
                                "description": "MCC-MNC"
                            },
                            "sender": {
                                "type": "string"
                            },
                            "campaign_id": {
                                "type": "integer"
                            },
                            "source": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "enum": [
                                        "portal",
                                        "campaign",
                                        "csv",
                                        "automation",
                                        "api_v1",
                                        "api_v3",
                                        "verify"
                                    ]
                                }
                            },
                            "api_key_id": {
                                "type": "integer"
                            },
                            "account_id": {
                                "type": "integer",
                                "description": "one of your sub-accounts"
                            },
                            "destination": {
                                "type": "string",
                                "description": "number contains"
                            },
                            "text": {
                                "type": "string",
                                "description": "text contains"
                            },
                            "error_code": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "Report": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "rep_01m66mpjntv6jy1hph33zh75mt"
                    },
                    "object": {
                        "type": "string",
                        "example": "report"
                    },
                    "type": {
                        "type": "string"
                    },
                    "format": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "queued",
                            "running",
                            "ready",
                            "failed",
                            "cancelled",
                            "expired"
                        ]
                    },
                    "progress": {
                        "type": "integer",
                        "description": "0-100"
                    },
                    "rows": {
                        "type": "integer"
                    },
                    "rows_estimated": {
                        "type": "integer"
                    },
                    "download_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "expires_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "error": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "finished_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                }
            },
            "HookEvent": {
                "type": "string",
                "enum": [
                    "message.delivered",
                    "message.clicked",
                    "message.inbound",
                    "contact.opted_out"
                ]
            },
            "Hook": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "hook_01m68hrytj1g8bfxwpe3w9gmwz"
                    },
                    "object": {
                        "type": "string",
                        "example": "hook"
                    },
                    "event": {
                        "$ref": "#/components/schemas/HookEvent"
                    },
                    "target_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "platform": {
                        "type": "string",
                        "enum": [
                            "zapier",
                            "make",
                            "other"
                        ]
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "last_delivery_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                }
            },
            "HookEnvelope": {
                "type": "object",
                "description": "Body of every hook delivery. data = message object (message.*), inbound message (message.inbound) or opt-out {phone, scope group|all, group_id, group_name, source, keyword, opted_out_at}",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "evt_01m68hqvk6rbnpcn6d3th1q8s8"
                    },
                    "type": {
                        "$ref": "#/components/schemas/HookEvent"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            },
            "ContactList": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "6ae4daa666119"
                    },
                    "object": {
                        "type": "string",
                        "example": "contact_list"
                    },
                    "name": {
                        "type": "string"
                    },
                    "contacts": {
                        "type": "integer"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "ContactFields": {
                "type": "object",
                "properties": {
                    "country": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 2,
                        "description": "ISO country for national numbers"
                    },
                    "first_name": {
                        "type": "string",
                        "maxLength": 100
                    },
                    "last_name": {
                        "type": "string",
                        "maxLength": 100
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "company": {
                        "type": "string"
                    },
                    "fields": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string",
                            "maxLength": 255
                        },
                        "description": "field tag → value (e.g. BIRTH_DATE: 2000-01-31)"
                    }
                }
            },
            "Contact": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "object": {
                        "type": "string",
                        "example": "contact"
                    },
                    "list_id": {
                        "type": "string"
                    },
                    "phone": {
                        "type": "string",
                        "example": "+573001234567"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "subscribed",
                            "unsubscribed",
                            "pending",
                            "bounced",
                            "complained",
                            "blocked"
                        ]
                    },
                    "first_name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "last_name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "email": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "fields": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    },
                    "created": {
                        "type": "boolean",
                        "description": "POST only — true when the contact was created"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "MaskingSession": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "masking_session"
                    },
                    "id": {
                        "type": "string"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "open",
                            "closed",
                            "expired"
                        ]
                    },
                    "proxy_number": {
                        "type": "string"
                    },
                    "party_a": {
                        "type": "string"
                    },
                    "party_b": {
                        "type": "string"
                    },
                    "label": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "client_ref": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "calls_count": {
                        "type": "integer"
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "closed_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "calls": {
                        "type": "array",
                        "description": "GET /masking/sessions/{id} only",
                        "items": {
                            "$ref": "#/components/schemas/MaskingCall"
                        }
                    }
                }
            },
            "MaskingCall": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "direction": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "a_to_b",
                            "b_to_a"
                        ]
                    },
                    "from": {
                        "type": "string"
                    },
                    "to": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "ringing",
                            "completed",
                            "busy",
                            "no_answer",
                            "failed",
                            "canceled",
                            "rejected"
                        ]
                    },
                    "reason": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "duration_seconds": {
                        "type": "integer"
                    },
                    "billable_seconds": {
                        "type": "integer"
                    },
                    "price": {
                        "type": "string"
                    },
                    "started_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "ended_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                }
            },
            "MessageStatus": {
                "type": "string",
                "enum": [
                    "scheduled",
                    "queued",
                    "sent",
                    "delivered",
                    "undelivered",
                    "expired",
                    "rejected",
                    "failed",
                    "canceled",
                    "read",
                    "ringing",
                    "answered",
                    "completed",
                    "busy",
                    "no_answer"
                ],
                "description": "email: read = opened, failed = bounced (the address is suppressed)"
            },
            "MessageRequest": {
                "type": "object",
                "required": [
                    "to",
                    "from"
                ],
                "description": "text is required unless template_id is sent.",
                "properties": {
                    "to": {
                        "type": "string",
                        "description": "E.164 (+573001234567) or national with country",
                        "maxLength": 32
                    },
                    "country": {
                        "type": "string",
                        "description": "ISO hint for national numbers",
                        "example": "CO"
                    },
                    "from": {
                        "type": "string",
                        "description": "Approved sender ID (≤11 chars) or a number of your account"
                    },
                    "text": {
                        "type": "string",
                        "maxLength": 1600,
                        "description": "GSM-7 or Unicode; up to 10 segments"
                    },
                    "template_id": {
                        "type": "string",
                        "description": "Id of an approved SMS template of your account. Without text its text is sent; with text, text must be the template with only its {placeholders} filled in. Required in practice when the plan only allows approved templates (else 422 template_required). Pending/rejected/disabled: template_not_approved; unknown: unknown_template."
                    },
                    "client_ref": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "scheduled_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "up to 30 days ahead"
                    },
                    "validity": {
                        "type": "integer",
                        "minimum": 60,
                        "maximum": 259200,
                        "default": 172800,
                        "description": "seconds"
                    },
                    "callback_url": {
                        "type": "string",
                        "format": "uri",
                        "description": "overrides the account status URL"
                    },
                    "flash": {
                        "type": "boolean",
                        "default": false,
                        "description": "Flash SMS (class 0): shown on screen, not stored. Same price. Some handsets/networks ignore it."
                    },
                    "shorten_urls": {
                        "type": "boolean",
                        "default": false,
                        "description": "Replace http(s) links in text by own short links (https://<short domain>/<7 chars>); segments and price count the final text. Destinations that are local/private, other shorteners or blocked are refused (link_refused)."
                    },
                    "track_clicks": {
                        "type": "boolean",
                        "default": false,
                        "description": "One short link per recipient (message.clicked webhook, per-recipient click stats). Implies shorten_urls."
                    },
                    "category": {
                        "type": "string",
                        "enum": [
                            "marketing",
                            "transactional"
                        ],
                        "default": "transactional",
                        "description": "SMS: marketing messages follow the account's sending rules — frequency cap per recipient (over it: 422 frequency_capped, nothing charged) and quiet hours in the recipient's time zone (the message is accepted as scheduled for the end of the quiet hours; delayed_by = quiet_hours). Transactional (default) is never delayed or capped; Verify/OTP is always transactional."
                    },
                    "conversion_tracking": {
                        "type": "boolean",
                        "default": false,
                        "description": "Allow reporting a conversion of this message within 7 days (POST /messages/{id}/conversion)."
                    }
                }
            },
            "ChannelMessageRequest": {
                "type": "object",
                "required": [
                    "to"
                ],
                "properties": {
                    "channel": {
                        "type": "string",
                        "enum": [
                            "sms",
                            "whatsapp",
                            "rcs",
                            "telegram",
                            "viber",
                            "voice",
                            "email",
                            "auto"
                        ],
                        "default": "sms"
                    },
                    "to": {
                        "type": "string",
                        "description": "phone number; for email an email address, or the phone number of a contact with an email (else 422 no_email)"
                    },
                    "account": {
                        "type": "string",
                        "description": "id of one of your WhatsApp / voice numbers, RCS agents, Telegram or Viber bots (default: the first active one)"
                    },
                    "suggestions": {
                        "type": "array",
                        "maxItems": 11,
                        "items": {
                            "type": "string",
                            "maxLength": 25
                        },
                        "description": "RCS only: suggested replies (invalid_suggestions)"
                    },
                    "text": {
                        "type": "string",
                        "description": "SMS text, WhatsApp session text (24 h window, ≤ 4096), text read on a voice call, or the plain-text body of an email"
                    },
                    "from": {
                        "type": "string",
                        "description": "SMS: sender ID. Email: an address of one of your verified domains or sender identities (else 422 from_not_verified); default your default sender identity, else the platform address with Reply-To your account email"
                    },
                    "from_name": {
                        "type": "string",
                        "maxLength": 100,
                        "description": "email only"
                    },
                    "reply_to": {
                        "type": "string",
                        "format": "email",
                        "description": "email only"
                    },
                    "subject": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "email: required unless email_template (missing_subject)"
                    },
                    "html": {
                        "type": "string",
                        "description": "email HTML body, ≤ 512 KB; links are click-tracked"
                    },
                    "email_template": {
                        "type": "string",
                        "description": "email: id of one of your email templates (subject, html, text, category)"
                    },
                    "variables": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        },
                        "description": "email: values for {placeholders}, e.g. {first_name}; HTML-escaped in html"
                    },
                    "category": {
                        "type": "string",
                        "enum": [
                            "transactional",
                            "marketing"
                        ],
                        "default": "transactional",
                        "description": "email: marketing adds an unsubscribe link and List-Unsubscribe"
                    },
                    "track_opens": {
                        "type": "boolean",
                        "default": true
                    },
                    "track_clicks": {
                        "type": "boolean",
                        "default": true
                    },
                    "template": {
                        "type": "object",
                        "required": [
                            "name"
                        ],
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "language": {
                                "type": "string",
                                "example": "es"
                            },
                            "variables": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "maxLength": 1024
                                }
                            }
                        }
                    },
                    "media": {
                        "type": "object",
                        "required": [
                            "url"
                        ],
                        "description": "WhatsApp (type required), RCS / Telegram / Viber (an image; type not needed)",
                        "properties": {
                            "type": {
                                "type": "string",
                                "enum": [
                                    "image",
                                    "document",
                                    "video",
                                    "audio"
                                ]
                            },
                            "url": {
                                "type": "string",
                                "format": "uri",
                                "description": "https only"
                            },
                            "caption": {
                                "type": "string",
                                "maxLength": 1024
                            },
                            "filename": {
                                "type": "string",
                                "maxLength": 120
                            }
                        }
                    },
                    "tts": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "object",
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "maxLength": 1000
                                    },
                                    "language": {
                                        "type": "string",
                                        "example": "es-MX",
                                        "default": "es-MX"
                                    },
                                    "voice": {
                                        "type": "string",
                                        "enum": [
                                            "female",
                                            "male"
                                        ],
                                        "default": "female"
                                    }
                                }
                            }
                        ]
                    },
                    "audio_url": {
                        "type": "string",
                        "format": "uri",
                        "description": "https only"
                    },
                    "ivr": {
                        "type": "string",
                        "description": "IVR flow id"
                    },
                    "client_ref": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "callback_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "fallback": {
                        "type": "array",
                        "maxItems": 3,
                        "items": {
                            "type": "object",
                            "required": [
                                "channel"
                            ],
                            "properties": {
                                "channel": {
                                    "type": "string",
                                    "enum": [
                                        "sms",
                                        "whatsapp",
                                        "rcs",
                                        "telegram",
                                        "viber",
                                        "voice",
                                        "email"
                                    ]
                                },
                                "after": {
                                    "type": "string",
                                    "pattern": "^[0-9]{1,4}[smh]$",
                                    "default": "5m",
                                    "description": "30 s to 24 h"
                                },
                                "text": {
                                    "type": "string"
                                },
                                "from": {
                                    "type": "string"
                                },
                                "template": {
                                    "type": "object"
                                },
                                "media": {
                                    "type": "object"
                                },
                                "tts": {
                                    "type": "object"
                                },
                                "audio_url": {
                                    "type": "string"
                                },
                                "ivr": {
                                    "type": "string"
                                },
                                "account": {
                                    "type": "string"
                                },
                                "subject": {
                                    "type": "string"
                                },
                                "html": {
                                    "type": "string"
                                },
                                "email_template": {
                                    "type": "string"
                                },
                                "variables": {
                                    "type": "object"
                                },
                                "category": {
                                    "type": "string",
                                    "enum": [
                                        "transactional",
                                        "marketing"
                                    ]
                                }
                            }
                        }
                    }
                }
            },
            "MessageRequestPartial": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/MessageRequest"
                    }
                ],
                "required": [
                    "to"
                ]
            },
            "Message": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "msg_01m65jn6f5x9jej71dmq941vkb"
                    },
                    "object": {
                        "type": "string",
                        "example": "message"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    },
                    "to": {
                        "type": "string"
                    },
                    "from": {
                        "type": "string"
                    },
                    "text": {
                        "type": "string"
                    },
                    "client_ref": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "status": {
                        "$ref": "#/components/schemas/MessageStatus"
                    },
                    "error": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "description": {
                                "type": "string"
                            }
                        }
                    },
                    "encoding": {
                        "type": "string",
                        "enum": [
                            "GSM-7",
                            "UCS-2"
                        ]
                    },
                    "segments": {
                        "type": "integer"
                    },
                    "flash": {
                        "type": "boolean"
                    },
                    "price": {
                        "type": "string",
                        "example": "0.0120"
                    },
                    "currency": {
                        "type": "string",
                        "example": "USD"
                    },
                    "country": {
                        "type": "string",
                        "example": "CO"
                    },
                    "scheduled_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "category": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "marketing",
                            "transactional"
                        ],
                        "description": "SMS only (null for other channels)"
                    },
                    "delayed_by": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "quiet_hours"
                        ],
                        "description": "set when the sending rules moved scheduled_at (quiet hours at the recipient)"
                    },
                    "callback_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "submitted_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "done_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "channel": {
                        "type": "string",
                        "enum": [
                            "sms",
                            "whatsapp",
                            "rcs",
                            "telegram",
                            "viber",
                            "voice",
                            "email"
                        ]
                    },
                    "email": {
                        "type": "object",
                        "description": "email messages only",
                        "properties": {
                            "subject": {
                                "type": "string"
                            },
                            "category": {
                                "type": "string",
                                "enum": [
                                    "transactional",
                                    "marketing"
                                ]
                            },
                            "template": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "from_name": {
                                "type": "string"
                            },
                            "reply_to": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "opens": {
                                "type": "integer"
                            },
                            "clicks": {
                                "type": "integer"
                            },
                            "opened_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            },
                            "clicked_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            }
                        }
                    },
                    "whatsapp": {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "enum": [
                                    "template",
                                    "text",
                                    "media",
                                    "otp"
                                ]
                            },
                            "template": {
                                "type": "string"
                            },
                            "language": {
                                "type": "string"
                            },
                            "category": {
                                "type": "string",
                                "enum": [
                                    "marketing",
                                    "utility",
                                    "authentication",
                                    "service"
                                ]
                            },
                            "media_url": {
                                "type": "string"
                            }
                        }
                    },
                    "voice": {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "enum": [
                                    "tts",
                                    "audio",
                                    "ivr",
                                    "otp"
                                ]
                            },
                            "duration": {
                                "type": [
                                    "integer",
                                    "null"
                                ]
                            },
                            "billable_seconds": {
                                "type": [
                                    "integer",
                                    "null"
                                ]
                            },
                            "digits": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            }
                        }
                    },
                    "fallback": {
                        "type": "object",
                        "properties": {
                            "previous": {
                                "type": "string"
                            },
                            "next": {
                                "type": "string"
                            },
                            "pending": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "channel": {
                                            "type": "string"
                                        },
                                        "after_seconds": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "conversion_tracking": {
                        "type": "boolean"
                    }
                }
            },
            "BatchResult": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "batch"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "accepted": {
                        "type": "integer"
                    },
                    "rejected": {
                        "type": "integer"
                    },
                    "total_price": {
                        "type": "string"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "index": {
                                    "type": "integer"
                                },
                                "message": {
                                    "$ref": "#/components/schemas/Message"
                                },
                                "error": {
                                    "type": "object",
                                    "properties": {
                                        "code": {
                                            "type": "string"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "param": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "WebhookSettings": {
                "type": "object",
                "properties": {
                    "status_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "inbound_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "signing_secret_hint": {
                        "type": "string"
                    }
                }
            },
            "WebhookDelivery": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "event": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "delivered",
                            "failed"
                        ]
                    },
                    "attempts": {
                        "type": "integer"
                    },
                    "next_attempt_at": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "last_response_code": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "last_error": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "payload": {
                        "type": "object"
                    }
                }
            },
            "Verification": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "ver_01m65mc32mhad5g95nbspkpdr4"
                    },
                    "object": {
                        "type": "string",
                        "example": "verification"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    },
                    "app_id": {
                        "type": "string"
                    },
                    "to": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "channel": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "approved",
                            "expired",
                            "canceled",
                            "max_attempts",
                            "failed"
                        ]
                    },
                    "attempts": {
                        "type": "integer"
                    },
                    "attempts_remaining": {
                        "type": "integer"
                    },
                    "resends": {
                        "type": "integer"
                    },
                    "locale": {
                        "type": "string"
                    },
                    "test_number": {
                        "type": "boolean"
                    },
                    "price": {
                        "type": "string"
                    },
                    "currency": {
                        "type": "string"
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "approved_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "verified_channel": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "sms",
                            "whatsapp",
                            "voice",
                            "email",
                            null
                        ],
                        "description": "channel whose code was entered (approved verifications)"
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "api",
                            "okta",
                            "auth0"
                        ],
                        "description": "who made the code: api (we did), okta / auth0 (the platform checks it)"
                    },
                    "pricing": {
                        "type": "string",
                        "enum": [
                            "per_message",
                            "per_success"
                        ],
                        "description": "per_message: every code message is charged; per_success: one fee per approved verification (plan setting)"
                    },
                    "email_fallback": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "email": {
                                "type": "string",
                                "description": "masked"
                            },
                            "due_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            },
                            "sent_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            }
                        }
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "VerifyApp": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "code_length": {
                        "type": "integer"
                    },
                    "code_type": {
                        "type": "string",
                        "enum": [
                            "numeric",
                            "alphanumeric"
                        ]
                    },
                    "expiry_seconds": {
                        "type": "integer"
                    },
                    "max_attempts": {
                        "type": "integer"
                    },
                    "resend_cooldown_seconds": {
                        "type": "integer"
                    },
                    "max_resends": {
                        "type": "integer"
                    },
                    "sender_id": {
                        "type": "string"
                    },
                    "template": {
                        "type": "string"
                    },
                    "default_locale": {
                        "type": "string"
                    },
                    "allowed_countries": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "denied_countries": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "test_numbers": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "number": {
                                    "type": "string"
                                },
                                "code": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "fraud_limits": {
                        "type": "object"
                    },
                    "flash": {
                        "type": "boolean",
                        "description": "send codes as Flash SMS"
                    },
                    "email_fallback": {
                        "type": "boolean",
                        "description": "also send a code by email when the request has email and the code is not verified in time"
                    },
                    "email_fallback_after": {
                        "type": "integer",
                        "minimum": 30,
                        "maximum": 600,
                        "default": 60
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "disabled"
                        ]
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "required": [
                            "code",
                            "message",
                            "request_id"
                        ],
                        "properties": {
                            "code": {
                                "type": "string",
                                "example": "insufficient_balance",
                                "description": "e.g. insufficient_balance, suppressed, from_not_verified, no_email, missing_subject"
                            },
                            "message": {
                                "type": "string"
                            },
                            "param": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "doc_url": {
                                "type": "string"
                            },
                            "request_id": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "Conversion": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "conv_01jbsample0000000000000000"
                    },
                    "object": {
                        "type": "string",
                        "const": "conversion"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "api",
                            "verify",
                            "campaign"
                        ]
                    },
                    "message_id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "campaign_id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "event": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "value": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "49.90"
                    },
                    "currency": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "sent_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "converted_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "seconds_to_convert": {
                        "type": "integer"
                    }
                }
            },
            "EmailEvent": {
                "type": "object",
                "description": "One step of an email. Webhook events: email.sent, email.delivered, email.deferred, email.bounced, email.failed, email.complained, email.opened, email.clicked, email.unsubscribed (data = the Email + event).",
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "accepted",
                            "sent",
                            "delivered",
                            "deferred",
                            "bounced",
                            "failed",
                            "complained",
                            "opened",
                            "clicked",
                            "unsubscribed"
                        ]
                    },
                    "at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "detail": {
                        "type": "string",
                        "description": "Bounce / failure reason or the provider answer"
                    },
                    "url": {
                        "type": "string",
                        "description": "The link clicked"
                    }
                }
            },
            "Email": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "msg_01m6jcgdqgaa9602eh3x9m0d5g"
                    },
                    "object": {
                        "type": "string",
                        "example": "email"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "accepted",
                            "sent",
                            "deferred",
                            "delivered",
                            "bounced",
                            "failed",
                            "complained",
                            "canceled"
                        ]
                    },
                    "to": {
                        "type": "string"
                    },
                    "from": {
                        "type": "string"
                    },
                    "from_name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "reply_to": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "subject": {
                        "type": "string"
                    },
                    "template": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "category": {
                        "type": "string"
                    },
                    "tags": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "metadata": {
                        "type": "object"
                    },
                    "attachments": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "filename": {
                                    "type": "string"
                                },
                                "content_type": {
                                    "type": "string"
                                },
                                "size": {
                                    "type": "integer"
                                }
                            }
                        }
                    },
                    "client_ref": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "price": {
                        "type": "string",
                        "example": "0.0010"
                    },
                    "currency": {
                        "type": "string"
                    },
                    "opened": {
                        "type": "boolean"
                    },
                    "opens": {
                        "type": "integer"
                    },
                    "opened_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "clicked": {
                        "type": "boolean"
                    },
                    "clicks": {
                        "type": "integer"
                    },
                    "clicked_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "unsubscribed": {
                        "type": "boolean"
                    },
                    "error": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "code": {
                                "type": "string",
                                "enum": [
                                    "bounced",
                                    "not_sent"
                                ]
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    },
                    "events": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/EmailEvent"
                        }
                    },
                    "callback_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "EmailIdentity": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "domain",
                            "sender",
                            "platform"
                        ]
                    },
                    "domain": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "verified",
                            "failed"
                        ]
                    },
                    "checks": {
                        "type": "object"
                    },
                    "verified_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "email": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "reply_to": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "default": {
                        "type": "boolean"
                    },
                    "usable": {
                        "type": "boolean"
                    }
                }
            }
        }
    }
}