{
  "openapi": "3.0.3",
  "info": {
    "title": "Allo API",
    "description": "Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages.\n\nAll requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation.",
    "version": "1.0.0",
    "contact": {
      "name": "Allo Support"
    }
  },
  "servers": [
    {
      "url": "https://api.withallo.com",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Summary Templates",
      "description": "Manage call summary templates that control how AI-generated call summaries are structured for your team."
    },
    {
      "name": "Webhooks",
      "description": "Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret."
    },
    {
      "name": "Calls",
      "description": "Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number."
    },
    {
      "name": "Contacts",
      "description": "Search and retrieve contact information with sorting and pagination. Includes engagement level tracking."
    },
    {
      "name": "SMS",
      "description": "Send SMS messages to phone numbers using your Allo numbers."
    },
    {
      "name": "Fax",
      "description": "Send a PDF as a fax from an Allo line with fax turned on. Sent and received faxes appear in conversation items."
    },
    {
      "name": "Phone Numbers",
      "description": "Retrieve information about your Allo phone numbers."
    },
    {
      "name": "Analytics",
      "description": "Pre-computed call metrics, team performance, and outbound dial funnel"
    },
    {
      "name": "CRM",
      "description": "Manage people, companies, and deals in your CRM."
    },
    {
      "name": "Notes",
      "description": "Internal team notes on conversations and CRM people, with @mention support. Notes are never visible to the contact."
    },
    {
      "name": "Threads",
      "description": "Team discussion threads attached to a conversation item (call, SMS, or conversation note). One thread per item."
    },
    {
      "name": "AI Receptionist",
      "description": "Read and write the AI receptionist configuration of a phone line: business details, voice, prompt, capabilities, business hours, transfer rules, scheduling calendars and knowledge sources."
    },
    {
      "name": "Inboxes",
      "description": "Personal inboxes: saved views of one or more lines, optionally narrowed to phone-menu options, with their own filters and notification setting."
    }
  ],
  "paths": {
    "/v2/api/partner/accounts": {
      "post": {
        "summary": "Create account",
        "description": "Creates an Allo account for one of your customers, provisions a phone number, and returns a scoped API key for the account. Requires the `PARTNER` scope and a Discounted licence (reseller) partner contract. The account gets its own Business plan subscription, billed to you at the chosen `interval` with your partner discount applied. The full period is charged when the account is created, with no proration: Allo draws on your prepaid credit first, then charges your card on file for the rest. Allo never charges your customer. This endpoint is optional: the partner portal (web.withallo.com/partner) creates accounts without code.",
        "operationId": "createPartnerAccount",
        "tags": [
          "Partner"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "name",
                  "interval",
                  "number_preference"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Becomes the account's login.",
                    "example": "client@example.com"
                  },
                  "name": {
                    "type": "string",
                    "example": "Jane Doe"
                  },
                  "interval": {
                    "type": "string",
                    "enum": [
                      "MONTHLY",
                      "YEARLY"
                    ],
                    "description": "Billing interval of the account's own subscription, billed to you.",
                    "example": "MONTHLY"
                  },
                  "personal_mobile": {
                    "type": "string",
                    "nullable": true,
                    "description": "Optional. An existing mobile the new number can attach to.",
                    "example": "+33612345678"
                  },
                  "partner_client_ref": {
                    "type": "string",
                    "description": "Your own reference for this customer. Echoed back and on the activation webhook.",
                    "example": "crm-12345"
                  },
                  "number_preference": {
                    "type": "object",
                    "required": [
                      "country"
                    ],
                    "properties": {
                      "country": {
                        "type": "string",
                        "description": "ISO country code.",
                        "example": "FR"
                      },
                      "prefix": {
                        "type": "string",
                        "nullable": true,
                        "example": "+337",
                        "description": "Optional. Digits the number should start with, after the country code, for example `+337` or `7`."
                      },
                      "esim": {
                        "type": "boolean",
                        "nullable": true,
                        "description": "Optional, default `false`. Set to `true` to get a French mobile number that can carry an eSIM, which you can then order with `POST /v2/api/partner/accounts/{account_id}/esims`. eSIM numbers are only available with `country` set to `FR`, otherwise the request fails with `ESIM_NOT_AVAILABLE_IN_COUNTRY`.",
                        "example": false
                      }
                    }
                  }
                }
              },
              "example": {
                "email": "client@example.com",
                "name": "Jane Doe",
                "interval": "MONTHLY",
                "personal_mobile": "+33612345678",
                "partner_client_ref": "crm-12345",
                "number_preference": {
                  "country": "FR",
                  "prefix": "+337"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "api_key": {
                          "type": "string",
                          "nullable": true,
                          "description": "Scoped API key for the new account, with the scopes CRM_READ, CRM_WRITE, WEBHOOKS_READ_WRITE, CONVERSATIONS_READ, PHONE_NUMBERS_READ, PHONE_NUMBERS_WRITE, AGENTS_READ, AGENTS_WRITE, SUMMARY_TEMPLATES_READ and SUMMARY_TEMPLATES_WRITE (no SMS_SEND). Returned only on create.",
                          "example": "b1c2..."
                        },
                        "phone_numbers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "example": [
                            "+33712345678"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "example": "ACTIVE"
                        },
                        "activated": {
                          "type": "boolean",
                          "description": "True once the customer has signed in on a device.",
                          "example": false
                        },
                        "partner_client_ref": {
                          "type": "string",
                          "nullable": true,
                          "example": "crm-12345"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "api_key": "b1c2...",
                    "phone_numbers": [
                      "+33712345678"
                    ],
                    "status": "ACTIVE",
                    "activated": false,
                    "partner_client_ref": "crm-12345"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: a required field is missing (MISSING_FIELD), or `number_preference.esim` is `true` with a country other than `FR` (ESIM_NOT_AVAILABLE_IN_COUNTRY).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "Billing error, nothing is created. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the first period and your billing account has no card on file. PARTNER_BILLING_FAILED: your card was declined. PARTNER_SUBSCRIPTION_NOT_BILLABLE: you have no billing account Allo can charge.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks the PARTNER scope, your account is not an enabled partner (PARTNER_ACCESS_REQUIRED), or your partner contract cannot create accounts (PARTNER_CONTRACT_CANNOT_PROVISION). Only Discounted licence (reseller) partners can create accounts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "An account already exists (PARTNER_ACCOUNT_ALREADY_EXISTS) or no number is available (NO_NUMBER_AVAILABLE).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/accounts/price": {
      "get": {
        "summary": "Get account price",
        "description": "Returns what Allo will charge you for a new account at the chosen billing interval: the Business plan price in your billing currency, with your partner discount applied. The full amount is charged when the account is created, with no proration. Amounts are in the smallest currency unit (e.g. cents). Requires the `PARTNER` scope and a Discounted licence (reseller) partner contract.",
        "operationId": "getPartnerAccountPrice",
        "tags": [
          "Partner"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "interval",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "MONTHLY",
                "YEARLY"
              ]
            },
            "description": "Billing interval of the account you want to price."
          }
        ],
        "responses": {
          "200": {
            "description": "Price of a new account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "pricing": {
                          "type": "object",
                          "properties": {
                            "product_price": {
                              "type": "integer",
                              "format": "int64",
                              "description": "Price charged when the account is created, partner discount applied, in the smallest currency unit.",
                              "example": 3150
                            },
                            "product_prorated_price": {
                              "type": "integer",
                              "format": "int64",
                              "description": "Same as `product_price`: a partner account is charged in full, with no proration.",
                              "example": 3150
                            },
                            "pay_next_period": {
                              "type": "integer",
                              "format": "int64",
                              "description": "Price of the next renewal. Equals `product_price` when your discount applies beyond the first invoice, otherwise the full plan price.",
                              "example": 3150
                            },
                            "currency_code": {
                              "type": "string",
                              "description": "Lowercase ISO 4217 code of your billing currency.",
                              "example": "eur"
                            },
                            "pay_now": {
                              "type": "integer",
                              "format": "int64",
                              "deprecated": true,
                              "description": "Deprecated. Use `product_prorated_price`.",
                              "example": 3150
                            }
                          }
                        },
                        "interval": {
                          "type": "string",
                          "enum": [
                            "MONTHLY",
                            "YEARLY"
                          ],
                          "example": "MONTHLY"
                        },
                        "is_trial": {
                          "type": "boolean",
                          "description": "Always `false`: a partner account never starts on a trial.",
                          "example": false
                        },
                        "reason": {
                          "type": "string",
                          "enum": [
                            "NEW_SEAT"
                          ],
                          "description": "Always `NEW_SEAT` for a partner account.",
                          "example": "NEW_SEAT"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "pricing": {
                      "product_price": 3150,
                      "product_prorated_price": 3150,
                      "pay_next_period": 3150,
                      "currency_code": "eur",
                      "pay_now": 3150
                    },
                    "interval": "MONTHLY",
                    "is_trial": false,
                    "reason": "NEW_SEAT"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope, your account is not an enabled partner (PARTNER_ACCESS_REQUIRED), or your partner contract cannot create accounts (PARTNER_CONTRACT_CANNOT_PROVISION).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/accounts/{id}": {
      "get": {
        "summary": "Get account",
        "description": "Returns the status and activation state of an account you provisioned, including whether it is suspended. Requires the `PARTNER` scope.",
        "operationId": "getPartnerAccount",
        "tags": [
          "Partner"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned on create."
          }
        ],
        "responses": {
          "200": {
            "description": "Account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "api_key": {
                          "type": "string",
                          "nullable": true,
                          "description": "Scoped API key for the new account, with the scopes CRM_READ, CRM_WRITE, WEBHOOKS_READ_WRITE, CONVERSATIONS_READ, PHONE_NUMBERS_READ, PHONE_NUMBERS_WRITE, AGENTS_READ, AGENTS_WRITE, SUMMARY_TEMPLATES_READ and SUMMARY_TEMPLATES_WRITE (no SMS_SEND). Returned only on create.",
                          "example": "b1c2..."
                        },
                        "phone_numbers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "example": [
                            "+33712345678"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "description": "The account's status: `ACTIVE`, or `SUSPENDED` while the account is suspended with Suspend account.",
                          "example": "ACTIVE"
                        },
                        "activated": {
                          "type": "boolean",
                          "description": "True once the customer has signed in on a device.",
                          "example": false
                        },
                        "partner_client_ref": {
                          "type": "string",
                          "nullable": true,
                          "example": "crm-12345"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Deactivate account",
        "description": "Deactivates an account you provisioned and cancels its subscription, so it is not renewed. The account stays active until the end of the current paid period. Then the account and its members are deleted, and their email and personal mobile can be used to create a new account. An account whose subscription has already ended is deleted right away. Requires the `PARTNER` scope.",
        "operationId": "deletePartnerAccount",
        "tags": [
          "Partner"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Account deactivated"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope, or your partner contract does not allow deactivating this account (PARTNER_CANNOT_DEACTIVATE).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/accounts/{id}/suspend": {
      "post": {
        "summary": "Suspend account",
        "description": "Suspends an account you provisioned, right away. Inbound and outbound calls, outgoing SMS and the AI receptionist stop for every member of the account: each member's status becomes `SUSPENDED`, and their eSIM lines are suspended. The account keeps its numbers, its eSIMs and its history, and its billing does not change. Incoming SMS are stored without any notification. Idempotent: suspending an account that is already suspended changes nothing and sends no second webhook. Allo sends `partner.account.suspended` to your webhook endpoint. Requires the `PARTNER` scope.",
        "operationId": "suspendPartnerAccount",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "The account, with its new status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "phone_numbers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "example": [
                            "+33712345678"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "description": "The account's status: `ACTIVE`, or `SUSPENDED` while the account is suspended with Suspend account.",
                          "example": "ACTIVE"
                        },
                        "activated": {
                          "type": "boolean",
                          "description": "True once the customer has signed in on a device.",
                          "example": false
                        },
                        "partner_client_ref": {
                          "type": "string",
                          "nullable": true,
                          "example": "crm-12345"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "phone_numbers": [
                      "+33712345678"
                    ],
                    "status": "SUSPENDED",
                    "activated": true,
                    "partner_client_ref": "crm-12345"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/accounts/{id}/resume": {
      "post": {
        "summary": "Resume account",
        "description": "Resumes a suspended account: everything the suspension stopped works again, including its eSIM lines. Idempotent: resuming an account that is not suspended changes nothing and sends no webhook. Allo sends `partner.account.resumed` to your webhook endpoint. Requires the `PARTNER` scope.",
        "operationId": "resumePartnerAccount",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "The account, with its new status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "phone_numbers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "example": [
                            "+33712345678"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "description": "The account's status: `ACTIVE`, or `SUSPENDED` while the account is suspended with Suspend account.",
                          "example": "ACTIVE"
                        },
                        "activated": {
                          "type": "boolean",
                          "description": "True once the customer has signed in on a device.",
                          "example": false
                        },
                        "partner_client_ref": {
                          "type": "string",
                          "nullable": true,
                          "example": "crm-12345"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "phone_numbers": [
                      "+33712345678"
                    ],
                    "status": "ACTIVE",
                    "activated": true,
                    "partner_client_ref": "crm-12345"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/accounts/{id}/numbers": {
      "post": {
        "summary": "Add number",
        "description": "Adds a phone number to one of your accounts. The number is billed on the account's subscription, which you pay: Allo draws on your prepaid credit first, then charges your card on file for the rest. When the account already pays for a number slot that no number uses, the new number takes that slot and nothing is charged (`charged: false`). Allo checks that a number is available before charging anything. Requires the `PARTNER` scope.",
        "operationId": "addPartnerAccountNumber",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,100}$"
            },
            "description": "Optional. 8 to 100 letters, digits, `-` or `_`, for example a UUID. Retrying with the same key does not charge you twice.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "country"
                ],
                "properties": {
                  "country": {
                    "type": "string",
                    "description": "ISO country code.",
                    "example": "FR"
                  },
                  "prefix": {
                    "type": "string",
                    "nullable": true,
                    "example": "7",
                    "description": "Optional. Digits the number should start with, after the country code, for example `+337` or `7`."
                  },
                  "esim": {
                    "type": "boolean",
                    "nullable": true,
                    "description": "Optional, default `false`. Set to `true` to get a French mobile number that can carry an eSIM, which you can then order with `POST /v2/api/partner/accounts/{account_id}/esims`. eSIM numbers are only available with `country` set to `FR`, otherwise the request fails with `ESIM_NOT_AVAILABLE_IN_COUNTRY`.",
                    "example": true
                  }
                }
              },
              "example": {
                "country": "FR",
                "prefix": "7",
                "esim": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Number added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "phone_number": {
                          "type": "string",
                          "description": "The number added to the account, in E.164 format.",
                          "example": "+33745805222"
                        },
                        "country": {
                          "type": "string",
                          "description": "The number's country, as Allo names it (`GB` is returned as `UK`).",
                          "example": "FR"
                        },
                        "charged": {
                          "type": "boolean",
                          "description": "`false` when the number took a slot the account already paid for, `true` when a new slot was charged.",
                          "example": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "phone_number": "+33745805222",
                    "country": "FR",
                    "charged": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: MISSING_FIELD (`country`), INVALID_NUMBER_PREFERENCE (unknown country), ESIM_NOT_AVAILABLE_IN_COUNTRY or INVALID_IDEMPOTENCY_KEY.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "Billing error, nothing is created. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. PARTNER_BILLING_FAILED: your card was declined. PARTNER_SUBSCRIPTION_NOT_BILLABLE: the account has no subscription Allo can bill.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Nothing is charged for NO_NUMBER_AVAILABLE (no number matches the country and prefix) or REGULATORY_VERIFICATION_REQUIRED (the country needs the account's regulatory verification first). Also IDEMPOTENCY_KEY_ALREADY_USED (an earlier attempt used this key), PARTNER_ACCOUNT_BUSY (another number or member is being added to the account, `retryable: true`), PARTNER_ACCOUNT_DEACTIVATING (the account is being deactivated) or PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT (the account's subscription cannot be billed right now; retry when `retryable` is `true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "PARTNER_BILLING_UNAVAILABLE: billing is temporarily unavailable, retry with the same Idempotency-Key. PARTNER_NUMBER_SETUP_FAILED: the number could not be set up, and Allo took the charge back. PARTNER_NUMBER_KEPT: the number was assigned but its setup did not complete, and it stays on the account and its billing. Do not retry these two: write to partnership@themobilefirst.co.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/partner/accounts/{id}/numbers/price": {
      "get": {
        "summary": "Get number price",
        "description": "Returns what adding one more number to the account costs today. When the account already pays for a free number slot, `included` is `true` and `amount_due_now` is `0`. Otherwise `amount_due_now` is the charge for the rest of the account's current billing period, net of the subscription's discount, tax included. Requires the `PARTNER` scope.",
        "operationId": "getPartnerAccountNumberPrice",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "Price of one more number",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "included": {
                          "type": "boolean",
                          "description": "`true` when the account already pays for a number slot that no number uses: the next number costs nothing.",
                          "example": false
                        },
                        "unit_amount_before_discount": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The price of one number for a full billing period, before discount, in the smallest currency unit.",
                          "example": 1000
                        },
                        "amount_due_now": {
                          "type": "integer",
                          "format": "int64",
                          "description": "What Allo charges when you add the number: prorated to the end of the current period, net of the subscription's discount, tax included. `0` when `included` is `true`.",
                          "example": 540
                        },
                        "currency": {
                          "type": "string",
                          "description": "Lowercase ISO 4217 code of the account's subscription.",
                          "example": "eur"
                        },
                        "interval": {
                          "type": "string",
                          "enum": [
                            "MONTHLY",
                            "YEARLY"
                          ],
                          "description": "Billing interval of the account's subscription.",
                          "example": "MONTHLY"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "included": false,
                    "unit_amount_before_discount": 1000,
                    "amount_due_now": 540,
                    "currency": "eur",
                    "interval": "MONTHLY"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "The account has no subscription Allo can bill (PARTNER_SUBSCRIPTION_NOT_BILLABLE).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "Billing is temporarily unavailable (PARTNER_BILLING_UNAVAILABLE). Retry in a few seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/partner/accounts/{id}/members": {
      "get": {
        "summary": "List members",
        "description": "Lists the members of one of your accounts, oldest first. The account itself is not in the list. Requires the `PARTNER` scope.",
        "operationId": "listPartnerAccountMembers",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "The account's members",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The member's user id (`usr-*`). Pass it as `holder_id` to Order eSIM to register the member's eSIM to the member.",
                            "example": "usr-8C1B2E7F4A9D3C6B0E5F1A2D7C4B9E3F6A0D8C21"
                          },
                          "account_id": {
                            "type": "string",
                            "description": "The account the member was added to.",
                            "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                          },
                          "email": {
                            "type": "string",
                            "description": "The member's login.",
                            "example": "paul@example.com"
                          },
                          "name": {
                            "type": "string",
                            "example": "Paul Martin"
                          },
                          "role": {
                            "type": "string",
                            "enum": [
                              "ADMIN",
                              "MANAGER",
                              "MEMBER"
                            ],
                            "example": "MEMBER"
                          },
                          "phone_numbers": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "The member's own numbers.",
                            "example": [
                              "+33745805111"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "example": "ACTIVE",
                            "description": "The member's status: `ACTIVE`, or `SUSPENDED` while the account is suspended with Suspend account."
                          },
                          "activated": {
                            "type": "boolean",
                            "description": "True once the member has signed in on a device.",
                            "example": false
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/ApiPagination"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "usr-8C1B2E7F4A9D3C6B0E5F1A2D7C4B9E3F6A0D8C21",
                      "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                      "email": "paul@example.com",
                      "name": "Paul Martin",
                      "role": "MEMBER",
                      "phone_numbers": [
                        "+33745805111"
                      ],
                      "status": "ACTIVE",
                      "activated": false
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 1,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Add member",
        "description": "Adds a member to one of your accounts, with a phone number of their own: a new number from `number_preference`, or a number the account already holds from `phone_number`, which the member takes over with its history. The member takes a seat the account already pays for and no one uses, or one more seat on the account's subscription, which you pay: Allo draws on your prepaid credit first, then charges your card on file for the rest. The seat includes the member's number, so the number is not billed on top. Allo sends the member no invitation email. Allo checks that a number is available before charging anything. Requires the `PARTNER` scope.",
        "operationId": "addPartnerAccountMember",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "name"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Becomes the member's login. It must not belong to an Allo account yet.",
                    "example": "paul@example.com"
                  },
                  "name": {
                    "type": "string",
                    "example": "Paul Martin"
                  },
                  "personal_mobile": {
                    "type": "string",
                    "nullable": true,
                    "description": "Optional, E.164. The member's own mobile. It must not belong to an Allo account yet.",
                    "example": "+33612345679"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "ADMIN",
                      "MANAGER",
                      "MEMBER"
                    ],
                    "nullable": true,
                    "description": "Optional, default `MEMBER`. The member's role in the account's workspace.",
                    "example": "MEMBER"
                  },
                  "number_preference": {
                    "type": "object",
                    "required": [
                      "country"
                    ],
                    "description": "The member's new number. Required unless you send `phone_number`. Do not send both.",
                    "properties": {
                      "country": {
                        "type": "string",
                        "description": "ISO country code.",
                        "example": "FR"
                      },
                      "prefix": {
                        "type": "string",
                        "nullable": true,
                        "example": "7",
                        "description": "Optional. Digits the number should start with, after the country code, for example `+337` or `7`."
                      },
                      "esim": {
                        "type": "boolean",
                        "nullable": true,
                        "description": "Optional, default `false`. Set to `true` to get a French mobile number that can carry an eSIM, which you can then order with `POST /v2/api/partner/accounts/{account_id}/esims`. eSIM numbers are only available with `country` set to `FR`, otherwise the request fails with `ESIM_NOT_AVAILABLE_IN_COUNTRY`.",
                        "example": true
                      }
                    }
                  },
                  "phone_number": {
                    "type": "string",
                    "nullable": true,
                    "description": "A number the account holds itself, for example one kept from a removed member, in E.164 format. The member takes it over, with its call and message history, instead of getting a new number. Send either `phone_number` or `number_preference`, not both. If the number had an eSIM, revoke it first, then order a new eSIM for the member with `holder_id`.",
                    "example": "+33745805111"
                  }
                }
              },
              "example": {
                "email": "paul@example.com",
                "name": "Paul Martin",
                "personal_mobile": "+33612345679",
                "role": "MEMBER",
                "number_preference": {
                  "country": "FR",
                  "esim": true
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Member added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The member's user id (`usr-*`). Pass it as `holder_id` to Order eSIM to register the member's eSIM to the member.",
                          "example": "usr-8C1B2E7F4A9D3C6B0E5F1A2D7C4B9E3F6A0D8C21"
                        },
                        "account_id": {
                          "type": "string",
                          "description": "The account the member was added to.",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "email": {
                          "type": "string",
                          "description": "The member's login.",
                          "example": "paul@example.com"
                        },
                        "name": {
                          "type": "string",
                          "example": "Paul Martin"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "ADMIN",
                            "MANAGER",
                            "MEMBER"
                          ],
                          "example": "MEMBER"
                        },
                        "phone_numbers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The member's own numbers.",
                          "example": [
                            "+33745805111"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "example": "ACTIVE",
                          "description": "The member's status: `ACTIVE`, or `SUSPENDED` while the account is suspended with Suspend account."
                        },
                        "activated": {
                          "type": "boolean",
                          "description": "True once the member has signed in on a device.",
                          "example": false
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "usr-8C1B2E7F4A9D3C6B0E5F1A2D7C4B9E3F6A0D8C21",
                    "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "email": "paul@example.com",
                    "name": "Paul Martin",
                    "role": "MEMBER",
                    "phone_numbers": [
                      "+33745805111"
                    ],
                    "status": "ACTIVE",
                    "activated": false
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: MISSING_FIELD (`email`, `name`, `number_preference` or `number_preference.country`), INVALID_PHONE_NUMBER (`personal_mobile` or `phone_number`), INVALID_MEMBER_ROLE, INVALID_NUMBER_PREFERENCE, ESIM_NOT_AVAILABLE_IN_COUNTRY, or PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT (both `phone_number` and `number_preference` were sent).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "Billing error, nothing is created. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. PARTNER_BILLING_FAILED: your card was declined. PARTNER_SUBSCRIPTION_NOT_BILLABLE: the account has no subscription Allo can bill.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND), or the account does not hold the `phone_number` itself: it is not on the account, or a member holds it (PARTNER_ACCOUNT_NUMBER_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Nothing is charged for PARTNER_ACCOUNT_ALREADY_EXISTS (the email or personal mobile already belongs to an Allo account), NO_NUMBER_AVAILABLE or REGULATORY_VERIFICATION_REQUIRED. Also PARTNER_ACCOUNT_BUSY (another number or member is being added to the account, `retryable: true`), PARTNER_ACCOUNT_DEACTIVATING (the account is being deactivated) or PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT (the account's subscription cannot be billed right now; retry when `retryable` is `true`). PARTNER_NUMBER_HAS_LIVE_ESIM: the `phone_number` still has an eSIM that is not revoked; revoke it with `POST /v2/api/partner/esims/{id}/revoke` first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "PARTNER_BILLING_UNAVAILABLE: billing is temporarily unavailable, retry in a few seconds. PARTNER_NUMBER_SETUP_FAILED: the member's number could not be set up, and the member and the charge were removed. PARTNER_NUMBER_KEPT: the number was assigned but its setup did not complete, and it stays on the account with the member's seat. Do not retry these two: write to partnership@themobilefirst.co.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/partner/accounts/{id}/members/{member_id}": {
      "delete": {
        "summary": "Remove member",
        "description": "Removes a member from one of your accounts. Allo revokes the member's eSIMs first, so their phone stops ringing right away, then removes the member from the account's workspace. The member's numbers stay on the account, with their history. The seat stays paid until the end of the current billing period, and from the next invoice the account's subscription bills the kept numbers as extra numbers, with no proration. Requires the `PARTNER` scope.",
        "operationId": "removePartnerAccountMember",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          },
          {
            "name": "member_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The member's `id` (`usr-*`), from Add member or List members."
          }
        ],
        "responses": {
          "204": {
            "description": "Member removed"
          },
          "400": {
            "description": "The `member_id` is the account itself, which is not a member (PARTNER_ACCOUNT_OWNER_NOT_REMOVABLE). To end the account, use `DELETE /v2/api/partner/accounts/{id}`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND), or no member with this id is in the account's workspace (PARTNER_ACCOUNT_MEMBER_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "One of the member's eSIMs is being moved between the network and the eSIM right now (PARTNER_ESIM_MOVE_IN_PROGRESS), or another member or number is being changed on this account (PARTNER_ACCOUNT_BUSY). Both are `retryable: true`: retry in a few minutes for the first, a few seconds for the second.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/accounts/{account_id}/esims/offer": {
      "get": {
        "summary": "Get eSIM offer",
        "description": "Returns the eSIM setup fee, the data tiers you can order and the data top-ups you can buy for an account you provisioned, priced on the subscription you pay for that account: its currency, its billing interval and your partner discount. Amounts are in the smallest currency unit (e.g. cents). Requires the `PARTNER` scope.",
        "operationId": "getPartnerEsimOffer",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "eSIM offer for the account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "description": "Currency of the subscription you pay for the account.",
                          "example": "eur"
                        },
                        "interval": {
                          "type": "string",
                          "enum": [
                            "MONTHLY",
                            "YEARLY"
                          ],
                          "description": "Billing interval of the tiers, the same as the account's subscription.",
                          "example": "MONTHLY"
                        },
                        "setup_price_cents": {
                          "type": "integer",
                          "format": "int64",
                          "description": "One-off setup fee per eSIM, charged with the first tier period.",
                          "example": 1234
                        },
                        "tiers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string",
                                "description": "Pass it as `tier` when you order or change the tier.",
                                "example": "ESIM_20GB"
                              },
                              "data_mb": {
                                "type": "integer",
                                "format": "int64",
                                "description": "Mobile data included in the tier, in MB (1 GB = 1024 MB).",
                                "example": 20480
                              },
                              "price_cents": {
                                "type": "integer",
                                "format": "int64",
                                "description": "Price of the tier per billing interval.",
                                "example": 3456
                              }
                            }
                          }
                        },
                        "top_ups": {
                          "type": "array",
                          "description": "Data top-ups you can buy for an eSIM of this account. A top-up is charged once and adds data for the current calendar month (Paris time) only.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string",
                                "enum": [
                                  "TOPUP_5GB",
                                  "TOPUP_10GB",
                                  "TOPUP_20GB"
                                ],
                                "description": "Pass it as `code` when you buy a top-up.",
                                "example": "TOPUP_5GB"
                              },
                              "data_mb": {
                                "type": "integer",
                                "format": "int64",
                                "description": "Mobile data the top-up adds, in MB (1 GB = 1024 MB).",
                                "example": 5120
                              },
                              "price_cents": {
                                "type": "integer",
                                "format": "int64",
                                "description": "One-off price of the top-up, before tax.",
                                "example": 567
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "currency": "eur",
                    "interval": "MONTHLY",
                    "setup_price_cents": 1234,
                    "tiers": [
                      {
                        "code": "ESIM_5GB",
                        "data_mb": 5120,
                        "price_cents": 2345
                      },
                      {
                        "code": "ESIM_20GB",
                        "data_mb": 20480,
                        "price_cents": 3456
                      }
                    ],
                    "top_ups": [
                      {
                        "code": "TOPUP_5GB",
                        "data_mb": 5120,
                        "price_cents": 567
                      },
                      {
                        "code": "TOPUP_10GB",
                        "data_mb": 10240,
                        "price_cents": 890
                      },
                      {
                        "code": "TOPUP_20GB",
                        "data_mb": 20480,
                        "price_cents": 1234
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "eSIMs cannot be ordered for this account right now (ESIM_UNAVAILABLE).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/partner/accounts/{account_id}/esims": {
      "post": {
        "summary": "Order eSIM",
        "description": "Orders an eSIM for one of the account's numbers. The setup fee and the first period of the tier are charged on the subscription you pay for the account: Allo draws on your prepaid credit first, then charges your card on file for the rest. The eSIM is returned with status `PROVISIONING` and is usually ready 5 to 15 minutes later: Allo then sends the `partner.esim.ready` webhook. A number whose eSIM was revoked can get a new eSIM: the order charges the setup fee again. A card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED`. Requires the `PARTNER` scope.",
        "operationId": "orderPartnerEsim",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,100}$"
            },
            "description": "Optional. 8 to 100 letters, digits, `-` or `_`, for example a UUID. Retrying with the same key does not charge you twice.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone_number",
                  "tier",
                  "identity"
                ],
                "properties": {
                  "phone_number": {
                    "type": "string",
                    "description": "One of the account's numbers that can carry an eSIM: created, added or given to a member with `number_preference.esim` set to `true`.",
                    "example": "+33745805999"
                  },
                  "tier": {
                    "type": "string",
                    "description": "A tier `code` from Get eSIM offer.",
                    "example": "ESIM_20GB"
                  },
                  "holder_id": {
                    "type": "string",
                    "nullable": true,
                    "description": "Optional. The Allo user the eSIM is registered to: the account itself by default, or the `id` of a member returned by Add member for the member's own number, including a number the member took over with `phone_number`.",
                    "example": null
                  },
                  "identity": {
                    "type": "object",
                    "description": "The business the line is registered to.",
                    "required": [
                      "corporate_name",
                      "postal_address",
                      "postal_code",
                      "city"
                    ],
                    "properties": {
                      "corporate_name": {
                        "type": "string",
                        "example": "Plomberie Martin"
                      },
                      "postal_address": {
                        "type": "string",
                        "example": "12 rue de la Paix"
                      },
                      "postal_code": {
                        "type": "string",
                        "description": "5 digits.",
                        "example": "75001"
                      },
                      "city": {
                        "type": "string",
                        "example": "Paris"
                      },
                      "first_name": {
                        "type": "string",
                        "nullable": true,
                        "example": "Jean"
                      },
                      "last_name": {
                        "type": "string",
                        "nullable": true,
                        "example": "Martin"
                      },
                      "company_name": {
                        "type": "string",
                        "nullable": true,
                        "example": "Plomberie Martin"
                      },
                      "siret": {
                        "type": "string",
                        "nullable": true,
                        "example": "12345678900012"
                      },
                      "naf": {
                        "type": "string",
                        "nullable": true,
                        "example": "4322A"
                      },
                      "email": {
                        "type": "string",
                        "nullable": true,
                        "example": "jean@plomberie-martin.fr"
                      }
                    }
                  }
                }
              },
              "example": {
                "phone_number": "+33745805999",
                "tier": "ESIM_20GB",
                "identity": {
                  "corporate_name": "Plomberie Martin",
                  "postal_address": "12 rue de la Paix",
                  "postal_code": "75001",
                  "city": "Paris",
                  "first_name": "Jean",
                  "last_name": "Martin",
                  "email": "jean@plomberie-martin.fr"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "eSIM ordered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The eSIM id (`eso-*`).",
                          "example": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61"
                        },
                        "account_id": {
                          "type": "string",
                          "description": "The account the eSIM was ordered for.",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "partner_client_ref": {
                          "type": "string",
                          "nullable": true,
                          "description": "Your own reference, set when the account was created.",
                          "example": "crm-12345"
                        },
                        "phone_number": {
                          "type": "string",
                          "description": "The number the eSIM carries.",
                          "example": "+33745805999"
                        },
                        "tier": {
                          "type": "string",
                          "description": "The tier code that was ordered.",
                          "example": "ESIM_20GB"
                        },
                        "scheduled_tier": {
                          "type": "string",
                          "nullable": true,
                          "description": "The tier a scheduled downgrade will switch the eSIM to. Always `null` on a new order.",
                          "example": null
                        },
                        "scheduled_tier_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "When the scheduled downgrade applies. Always `null` on a new order.",
                          "example": null
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "PROVISIONING",
                            "ACTIVE",
                            "FAILED",
                            "REVOKED"
                          ],
                          "description": "`PROVISIONING`: ordered, not ready yet. `ACTIVE`: ready, calls to the number ring the eSIM. `FAILED`: the order did not complete, see `failure_code`. `REVOKED`: the eSIM was revoked, or replaced by a later eSIM on the same number, and no longer works.",
                          "example": "PROVISIONING"
                        },
                        "failure_code": {
                          "type": "string",
                          "nullable": true,
                          "description": "Why the order failed. Set only when `status` is `FAILED`.",
                          "example": null
                        },
                        "data": {
                          "type": "object",
                          "nullable": true,
                          "description": "Mobile data use this month. Always `null` here, since a new eSIM is not `ACTIVE` yet: read it with Get eSIM once the eSIM is ready.",
                          "example": null
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the eSIM was ordered.",
                          "example": "2026-10-14T10:05:00"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                    "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "partner_client_ref": "crm-12345",
                    "phone_number": "+33745805999",
                    "tier": "ESIM_20GB",
                    "scheduled_tier": null,
                    "scheduled_tier_at": null,
                    "status": "PROVISIONING",
                    "failure_code": null,
                    "data": null,
                    "created_at": "2026-10-14T10:05:00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: MISSING_FIELD, INVALID_ESIM_TIER, ESIM_IDENTITY_INCOMPLETE or INVALID_IDEMPOTENCY_KEY.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the order and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The account was not provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND), the number does not belong to the account (PARTNER_ESIM_NUMBER_NOT_FOUND), or `holder_id` cannot hold an eSIM for this number (PARTNER_ESIM_HOLDER_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The number cannot carry an eSIM (ESIM_NOT_ELIGIBLE), already has an eSIM that is not revoked (ESIM_ALREADY_EXISTS), has an order in progress (ESIM_ORDER_IN_PROGRESS) or one handled by Allo support (ESIM_ORDER_NEEDS_SUPPORT), or the subscription you pay for the account cannot take an eSIM right now (ESIM_SUBSCRIPTION_CONFLICT).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "eSIMs cannot be ordered for this account right now (ESIM_UNAVAILABLE).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/partner/esims/{id}": {
      "get": {
        "summary": "Get eSIM",
        "description": "Returns the status of an eSIM you ordered, its current tier and, once it is `ACTIVE`, its mobile data use this month. Use it to poll for readiness if you do not receive webhooks. Requires the `PARTNER` scope.",
        "operationId": "getPartnerEsim",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The eSIM id returned by Order eSIM (`eso-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "eSIM",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The eSIM id (`eso-*`).",
                          "example": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61"
                        },
                        "account_id": {
                          "type": "string",
                          "description": "The account the eSIM was ordered for.",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "partner_client_ref": {
                          "type": "string",
                          "nullable": true,
                          "description": "Your own reference, set when the account was created.",
                          "example": "crm-12345"
                        },
                        "phone_number": {
                          "type": "string",
                          "description": "The number the eSIM carries.",
                          "example": "+33745805999"
                        },
                        "tier": {
                          "type": "string",
                          "description": "The eSIM's current tier code. It changes when an upgrade is paid or a scheduled downgrade applies.",
                          "example": "ESIM_20GB"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "PROVISIONING",
                            "ACTIVE",
                            "FAILED",
                            "REVOKED"
                          ],
                          "description": "`PROVISIONING`: ordered, not ready yet. `ACTIVE`: ready, calls to the number ring the eSIM. `FAILED`: the order did not complete, see `failure_code`. `REVOKED`: the eSIM was revoked, or replaced by a later eSIM on the same number, and no longer works.",
                          "example": "PROVISIONING"
                        },
                        "failure_code": {
                          "type": "string",
                          "nullable": true,
                          "description": "Why the order failed. Set only when `status` is `FAILED`.",
                          "example": null
                        },
                        "data": {
                          "type": "object",
                          "nullable": true,
                          "description": "Mobile data use for the current cycle, the calendar month in Paris time. `null` unless `status` is `ACTIVE`. Read live from the network on each call: it can lag real use by a few minutes.",
                          "properties": {
                            "used_mb": {
                              "type": "integer",
                              "format": "int64",
                              "description": "Mobile data used this month, in MB. `null` when the network has not reported it yet.",
                              "example": 3172,
                              "nullable": true
                            },
                            "allowance_mb": {
                              "type": "integer",
                              "format": "int64",
                              "description": "Mobile data the eSIM can use this month, in MB: the tier's data plus the top-ups bought this month.",
                              "example": 25600
                            },
                            "remaining_mb": {
                              "type": "integer",
                              "format": "int64",
                              "description": "`allowance_mb` minus `used_mb`, in MB. `null` when `used_mb` is `null`.",
                              "example": 22428,
                              "nullable": true
                            },
                            "cycle_started_at": {
                              "type": "string",
                              "format": "date-time",
                              "description": "Start of the current cycle, in UTC: midnight on the 1st of the month in Paris time.",
                              "example": "2026-10-31T23:00:00"
                            },
                            "cycle_ends_at": {
                              "type": "string",
                              "format": "date-time",
                              "description": "End of the current cycle, in UTC: midnight on the 1st of the next month in Paris time.",
                              "example": "2026-11-30T23:00:00"
                            }
                          }
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the eSIM was ordered.",
                          "example": "2026-10-14T10:05:00"
                        },
                        "scheduled_tier": {
                          "type": "string",
                          "nullable": true,
                          "description": "The tier a scheduled downgrade will switch the eSIM to. `null` when no downgrade is scheduled.",
                          "example": null
                        },
                        "scheduled_tier_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "When the scheduled downgrade applies: the end of the period already paid. `null` when no downgrade is scheduled.",
                          "example": null
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                    "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "partner_client_ref": "crm-12345",
                    "phone_number": "+33745805999",
                    "tier": "ESIM_20GB",
                    "scheduled_tier": null,
                    "scheduled_tier_at": null,
                    "status": "ACTIVE",
                    "failure_code": null,
                    "data": {
                      "used_mb": 3172,
                      "allowance_mb": 25600,
                      "remaining_mb": 22428,
                      "cycle_started_at": "2026-10-31T23:00:00",
                      "cycle_ends_at": "2026-11-30T23:00:00"
                    },
                    "created_at": "2026-10-14T10:05:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/esims/{id}/revoke": {
      "post": {
        "summary": "Revoke eSIM",
        "description": "Revokes an eSIM right away: it stops working on its phone for good. The number stays on the account, keeps its history and rings the Allo apps instead. The eSIM's data tier ends now. To put the number on a phone again, order a new eSIM for it, which charges the setup fee. Idempotent: revoking an eSIM that is already `REVOKED` returns it unchanged. Requires the `PARTNER` scope.",
        "operationId": "revokePartnerEsim",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The eSIM id returned by Order eSIM (`eso-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "The revoked eSIM, with status `REVOKED`",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The eSIM id (`eso-*`).",
                          "example": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61"
                        },
                        "account_id": {
                          "type": "string",
                          "description": "The account the eSIM was ordered for.",
                          "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
                        },
                        "partner_client_ref": {
                          "type": "string",
                          "nullable": true,
                          "description": "Your own reference, set when the account was created.",
                          "example": "crm-12345"
                        },
                        "phone_number": {
                          "type": "string",
                          "description": "The number the eSIM carries.",
                          "example": "+33745805999"
                        },
                        "tier": {
                          "type": "string",
                          "description": "The tier code that was ordered.",
                          "example": "ESIM_20GB"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "PROVISIONING",
                            "ACTIVE",
                            "FAILED",
                            "REVOKED"
                          ],
                          "description": "`PROVISIONING`: ordered, not ready yet. `ACTIVE`: ready, calls to the number ring the eSIM. `FAILED`: the order did not complete, see `failure_code`. `REVOKED`: the eSIM was revoked, or replaced by a later eSIM on the same number, and no longer works.",
                          "example": "PROVISIONING"
                        },
                        "failure_code": {
                          "type": "string",
                          "nullable": true,
                          "description": "Why the order failed. Set only when `status` is `FAILED`.",
                          "example": null
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the eSIM was ordered.",
                          "example": "2026-10-14T10:05:00"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                    "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "partner_client_ref": "crm-12345",
                    "phone_number": "+33745805999",
                    "tier": "ESIM_20GB",
                    "status": "REVOKED",
                    "failure_code": null,
                    "created_at": "2026-10-14T10:05:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The eSIM is not live: it is still provisioning, it failed, or it is being moved between the network and the eSIM (PARTNER_ESIM_NOT_REVOCABLE). Only an `ACTIVE` eSIM can be revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/esims/{id}/activation_code": {
      "get": {
        "summary": "Get eSIM activation code",
        "description": "Returns the activation code of a ready eSIM: the LPA string, the SM-DP+ address, the matching id and a QR code. Before the eSIM is ready, the request fails with `ESIM_NOT_READY`. Requires the `PARTNER` scope.",
        "operationId": "getPartnerEsimActivationCode",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The eSIM id returned by Order eSIM (`eso-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "Activation code",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "lpa": {
                          "type": "string",
                          "description": "Full activation code, `LPA:1$<smdp_address>$<matching_id>`.",
                          "example": "LPA:1$smdp.example.com$ABCD-1234-EFGH-5678"
                        },
                        "smdp_address": {
                          "type": "string",
                          "description": "SM-DP+ address, for manual entry on Android.",
                          "example": "smdp.example.com"
                        },
                        "matching_id": {
                          "type": "string",
                          "description": "Matching id (activation code), for manual entry on Android.",
                          "example": "ABCD-1234-EFGH-5678"
                        },
                        "qr_code": {
                          "type": "string",
                          "description": "PNG data URI of a QR code that encodes `lpa`.",
                          "example": "data:image/png;base64,iVBORw0KGgo..."
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "lpa": "LPA:1$smdp.example.com$ABCD-1234-EFGH-5678",
                    "smdp_address": "smdp.example.com",
                    "matching_id": "ABCD-1234-EFGH-5678",
                    "qr_code": "data:image/png;base64,iVBORw0KGgo..."
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The eSIM is not ready to install yet (ESIM_NOT_READY). Wait for the `partner.esim.ready` webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "The activation code cannot be read right now (ESIM_UNAVAILABLE).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/partner/accounts/{account_id}/sender_ids": {
      "get": {
        "summary": "List sender IDs",
        "description": "Lists the sender IDs declared on one of your accounts, with their review status. Requires the `PARTNER` scope.",
        "operationId": "listPartnerSenderIds",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "The account's sender IDs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PartnerSenderId"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/ApiPagination"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                      "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                      "partner_client_ref": "crm-12345",
                      "sender_id": "PLOMBMARTIN",
                      "status": "PENDING",
                      "example_content": "Bonjour, votre intervention est confirmée demain à 9h. Plomberie Martin",
                      "created_at": "2026-11-16T10:05:00"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 1,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Declare sender ID",
        "description": "Declares an alphanumeric sender ID on one of your accounts, so the account can send SMS under that name. The sender ID is created with status `PENDING` and Allo reviews it by hand, usually in 1 to 5 business days. Allo then sends the `partner.sender_id.validated` or `partner.sender_id.failed` webhook. A sender ID belongs to one Allo account only, and an account holds at most 3. Sending the same `sender_id` again for the same account returns the existing one. Requires the `PARTNER` scope.",
        "operationId": "createPartnerSenderId",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePartnerSenderIdRequest"
              },
              "example": {
                "sender_id": "PLOMBMARTIN",
                "example_content": "Bonjour, votre intervention est confirmée demain à 9h. Plomberie Martin"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sender ID declared, waiting for Allo's review",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PartnerSenderId"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                    "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "partner_client_ref": "crm-12345",
                    "sender_id": "PLOMBMARTIN",
                    "status": "PENDING",
                    "example_content": "Bonjour, votre intervention est confirmée demain à 9h. Plomberie Martin",
                    "created_at": "2026-11-16T10:05:00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: MISSING_FIELD (`sender_id`), SENDER_ID_INVALID_FORMAT (`sender_id` is not 1 to 11 letters or digits) or EXAMPLE_CONTENT_TOO_LONG (`example_content` is longer than 1000 characters).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The sender ID already belongs to another Allo account (SENDER_ID_ALREADY_EXISTS), or the account already has 3 sender IDs (MAX_SENDER_IDS_REACHED).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/accounts/{account_id}/sender_ids/{id}": {
      "get": {
        "summary": "Get sender ID",
        "description": "Returns a sender ID declared on one of your accounts, with its review status. Use it to poll the status if you do not receive webhooks, and to see whether Allo disabled it. Requires the `PARTNER` scope.",
        "operationId": "getPartnerSenderId",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account id returned by Create account (`usr-*`)."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sender ID's id returned by Declare sender ID (`vsi-*`)."
          }
        ],
        "responses": {
          "200": {
            "description": "Sender ID",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PartnerSenderId"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                    "account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
                    "partner_client_ref": "crm-12345",
                    "sender_id": "PLOMBMARTIN",
                    "status": "VALIDATED",
                    "example_content": "Bonjour, votre intervention est confirmée demain à 9h. Plomberie Martin",
                    "created_at": "2026-11-16T10:05:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The account was not provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND), or no sender ID with this id is declared on the account (PARTNER_SENDER_ID_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/credit": {
      "get": {
        "summary": "Get prepaid credit",
        "description": "Returns the prepaid credit you have left and your recent top-ups. Allo pays what you buy through the Partner API from this credit first, then charges your card on file for the rest. Without enough credit and without a card, a request that charges fails with `402 PARTNER_CREDIT_INSUFFICIENT` and nothing is created. Requires the `PARTNER` scope and a Discounted licence (reseller) partner contract.",
        "operationId": "getPartnerCredit",
        "tags": [
          "Partner"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Your prepaid credit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "balance_cents": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Credit left, in the smallest unit of `currency`. `0` before your first top-up.",
                          "example": 120000
                        },
                        "currency": {
                          "type": "string",
                          "description": "Lowercase ISO 4217 code of your billing account. Omitted before your first top-up.",
                          "example": "eur"
                        },
                        "prepaid": {
                          "type": "boolean",
                          "description": "`true` once at least one top-up was added to your credit.",
                          "example": true
                        },
                        "last_top_up": {
                          "type": "object",
                          "description": "Your most recent top-up. Omitted when there is none.",
                          "properties": {
                            "amount_cents": {
                              "type": "integer",
                              "format": "int64",
                              "example": 150000
                            },
                            "currency": {
                              "type": "string",
                              "example": "eur"
                            },
                            "at": {
                              "type": "string",
                              "format": "date-time",
                              "example": "2026-10-01T09:12:44Z"
                            }
                          }
                        },
                        "top_ups": {
                          "type": "array",
                          "description": "Your 20 most recent top-ups, newest first.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "amount_cents": {
                                "type": "integer",
                                "format": "int64",
                                "description": "Amount added to your credit, excluding tax.",
                                "example": 150000
                              },
                              "currency": {
                                "type": "string",
                                "example": "eur"
                              },
                              "invoice_id": {
                                "type": "string",
                                "description": "The invoice the top-up was paid with.",
                                "example": "in_1Q2w3E4r5T6y7U8i"
                              },
                              "at": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2026-10-01T09:12:44Z"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "balance_cents": 120000,
                    "currency": "eur",
                    "prepaid": true,
                    "last_top_up": {
                      "amount_cents": 150000,
                      "currency": "eur",
                      "at": "2026-10-01T09:12:44Z"
                    },
                    "top_ups": [
                      {
                        "amount_cents": 150000,
                        "currency": "eur",
                        "invoice_id": "in_1Q2w3E4r5T6y7U8i",
                        "at": "2026-10-01T09:12:44Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the PARTNER scope, your account is not an enabled partner (PARTNER_ACCESS_REQUIRED), or your partner contract cannot create accounts (PARTNER_CONTRACT_CANNOT_PROVISION).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/default_summary_template": {
      "put": {
        "summary": "Set number default summary template",
        "description": "Sets or clears the default summary template used for a phone number's call summaries. Pass `summary_template_id` to set it, or null/omit to clear it.",
        "operationId": "setNumberDefaultSummaryTemplate",
        "tags": [
          "Summary Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "summary_template_id": {
                    "type": "string",
                    "nullable": true,
                    "description": "Summary template ID (`tst-*`) to set as the default, or null to clear.",
                    "example": "tst-abc123"
                  }
                }
              },
              "example": {
                "summary_template_id": "tst-abc123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default summary template updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "number": {
                          "type": "string",
                          "example": "+14155551234"
                        },
                        "default_summary_template_id": {
                          "type": "string",
                          "nullable": true,
                          "example": "tst-abc123"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "number": "+14155551234",
                    "default_summary_template_id": "tst-abc123"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/call_flow": {
      "get": {
        "summary": "Get call flow",
        "description": "Returns the call flow for a phone number. By default returns the published flow (or an in-memory synthesis of the legacy IVR if none is published); pass `?status=draft` to return the working draft instead.",
        "operationId": "getCallFlow",
        "tags": [
          "Phone Numbers"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Pass `draft` to fetch the working draft instead of the published flow.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "published"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The call flow",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallFlow"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/call_flow/draft": {
      "get": {
        "summary": "Get call flow draft",
        "description": "Returns the working draft of a phone number's call flow. Unlike `GET /v2/api/numbers/{number}/call_flow?status=draft`, this endpoint does NOT fall back to the published flow when no draft exists — it returns `404 CALL_FLOW_DRAFT_NOT_FOUND`. Use it to read a draft's `lock_version` without risk of accidentally holding the published version's lock.",
        "operationId": "getCallFlowDraft",
        "tags": [
          "Phone Numbers"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The working draft",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallFlow"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "put": {
        "summary": "Save call flow draft",
        "description": "Creates or updates the working draft of a phone number's call flow. The draft is validated leniently and is not live until published. Optimistic concurrency: pass the `lock_version` returned by a previous read to detect a concurrent edit, and `base_published_version` to detect a publish that happened mid-edit.",
        "operationId": "saveCallFlowDraft",
        "tags": [
          "Phone Numbers"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "definition",
                  "schema_version"
                ],
                "properties": {
                  "definition": {
                    "type": "object",
                    "description": "The call flow tree document (opaque; camelCase keys).",
                    "additionalProperties": true
                  },
                  "schema_version": {
                    "type": "integer",
                    "description": "Must match the server's current call flow schema version.",
                    "example": 1
                  },
                  "lock_version": {
                    "type": "integer",
                    "nullable": true,
                    "description": "The `lock_version` of the draft you are updating; omit or null to upsert without a concurrency check."
                  },
                  "base_published_version": {
                    "type": "integer",
                    "nullable": true,
                    "description": "The published version your edit is based on; a mismatch means someone published mid-edit (409)."
                  },
                  "engine_subset": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "NESTED_IVR",
                      "FULL_FLOW"
                    ],
                    "description": "`FULL_FLOW` runs the whole tree on live calls. `NESTED_IVR` runs only the root phone menu: its keys that lead to a nested menu, a condition or a voicemail node do nothing. Send `FULL_FLOW` for flows you build through the API. When omitted, it is inferred from the nodes: `FULL_FLOW` only if the flow has a business-hours, contact-property, country-code or send-SMS node, otherwise `NESTED_IVR`. A line whose flow is already `FULL_FLOW` keeps it."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved draft",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallFlow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/call_flow/publish": {
      "post": {
        "summary": "Publish call flow",
        "description": "Publishes the working draft, making it the live call flow for the phone number. This changes live inbound routing immediately. Runs full validation, which is stricter than the lenient validation a draft save runs, so a draft that saved successfully can still fail to publish; the whole publish rolls back if validation fails. Publishing consumes the draft, so the line is left with no draft afterwards.",
        "operationId": "publishCallFlow",
        "tags": [
          "Phone Numbers"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lock_version"
                ],
                "properties": {
                  "lock_version": {
                    "type": "integer",
                    "description": "The `lock_version` of the draft you are publishing.",
                    "example": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The published call flow",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallFlow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/summary_templates": {
      "get": {
        "summary": "List summary templates",
        "description": "Returns the team's call summary templates.",
        "operationId": "listSummaryTemplates",
        "tags": [
          "Summary Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of summary templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SummaryTemplate"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "tst-abc123",
                      "name": "Sales call",
                      "call_context": "B2B SaaS sales calls",
                      "icon": "📞",
                      "sections": [
                        {
                          "title": "Pain points",
                          "instructions": "List the prospect's pain points",
                          "order": 0
                        },
                        {
                          "title": "Next steps",
                          "instructions": "What was agreed",
                          "order": 1
                        }
                      ],
                      "created_at": "2026-06-01T10:00:00",
                      "updated_at": "2026-06-01T10:00:00"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create summary template",
        "description": "Creates a call summary template for the team.",
        "operationId": "createSummaryTemplate",
        "tags": [
          "Summary Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Template name.",
                    "example": "Sales call"
                  },
                  "call_context": {
                    "type": "string",
                    "nullable": true,
                    "description": "Background context that helps the AI summarize calls (max 4000 characters).",
                    "example": "B2B SaaS sales calls"
                  },
                  "icon": {
                    "type": "string",
                    "nullable": true,
                    "description": "Optional icon (e.g. an emoji).",
                    "example": "📞"
                  },
                  "sections": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "$ref": "#/components/schemas/SummaryTemplateSection"
                    },
                    "description": "Ordered sections that make up the summary (max 10)."
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Sales call",
                "call_context": "B2B SaaS sales calls",
                "icon": "📞",
                "sections": [
                  {
                    "title": "Pain points",
                    "instructions": "List the prospect's pain points",
                    "order": 0
                  },
                  {
                    "title": "Next steps",
                    "instructions": "What was agreed",
                    "order": 1
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Summary template created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SummaryTemplate"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "tst-abc123",
                    "name": "Sales call",
                    "call_context": "B2B SaaS sales calls",
                    "icon": "📞",
                    "sections": [
                      {
                        "title": "Pain points",
                        "instructions": "List the prospect's pain points",
                        "order": 0
                      },
                      {
                        "title": "Next steps",
                        "instructions": "What was agreed",
                        "order": 1
                      }
                    ],
                    "created_at": "2026-06-01T10:00:00",
                    "updated_at": "2026-06-01T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/summary_templates/{id}": {
      "get": {
        "summary": "Get summary template",
        "description": "Returns a single call summary template by ID.",
        "operationId": "getSummaryTemplate",
        "tags": [
          "Summary Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Summary template ID (`tst-*`)",
            "schema": {
              "type": "string",
              "example": "tst-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Summary template",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SummaryTemplate"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "tst-abc123",
                    "name": "Sales call",
                    "call_context": "B2B SaaS sales calls",
                    "icon": "📞",
                    "sections": [
                      {
                        "title": "Pain points",
                        "instructions": "List the prospect's pain points",
                        "order": 0
                      },
                      {
                        "title": "Next steps",
                        "instructions": "What was agreed",
                        "order": 1
                      }
                    ],
                    "created_at": "2026-06-01T10:00:00",
                    "updated_at": "2026-06-01T10:00:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "put": {
        "summary": "Update summary template",
        "description": "Replaces a summary template's name, call context, icon, and sections.",
        "operationId": "updateSummaryTemplate",
        "tags": [
          "Summary Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Summary template ID (`tst-*`)",
            "schema": {
              "type": "string",
              "example": "tst-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Template name.",
                    "example": "Sales call"
                  },
                  "call_context": {
                    "type": "string",
                    "nullable": true,
                    "description": "Background context that helps the AI summarize calls (max 4000 characters).",
                    "example": "B2B SaaS sales calls"
                  },
                  "icon": {
                    "type": "string",
                    "nullable": true,
                    "description": "Optional icon (e.g. an emoji).",
                    "example": "📞"
                  },
                  "sections": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "$ref": "#/components/schemas/SummaryTemplateSection"
                    },
                    "description": "Ordered sections that make up the summary (max 10)."
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Sales call",
                "call_context": "B2B SaaS sales calls",
                "icon": "📞",
                "sections": [
                  {
                    "title": "Pain points",
                    "instructions": "List the prospect's pain points",
                    "order": 0
                  },
                  {
                    "title": "Next steps",
                    "instructions": "What was agreed",
                    "order": 1
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Summary template updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SummaryTemplate"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "tst-abc123",
                    "name": "Sales call",
                    "call_context": "B2B SaaS sales calls",
                    "icon": "📞",
                    "sections": [
                      {
                        "title": "Pain points",
                        "instructions": "List the prospect's pain points",
                        "order": 0
                      },
                      {
                        "title": "Next steps",
                        "instructions": "What was agreed",
                        "order": 1
                      }
                    ],
                    "created_at": "2026-06-01T10:00:00",
                    "updated_at": "2026-06-01T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete summary template",
        "description": "Soft-deletes (deactivates) a summary template.",
        "operationId": "deleteSummaryTemplate",
        "tags": [
          "Summary Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Summary template ID (`tst-*`)",
            "schema": {
              "type": "string",
              "example": "tst-abc123"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Summary template deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/webhooks": {
      "get": {
        "summary": "List webhooks",
        "description": "Returns all webhook endpoints configured for your account.",
        "operationId": "listWebhooks",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of webhook endpoints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookApiResponse"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "ep_2NfDKEm9sF8xK3pQr1Zt",
                      "url": "https://example.com/webhooks/allo",
                      "topics": [
                        "call.received",
                        "sms.received"
                      ],
                      "description": "Production event stream",
                      "enabled": true,
                      "created_at": "2026-04-21T14:30:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create webhook",
        "description": "Creates a webhook endpoint subscribed to one or more event topics. The `signing_secret` is returned only in this response — store it to verify delivery signatures.",
        "operationId": "createWebhook",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookApiRequest"
              },
              "example": {
                "url": "https://example.com/webhooks/allo",
                "topics": [
                  "call.received",
                  "sms.received"
                ],
                "description": "Production event stream"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookApiResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "ep_2NfDKEm9sF8xK3pQr1Zt",
                    "url": "https://example.com/webhooks/allo",
                    "topics": [
                      "call.received",
                      "sms.received"
                    ],
                    "description": "Production event stream",
                    "enabled": true,
                    "signing_secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD",
                    "created_at": "2026-04-21T14:30:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/webhooks/{webhook_id}": {
      "get": {
        "summary": "Get webhook",
        "description": "Returns a single webhook endpoint by ID, including its `signing_secret`.",
        "operationId": "getWebhook",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "webhook_id",
            "in": "path",
            "required": true,
            "description": "The webhook endpoint ID (e.g. \"ep_2NfDKEm9sF8xK3pQr1Zt\").",
            "schema": {
              "type": "string",
              "example": "ep_2NfDKEm9sF8xK3pQr1Zt"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookApiResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "ep_2NfDKEm9sF8xK3pQr1Zt",
                    "url": "https://example.com/webhooks/allo",
                    "topics": [
                      "call.received",
                      "sms.received"
                    ],
                    "description": "Production event stream",
                    "enabled": true,
                    "signing_secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD",
                    "created_at": "2026-04-21T14:30:00Z"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "put": {
        "summary": "Update webhook",
        "description": "Updates a webhook endpoint. Only the fields you provide are changed. Omitted fields are left untouched.",
        "operationId": "updateWebhook",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "webhook_id",
            "in": "path",
            "required": true,
            "description": "The webhook endpoint ID (e.g. \"ep_2NfDKEm9sF8xK3pQr1Zt\").",
            "schema": {
              "type": "string",
              "example": "ep_2NfDKEm9sF8xK3pQr1Zt"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookApiRequest"
              },
              "example": {
                "topics": [
                  "call.received",
                  "call.completed"
                ],
                "enabled": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookApiResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "ep_2NfDKEm9sF8xK3pQr1Zt",
                    "url": "https://example.com/webhooks/allo",
                    "topics": [
                      "call.received",
                      "sms.received"
                    ],
                    "description": "Production event stream",
                    "enabled": true,
                    "created_at": "2026-04-21T14:30:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete webhook",
        "description": "Permanently deletes a webhook endpoint and its delivery history.",
        "operationId": "deleteWebhook",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "webhook_id",
            "in": "path",
            "required": true,
            "description": "The webhook endpoint ID (e.g. \"ep_2NfDKEm9sF8xK3pQr1Zt\").",
            "schema": {
              "type": "string",
              "example": "ep_2NfDKEm9sF8xK3pQr1Zt"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Webhook deleted"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/webhooks/event_types": {
      "get": {
        "summary": "List event types",
        "description": "Returns the catalog of event topics you can subscribe a webhook to.",
        "operationId": "listWebhookEventTypes",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Available event types",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEventTypeApiResponse"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "name": "call.received",
                      "description": "Inbound call received"
                    },
                    {
                      "name": "sms.sent",
                      "description": "Outbound sms sent"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v1/api/calls": {
      "get": {
        "summary": "Search Calls",
        "description": "**Deprecated.** Use `GET /v2/api/conversations` to list activity, or `POST /v2/api/conversations/items/search` to filter and keyword-search calls instead. This endpoint still responds, but it is no longer maintained and is not part of the current API reference.\n\nSearch and filter calls for a specific Allo phone number with pagination support.",
        "operationId": "searchCalls",
        "tags": [
          "Calls"
        ],
        "security": [
          {
            "CallsAuth": []
          }
        ],
        "parameters": [
          {
            "name": "size",
            "in": "query",
            "description": "Number of results per page. Must be between 1 and 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (0-indexed).",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "allo_number",
            "in": "query",
            "description": "Your Allo phone number to filter calls by. Must be in E.164 format (e.g., `+1234567890`).",
            "required": true,
            "schema": {
              "type": "string",
              "example": "+1234567890"
            }
          },
          {
            "name": "contact_number",
            "in": "query",
            "description": "Filter calls by contact phone number. Only returns calls with this specific contact. Must be in E.164 format (e.g., `+1234567890`).",
            "required": false,
            "schema": {
              "type": "string",
              "example": "+0987654321"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calls retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchCallsApiResponse"
                },
                "example": {
                  "data": {
                    "results": [
                      {
                        "id": "call_abc123",
                        "from_number": "+1234567890",
                        "to_number": "+0987654321",
                        "length_in_minutes": 5.5,
                        "type": "INBOUND",
                        "summary": "Customer called about order status.",
                        "tag": "support",
                        "recording_url": "https://storage.withallo.com/recordings/abc123.mp3",
                        "start_date": "2024-01-15T10:30:00",
                        "transcript": [
                          {
                            "source": "AGENT",
                            "text": "Hello, how can I help you today?",
                            "time": "2024-01-15T10:30:05",
                            "start_seconds": 5.0,
                            "end_seconds": 8.5
                          },
                          {
                            "source": "EXTERNAL",
                            "text": "Hi, I'm calling about my order status.",
                            "time": "2024-01-15T10:30:10",
                            "start_seconds": 10.0,
                            "end_seconds": 14.0
                          }
                        ]
                      }
                    ],
                    "metadata": {
                      "total_pages": 5,
                      "current_page": 0
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "deprecated": true
      }
    },
    "/v1/api/contacts": {
      "get": {
        "summary": "Search Contacts",
        "description": "**Deprecated.** Use `POST /v2/api/crm/people/search` instead. This endpoint still responds, but it is no longer maintained and is not part of the current API reference.\n\nSearch and filter contacts with sorting and pagination support. Returns contacts with engagement level information.",
        "operationId": "searchContacts",
        "tags": [
          "Contacts"
        ],
        "security": [
          {
            "ContactsAuth": []
          }
        ],
        "parameters": [
          {
            "name": "size",
            "in": "query",
            "description": "Number of results per page. Must be between 1 and 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (0-indexed).",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contacts retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchContactsApiResponse"
                },
                "example": {
                  "data": {
                    "results": [
                      {
                        "id": "cnt_abc123",
                        "name": "John",
                        "last_name": "Doe",
                        "company": {
                          "name": "Acme Corp",
                          "id": "com_xyz789"
                        },
                        "job_title": "Manager",
                        "website": null,
                        "status": "active",
                        "is_archived": false,
                        "created_at": "2024-01-10T08:00:00",
                        "updated_at": "2024-01-15T10:30:00",
                        "numbers": [
                          "+1234567890"
                        ],
                        "is_whitelisted": true,
                        "last_activity_date": "2024-01-15T10:30:00",
                        "engagement": "ENGAGED"
                      }
                    ],
                    "metadata": {
                      "pagination": {
                        "total_pages": 5,
                        "current_page": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "deprecated": true
      },
      "post": {
        "summary": "Create Contact",
        "description": "**Deprecated.** Use `POST /v2/api/crm/people` instead. This endpoint still responds, but it is no longer maintained and is not part of the current API reference.\n\nCreate a new contact in your Allo account. At least one phone number is required.",
        "operationId": "createContact",
        "tags": [
          "Contacts"
        ],
        "security": [
          {
            "ContactsWriteAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateContactRequest"
              },
              "example": {
                "name": "John",
                "last_name": "Doe",
                "job_title": "CEO",
                "website": "https://acme.com",
                "emails": [
                  "john@acme.com"
                ],
                "numbers": [
                  "+15551234567"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactApiResponse"
                },
                "example": {
                  "data": {
                    "id": "cnt_abc123",
                    "name": "John",
                    "last_name": "Doe",
                    "job_title": "CEO",
                    "website": "https://acme.com",
                    "status": null,
                    "is_archived": false,
                    "created_at": "2024-01-21T10:30:00",
                    "updated_at": "2024-01-21T10:30:00",
                    "numbers": [
                      "+15551234567"
                    ],
                    "is_whitelisted": false,
                    "last_activity_date": "2024-01-21T10:30:00",
                    "engagement": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "deprecated": true
      }
    },
    "/v1/api/contacts/{contact_id}": {
      "put": {
        "summary": "Update Contact",
        "description": "**Deprecated.** Use `PUT /v2/api/crm/people/{id}` instead. This endpoint still responds, but it is no longer maintained and is not part of the current API reference.\n\nUpdate an existing contact. Only provided fields will be updated. Arrays (emails, numbers, addresses) replace existing values entirely.",
        "operationId": "updateContact",
        "tags": [
          "Contacts"
        ],
        "security": [
          {
            "ContactsWriteAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_id",
            "in": "path",
            "description": "The unique identifier of the contact to update (e.g., \"cnt_abc123\")",
            "required": true,
            "schema": {
              "type": "string",
              "example": "cnt_abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateContactRequest"
              },
              "example": {
                "name": "John",
                "last_name": "Smith",
                "job_title": "CTO",
                "emails": [
                  "john.smith@acme.com",
                  "john@personal.com"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactApiResponse"
                },
                "example": {
                  "data": {
                    "id": "cnt_abc123",
                    "name": "John",
                    "last_name": "Smith",
                    "job_title": "CTO",
                    "website": "https://acme.com",
                    "status": null,
                    "is_archived": false,
                    "created_at": "2024-01-21T10:30:00",
                    "updated_at": "2024-01-21T11:00:00",
                    "numbers": [
                      "+15551234567"
                    ],
                    "is_whitelisted": false,
                    "last_activity_date": "2024-01-21T11:00:00",
                    "engagement": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "CONTACT_NOT_FOUND",
                  "details": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "deprecated": true
      }
    },
    "/v1/api/sms": {
      "post": {
        "summary": "Send SMS (US)",
        "description": "Send an SMS message to a US phone number using one of your Allo phone numbers. The recipient must be in the same country as your Allo number.",
        "operationId": "sendSMS",
        "tags": [
          "SMS"
        ],
        "security": [
          {
            "SmsAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendSMSRequest"
              },
              "example": {
                "from": "+1234567890",
                "to": "+0987654321",
                "message": "Hello, this is a test message"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SMS sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendSMSResponse"
                },
                "example": {
                  "data": {
                    "from_number": "+1234567890",
                    "sender_id": null,
                    "to_number": "+0987654321",
                    "type": "OUTBOUND",
                    "content": "Hello, this is a test message",
                    "start_date": "2024-01-15T10:30:00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "fromNumberNotFound": {
                    "summary": "From number not found",
                    "value": {
                      "code": "FROM_NUMBER_NOT_FOUND",
                      "details": null
                    }
                  },
                  "invalidToNumber": {
                    "summary": "Invalid to number",
                    "value": {
                      "code": "INVALID_TO_NUMBER",
                      "details": null
                    }
                  },
                  "toNumberCountryMismatch": {
                    "summary": "Country mismatch",
                    "value": {
                      "code": "TO_NUMBER_COUNTRY_MISMATCH",
                      "details": null
                    }
                  },
                  "invalidLength": {
                    "summary": "Invalid message length",
                    "value": {
                      "code": "INVALID_LENGTH",
                      "details": null
                    }
                  },
                  "providerNotSupported": {
                    "summary": "Provider not supported",
                    "value": {
                      "code": "PROVIDER_NOT_SUPPORTED",
                      "details": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/v1/api/sms#france": {
      "post": {
        "summary": "Send SMS (France)",
        "description": "Send an SMS message to a French phone number using a verified Sender ID. The Sender ID must be verified by the Allo team before use. Contact support to register your Sender ID.",
        "operationId": "sendSMSFrance",
        "tags": [
          "SMS"
        ],
        "security": [
          {
            "SmsAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendSMSFranceRequest"
              },
              "example": {
                "sender_id": "MyCompany",
                "to": "+33612345678",
                "message": "Bonjour, ceci est un message de test"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SMS sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendSMSResponse"
                },
                "example": {
                  "data": {
                    "from_number": null,
                    "sender_id": "MyCompany",
                    "to_number": "+33612345678",
                    "type": "OUTBOUND",
                    "content": "Bonjour, ceci est un message de test",
                    "start_date": "2024-01-15T10:30:00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidSenderId": {
                    "summary": "Invalid Sender ID",
                    "value": {
                      "code": "INVALID_SENDER_ID",
                      "details": null
                    }
                  },
                  "senderIdNotActive": {
                    "summary": "Sender ID not active",
                    "value": {
                      "code": "SENDER_ID_NOT_ACTIVE",
                      "details": null
                    }
                  },
                  "invalidToNumber": {
                    "summary": "Invalid to number",
                    "value": {
                      "code": "INVALID_TO_NUMBER",
                      "details": null
                    }
                  },
                  "invalidLength": {
                    "summary": "Invalid message length",
                    "value": {
                      "code": "INVALID_LENGTH",
                      "details": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/v1/api/numbers": {
      "get": {
        "summary": "Get Phone Numbers",
        "description": "**Deprecated.** Use `GET /v2/api/numbers` instead. This endpoint still responds, but it is no longer maintained and is not part of the current API reference.\n\nRetrieve all Allo phone numbers associated with your account. Returns basic information about each number including country, name, and sharing status.",
        "operationId": "getNumbers",
        "tags": [
          "Phone Numbers"
        ],
        "security": [
          {
            "CallsAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Phone numbers retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetNumbersResponse"
                },
                "example": {
                  "data": [
                    {
                      "number": "+1234567890",
                      "name": "Main Line",
                      "country": "US",
                      "is_shared_number": false
                    },
                    {
                      "number": "+33612345678",
                      "name": "France Office",
                      "country": "FR",
                      "is_shared_number": true
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "deprecated": true
      }
    },
    "/v1/api/contact/{contact_id}": {
      "get": {
        "summary": "Get Contact",
        "description": "**Deprecated.** Use `GET /v2/api/crm/people/{id}` instead. This endpoint still responds, but it is no longer maintained and is not part of the current API reference.\n\nGet detailed information for a specific contact by ID.",
        "operationId": "getContactContext",
        "tags": [
          "Contacts"
        ],
        "security": [
          {
            "ContactsAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_id",
            "in": "path",
            "description": "The unique identifier of the contact (e.g., \"cnt_abc123\")",
            "required": true,
            "schema": {
              "type": "string",
              "example": "cnt_abc123"
            }
          },
          {
            "name": "extend",
            "in": "query",
            "description": "Comma-separated list of additional data to include. Available options: `engagement` (includes engagement level), `activity` (includes recent communication activities).",
            "required": false,
            "schema": {
              "type": "string",
              "example": "engagement,activity"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contact context retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetContactContextResponse"
                },
                "example": {
                  "data": {
                    "id": "cnt_abc123",
                    "name": "John",
                    "last_name": "Doe",
                    "numbers": [
                      "+1234567890"
                    ],
                    "emails": [
                      "john@acme.com"
                    ],
                    "company": {
                      "name": "Acme Corp",
                      "id": "com_xyz789"
                    },
                    "job_title": "CEO",
                    "website": "https://acme.com",
                    "integration_data": {
                      "HUBSPOT": {
                        "contact_id": "12345",
                        "deal_stage": "Negotiation"
                      }
                    },
                    "custom_properties": {
                      "preferred_language": "English",
                      "vip_status": true
                    },
                    "engagement": "ENGAGED",
                    "activity": [
                      {
                        "type": "INBOUND_CALL",
                        "made_by": "John Doe",
                        "made_at": "2024-01-15T10:30:00",
                        "allo_number": "+1234567890",
                        "content": null
                      },
                      {
                        "type": "OUTBOUND_SMS",
                        "made_by": "Jane Smith",
                        "made_at": "2024-01-14T09:15:00",
                        "allo_number": null,
                        "content": "Thank you for your call. We will follow up shortly."
                      }
                    ],
                    "conversation_url": "/v1/api/contact/cnt_abc123/conversation"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "CONTACT_NOT_FOUND",
                  "details": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "deprecated": true
      }
    },
    "/v1/api/contact/{contact_id}/conversation": {
      "get": {
        "summary": "Search Conversations",
        "description": "**Deprecated.** Use `POST /v2/api/conversations/items/search` instead. This endpoint still responds, but it is no longer maintained and is not part of the current API reference.\n\nSearch calls and SMS for a specific contact. Returns paginated results including call recordings, transcripts, AI summaries, and text messages.",
        "operationId": "getContactConversation",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "CallsAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_id",
            "in": "path",
            "description": "The unique identifier of the contact (e.g., \"cnt_abc123\")",
            "required": true,
            "schema": {
              "type": "string",
              "example": "cnt_abc123"
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Number of results per page. Must be between 1 and 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (0-indexed).",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "allo_number",
            "in": "query",
            "description": "Filter conversations by a specific Allo phone number (E.164 format).",
            "required": false,
            "schema": {
              "type": "string",
              "example": "+1234567890"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetContactConversationResponse"
                },
                "example": {
                  "data": {
                    "results": [
                      {
                        "type": "CALL",
                        "call": {
                          "id": "call_abc123",
                          "from_number": "+1234567890",
                          "to_number": "+0987654321",
                          "length_in_minutes": 5.5,
                          "type": "INBOUND",
                          "summary": "Customer called about order status.",
                          "tag": "support",
                          "tags": [
                            "support",
                            "order"
                          ],
                          "recording_url": "https://storage.withallo.com/recordings/abc123.mp3",
                          "start_date": "2024-01-15T10:30:00",
                          "transcript": [
                            {
                              "source": "AGENT",
                              "text": "Hello, how can I help you today?",
                              "time": "2024-01-15T10:30:05",
                              "start_seconds": 5.0,
                              "end_seconds": 8.5
                            }
                          ]
                        },
                        "message": null
                      },
                      {
                        "type": "TEXT_MESSAGE",
                        "call": null,
                        "message": {
                          "from_number": "+1234567890",
                          "to_number": "+0987654321",
                          "type": "OUTBOUND",
                          "content": "Thank you for contacting us!",
                          "start_date": "2024-01-15T11:00:00"
                        }
                      }
                    ],
                    "metadata": {
                      "pagination": {
                        "total_pages": 5,
                        "current_page": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "CONTACT_NOT_FOUND",
                  "details": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "deprecated": true
      }
    },
    "/v2/api/conversations": {
      "get": {
        "summary": "List conversations",
        "description": "Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity. Listing by `inbox_id` or with `pinned` can return `400` `FEATURE_NOT_SUPPORTED` (with `param` naming which one), `400` `CONTACT_FILTER_NOT_SUPPORTED` when the inbox has saved contact filters on a workspace still on the old contact model, or `422` `CONTACT_FILTER_TOO_LARGE` (type `validation_error`) when its contact filters resolve to too many numbers or hold more than 50 IDs. Right after an inbox is created, `INBOX_NOT_FOUND` can be transient and carries `retryable: true`: retry once.",
        "operationId": "listConversations",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "allo_number",
            "in": "query",
            "required": false,
            "description": "Filter by Allo number (E.164). Send exactly one of `allo_number` or `inbox_id`. List your numbers with GET /v2/api/numbers to find the right one.",
            "schema": {
              "type": "string",
              "example": "+14155550100"
            }
          },
          {
            "name": "inbox_id",
            "in": "query",
            "description": "List the conversations of one of your inboxes (`inb-*`), from all of its lines (each row has its own `allo_number`). The inbox's sources and saved filters apply, but not the app's Needs action and Mine tabs; pass `unread` yourself. Send exactly one of `allo_number` or `inbox_id`.",
            "schema": {
              "type": "string",
              "example": "inb-abc123"
            }
          },
          {
            "name": "last_activity_since",
            "in": "query",
            "description": "Only return conversations with activity after this timestamp (ISO 8601). Ideal for incremental sync.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-04-20T10:00:00Z"
            }
          },
          {
            "name": "unread",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "pinned",
            "in": "query",
            "description": "Only pinned (`true`) or only unpinned (`false`) conversations. Any other value returns `400` `INVALID_PARAMETER`.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "$ref": "#/components/parameters/Extend"
          }
        ],
        "responses": {
          "200": {
            "description": "List of conversations",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ConversationSummary"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "contact_number": "+14155551234",
                      "contacts": [
                        {
                          "id": "cnt-abc123",
                          "name": "Sarah Johnson",
                          "company": {
                            "id": "com-xyz789",
                            "name": "Acme Corp"
                          },
                          "deals": [
                            {
                              "id": "dea-def456",
                              "name": "Enterprise Plan",
                              "status": "open"
                            }
                          ]
                        }
                      ],
                      "last_activity": "2026-04-21T14:30:00Z",
                      "last_item": {
                        "id": "cll-abc123",
                        "type": "CALL",
                        "direction": "INBOUND",
                        "date": "2026-04-21T14:30:00Z",
                        "summary": "Customer called about upgrading their plan.",
                        "result": "ANSWERED",
                        "duration": 145
                      },
                      "pinned": false,
                      "allo_number": "+14155550100"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 156,
                    "total_pages": 8,
                    "has_more": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "422": {
            "description": "The inbox's contact filters resolve to too many numbers or hold more than 50 IDs (`CONTACT_FILTER_TOO_LARGE`, type `validation_error`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/items/search": {
      "post": {
        "summary": "Search all conversations",
        "description": "Search and filter items across all conversations. Supports keyword search across transcripts, summaries, and message content.",
        "operationId": "searchAllConversations",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemSearchRequest"
              },
              "example": {
                "search": "billing issues",
                "type": "CALL",
                "sort": "RELEVANCE",
                "date": {
                  "from": "2026-01-01",
                  "to": "2026-04-21"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ConversationItem"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "cll-abc123",
                      "type": "CALL",
                      "direction": "INBOUND",
                      "allo_number": "+14155550100",
                      "contact_number": "+14155551234",
                      "contacts": [
                        {
                          "id": "cnt-abc123",
                          "name": "Sarah Johnson"
                        }
                      ],
                      "user": {
                        "id": "usr-abc123",
                        "name": "Alex Kim"
                      },
                      "date": "2026-04-21T14:30:00Z",
                      "duration": 145,
                      "result": "ANSWERED",
                      "recording_url": "https://storage.withallo.com/recordings/cll-abc123.mp3",
                      "summary": "Customer called about a billing issue on their last invoice.",
                      "tags": [
                        "billing",
                        "support"
                      ]
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 1,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/items/{id}": {
      "get": {
        "summary": "Get conversation item",
        "description": "Returns a single call or SMS message by its ID.",
        "operationId": "getConversationItem",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Item ID (`cll-*` for calls, `msg-*` for messages)",
            "schema": {
              "type": "string",
              "example": "cll-abc123"
            }
          },
          {
            "$ref": "#/components/parameters/Extend"
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConversationItem"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/items/{id}/recording": {
      "get": {
        "summary": "Get recording download link",
        "description": "Returns a fresh signed link to download a call's recording, valid for 60 minutes. The link works without an Allo login: do not share it beyond the people who may hear the call. Only a user who can play the recording in Allo gets one, and never for a call on a HIPAA-enabled team.",
        "operationId": "getConversationItemRecording",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Call ID (`cll-*`).",
            "schema": {
              "type": "string",
              "example": "cll-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Download link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "Signed link that downloads the recording, with no login.",
                          "example": "https://storage.withallo.com/object/sign/recordings/abc123.mp3?token=eyJhbGciOi..."
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the link stops working, 60 minutes after the request.",
                          "example": "2026-10-19T15:30:00Z"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "url": "https://storage.withallo.com/object/sign/recordings/abc123.mp3?token=eyJhbGciOi...",
                    "expires_at": "2026-10-19T15:30:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The ID has an unrecognized prefix (INVALID_ITEM_ID).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key lacks the CONVERSATIONS_READ scope, the key's user cannot play this recording (RECORDING_ACCESS_DENIED), or the line belongs to a HIPAA-enabled team (RECORDING_DOWNLOAD_RESTRICTED).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No call with this ID (CONVERSATION_ITEM_NOT_FOUND), or the item has no recording (RECORDING_NOT_FOUND). An SMS (`msg-*`) has no recording.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "The download link could not be created (RECORDING_DOWNLOAD_UNAVAILABLE). Retry in a few seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/conversations/items/{id}/summary": {
      "patch": {
        "summary": "Update call summary",
        "description": "Replace the markdown content of a call's AI-generated summary.\n\nOnly call items have summaries — passing an SMS ID (`msg-*`) returns `400 INVALID_ITEM_ID`. If multiple completed summary templates exist on the same call, set `template_key` to disambiguate.",
        "operationId": "updateCallSummary",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Call ID (`cll-*`)",
            "schema": {
              "type": "string",
              "example": "cll-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Full replacement markdown content. Max 100,000 characters.",
                    "maxLength": 100000
                  },
                  "template_key": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "MARKDOWN_CLASSIC",
                      "MARKDOWN_SHORT_CALL"
                    ],
                    "description": "Required only when the call has more than one completed summary template."
                  }
                },
                "required": [
                  "content"
                ]
              },
              "example": {
                "content": "# Summary\n\nCustomer asked about pricing for the Pro plan and confirmed a follow-up call next Tuesday."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallSummary"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cll-abc123",
                    "content": "# Summary\n\nCustomer asked about pricing for the Pro plan and confirmed a follow-up call next Tuesday.",
                    "version": 4,
                    "updated_at": "2026-05-12T14:32:11",
                    "updated_by": {
                      "id": "usr-abc123",
                      "name": "Alex Kim"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/me": {
      "get": {
        "summary": "Me",
        "description": "Returns information about the authenticated API key: its scopes, available endpoints, team, and rate limits. No specific scope is required — any valid API key can call this endpoint.\n\nAgents should call this endpoint first to discover their capabilities before making other API calls.",
        "operationId": "getMe",
        "tags": [
          "Users"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "API key info retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MeResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "api_key_id": "api-abc123def456",
                    "scopes": [
                      "CONVERSATIONS_READ",
                      "PHONE_NUMBERS_READ",
                      "TAGS_READ",
                      "TAGS_WRITE",
                      "USERS_READ"
                    ],
                    "endpoints": [
                      {
                        "method": "GET",
                        "path": "/v2/api/conversations",
                        "description": "List conversations grouped by contact number",
                        "scope": "CONVERSATIONS_READ"
                      },
                      {
                        "method": "POST",
                        "path": "/v2/api/conversations/items/search",
                        "description": "Search calls and SMS with filters and keyword search",
                        "scope": "CONVERSATIONS_READ"
                      },
                      {
                        "method": "GET",
                        "path": "/v2/api/tags",
                        "description": "List all available tags",
                        "scope": "TAGS_READ"
                      },
                      {
                        "method": "GET",
                        "path": "/v2/api/users",
                        "description": "List team members with roles and assigned numbers",
                        "scope": "USERS_READ"
                      },
                      {
                        "method": "GET",
                        "path": "/v2/api/numbers",
                        "description": "List phone numbers with capabilities and member access",
                        "scope": "PHONE_NUMBERS_READ"
                      }
                    ],
                    "team": {
                      "id": "team-xyz789",
                      "name": "Acme Sales"
                    },
                    "rate_limits": {
                      "read_per_second": 20,
                      "write_per_second": 5
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/users": {
      "get": {
        "summary": "List users",
        "description": "Returns all team members.",
        "operationId": "listUsers",
        "tags": [
          "Users"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "role",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ADMIN",
                "MANAGER",
                "MEMBER"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "BLOCKED"
              ],
              "default": "ACTIVE"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of users",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "usr-abc123",
                      "name": "Alex Kim",
                      "email": "alex@acme.com",
                      "role": "ADMIN",
                      "status": "ACTIVE",
                      "image_url": "https://storage.withallo.com/avatars/usr-abc123.jpg"
                    },
                    {
                      "id": "usr-def456",
                      "name": "Jordan Lee",
                      "email": "jordan@acme.com",
                      "role": "MEMBER",
                      "status": "ACTIVE",
                      "image_url": null
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/users/{id}": {
      "get": {
        "summary": "Get user",
        "description": "Returns a single team member by their ID.",
        "operationId": "getUser",
        "tags": [
          "Users"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "usr-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/tags": {
      "get": {
        "summary": "List tags",
        "description": "Returns all tags configured on the team.",
        "operationId": "listTags",
        "tags": [
          "Tags"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of tags",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tag"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "tag-abc123",
                      "name": "qualified",
                      "color": "#00AA00"
                    },
                    {
                      "id": "tag-def456",
                      "name": "follow_up",
                      "color": "#FF8800"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create tag",
        "description": "Creates a new tag on the team. The tag key is auto-generated by slugifying the name.",
        "operationId": "createTag",
        "tags": [
          "Tags"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Tag display name. The key (identifier) is derived from it.",
                    "example": "Interested"
                  },
                  "color": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 7,
                    "description": "Optional hex color (e.g. `#FF0000`).",
                    "example": "#123456"
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Interested",
                "color": "#123456"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tag created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Tag"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "interested",
                    "name": "Interested",
                    "color": "#123456"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/tags/{id}": {
      "delete": {
        "summary": "Delete tag",
        "description": "Soft-deletes a tag by its key. Tags synced from a CRM integration cannot be deleted via the API.",
        "operationId": "deleteTag",
        "tags": [
          "Tags"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tag key (the identifier returned by `GET /v2/api/tags`).",
            "schema": {
              "type": "string",
              "example": "interested"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Tag deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers": {
      "get": {
        "summary": "List phone numbers",
        "description": "Returns all phone numbers and sender IDs on your team.",
        "operationId": "listNumbers",
        "tags": [
          "Phone Numbers"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of phone numbers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PhoneNumber"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "number": "+14155550100",
                      "name": "Sales US",
                      "country": "US",
                      "type": "NUMBER",
                      "capabilities": [
                        "VOICE",
                        "SMS",
                        "MMS"
                      ],
                      "users": [
                        {
                          "id": "usr-abc123",
                          "name": "Adrien",
                          "email": "adrien@company.com"
                        }
                      ]
                    },
                    {
                      "number": "+33612345678",
                      "name": "Support FR",
                      "country": "FR",
                      "type": "NUMBER",
                      "capabilities": [
                        "VOICE"
                      ],
                      "users": [
                        {
                          "id": "usr-abc123",
                          "name": "Adrien",
                          "email": "adrien@company.com"
                        },
                        {
                          "id": "usr-def456",
                          "name": "Marie",
                          "email": "marie@company.com"
                        }
                      ]
                    },
                    {
                      "number": null,
                      "name": "Acme Corp",
                      "country": "FR",
                      "type": "SENDER_ID",
                      "capabilities": [
                        "SMS"
                      ],
                      "users": []
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/items/{id}/tags": {
      "post": {
        "summary": "Add tags",
        "description": "Add one or more tags to a conversation item.",
        "operationId": "addTags",
        "tags": [
          "Tags"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Call ID (`cll-*`)",
            "schema": {
              "type": "string",
              "example": "cll-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tag keys to add"
                  }
                },
                "required": [
                  "tags"
                ]
              },
              "example": {
                "tags": [
                  "qualified",
                  "follow_up"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tags added successfully"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/items/{id}/tags/{tag}": {
      "delete": {
        "summary": "Remove tag",
        "description": "Remove a tag from a conversation item.",
        "operationId": "removeTag",
        "tags": [
          "Tags"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Call ID (`cll-*`)",
            "schema": {
              "type": "string",
              "example": "cll-abc123"
            }
          },
          {
            "name": "tag",
            "in": "path",
            "required": true,
            "description": "Tag key to remove",
            "schema": {
              "type": "string",
              "example": "qualified"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tag removed successfully"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/items/batch": {
      "post": {
        "summary": "Get many conversation items",
        "description": "Returns multiple conversation items by their IDs in a single request. Use this to fetch full details (summary, tags, recording, etc.) for items returned by the analytics drilldown or any other list.",
        "operationId": "batchGetConversationItems",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of conversation item IDs (max 100)",
                    "maxItems": 100
                  }
                },
                "required": [
                  "ids"
                ]
              },
              "example": {
                "ids": [
                  "cll-abc123",
                  "cll-def456",
                  "cll-ghi789"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversation items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ConversationItem"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/dialing-queues/current": {
      "get": {
        "summary": "List current queue numbers",
        "description": "Returns the numbers in the Power Dialer queue currently assigned to the authenticated user, paginated and ordered by `position` ascending. `data` is the list of numbers (use `page`/`size` and read `pagination` to page through them); the `queue` key carries the queue's metadata (id, name, settings) without its numbers. To target a teammate's queue, pass either `user_id` or `email` as a query parameter (`user_id` wins when both are sent); the target must belong to the same team as the API key owner. When the user has no queue, the response is `200` with an empty `data` array, a zeroed `pagination`, and no `queue` (not a `404`).",
        "operationId": "getCurrentDialingQueue",
        "tags": [
          "Power Dialer"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "query",
            "required": false,
            "description": "ID of a teammate to read the queue for. Resolve teammate ids via [GET /v2/api/users](/en/v2/api-reference/users/list-users). Wins over `email` when both are provided.",
            "schema": {
              "type": "string",
              "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
            }
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "description": "Email of a teammate to read the queue for. Ignored when `user_id` is also supplied.",
            "schema": {
              "type": "string",
              "format": "email",
              "example": "teammate@acme.com"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-indexed page number for the queue's `numbers`.",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1,
              "example": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Number of `numbers` per page (max 100).",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100,
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of the current queue's numbers, ordered by position. Empty `data` array with zeroed `pagination` when the user has no queue.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/QueueNumber"
                          }
                        },
                        "queue": {
                          "$ref": "#/components/schemas/DialingQueueMeta"
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "number_to": "+12125550010",
                      "position": 0,
                      "created_at": "2026-04-30T10:00:00",
                      "updated_at": "2026-04-30T10:00:00",
                      "call_start_date": null,
                      "call_id": null,
                      "routing_result": null,
                      "sync_status": "NOT_SYNCED",
                      "call_status": "QUEUED"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 137,
                    "total_pages": 7,
                    "has_more": true
                  },
                  "queue": {
                    "id": "pdl_2xGh7kLmNpQr",
                    "name": "My Queue",
                    "creator_id": "usr_abc123",
                    "assignee_id": "usr_abc123",
                    "voicemail_handling": "NO_SKIP",
                    "do_not_disturb": "DISABLED",
                    "created_at": "2026-04-30T10:00:00",
                    "updated_at": "2026-04-30T10:00:00"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Assignee not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "assignee_not_found": {
                    "summary": "user_id or email does not match a teammate",
                    "value": {
                      "error": {
                        "type": "not_found_error",
                        "code": "ASSIGNEE_NOT_FOUND",
                        "message": "No team member found for the provided 'user_id' or 'email'.",
                        "retryable": false,
                        "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Reset current queue",
        "description": "Creates a fresh, empty queue assigned to the authenticated user. Any older queue with the same assignee stops being returned by `GET /current` (the newest queue wins). Send `user_id` or `email` to create the queue for a teammate instead — the API key owner is recorded as `creator_id`, the teammate as `assignee_id`. `user_id` wins when both are provided.",
        "operationId": "resetCurrentDialingQueue",
        "tags": [
          "Power Dialer"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResetDialingQueueRequest"
              },
              "examples": {
                "self": {
                  "summary": "Reset your own queue",
                  "value": {
                    "name": "Monday cold calls"
                  }
                },
                "teammate_by_pid": {
                  "summary": "Reset a teammate's queue by user_id",
                  "value": {
                    "name": "Monday cold calls",
                    "user_id": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
                  }
                },
                "teammate_by_email": {
                  "summary": "Reset a teammate's queue by email",
                  "value": {
                    "name": "Monday cold calls",
                    "email": "teammate@acme.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The newly created (empty) queue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DialingQueue"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "pdl_2xGh7kLmNpQr",
                    "name": "Monday cold calls",
                    "creator_id": "usr_abc123",
                    "assignee_id": "usr_abc123",
                    "voicemail_handling": "NO_SKIP",
                    "do_not_disturb": "DISABLED",
                    "numbers": [],
                    "created_at": "2026-05-06T10:00:00",
                    "updated_at": "2026-05-06T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "description": "Authenticated user or assignee not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "user_not_found": {
                    "summary": "Authenticated user not found",
                    "value": {
                      "error": {
                        "type": "not_found_error",
                        "code": "USER_NOT_FOUND",
                        "message": "User not found.",
                        "retryable": false
                      }
                    }
                  },
                  "assignee_not_found": {
                    "summary": "user_id or email does not match a teammate",
                    "value": {
                      "error": {
                        "type": "not_found_error",
                        "code": "ASSIGNEE_NOT_FOUND",
                        "message": "No team member found for the provided 'user_id' or 'email'.",
                        "retryable": false,
                        "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email."
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "patch": {
        "summary": "Upsert current queue",
        "description": "Creates or updates the config of the queue assigned to the authenticated user. Send `user_id` or `email` to act on a teammate's queue instead — `user_id` wins when both are provided.",
        "operationId": "upsertCurrentDialingQueue",
        "tags": [
          "Power Dialer"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpsertDialingQueueRequest"
              },
              "examples": {
                "self": {
                  "summary": "Update your own queue",
                  "value": {
                    "name": "Cold Calls"
                  }
                },
                "teammate_by_pid": {
                  "summary": "Update a teammate's queue by user_id",
                  "value": {
                    "name": "Cold Calls",
                    "user_id": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated queue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DialingQueue"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "404": {
            "description": "Assignee not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "not_found_error",
                    "code": "ASSIGNEE_NOT_FOUND",
                    "message": "No team member found for the provided 'user_id' or 'email'.",
                    "retryable": false,
                    "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email."
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/dialing-queues/current/numbers": {
      "post": {
        "summary": "Append numbers to queue",
        "description": "Appends phone numbers to the Power Dialer queue assigned to the authenticated user. Creates the queue implicitly if none exists. Send `user_id` or `email` to append to a teammate's queue — if that teammate has no current queue, one is created with the API key owner as `creator_id` and the teammate as `assignee_id`. `user_id` wins when both are provided.",
        "operationId": "appendDialingQueueNumbers",
        "tags": [
          "Power Dialer"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppendQueueNumbersRequest"
              },
              "examples": {
                "self": {
                  "summary": "Append to your own queue",
                  "value": {
                    "numbers": [
                      {
                        "number": "+1 (212) 555-0010",
                        "name": "John",
                        "last_name": "Doe",
                        "company": "Acme Inc",
                        "job_title": "Sales Manager",
                        "emails": [
                          "john.doe@acme.com"
                        ],
                        "website": "https://acme.com",
                        "custom_attributes": {
                          "lead_source": "Webinar"
                        }
                      },
                      {
                        "number": "+33 6 12 34 56 78",
                        "name": "Marie",
                        "last_name": "Dupont",
                        "company": "Acme Inc"
                      },
                      {
                        "number": "+44 20 7946 0958"
                      }
                    ]
                  }
                },
                "teammate_by_pid": {
                  "summary": "Append to a teammate's queue by user_id",
                  "value": {
                    "user_id": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220",
                    "numbers": [
                      {
                        "number": "+12125550010",
                        "name": "John",
                        "last_name": "Doe"
                      }
                    ]
                  }
                },
                "teammate_by_email": {
                  "summary": "Append to a teammate's queue by email",
                  "value": {
                    "email": "teammate@acme.com",
                    "numbers": [
                      {
                        "number": "+12125550010",
                        "name": "John",
                        "last_name": "Doe"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Numbers appended",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AppendQueueNumbersResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "added": [
                      {
                        "number_to": "+12125550010",
                        "position": 0,
                        "created_at": "2026-04-30T10:00:00",
                        "updated_at": "2026-04-30T10:00:00"
                      },
                      {
                        "number_to": "+33612345678",
                        "position": 1,
                        "created_at": "2026-04-30T10:00:00",
                        "updated_at": "2026-04-30T10:00:00"
                      }
                    ],
                    "skipped": [],
                    "ignored_custom_attributes": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "Queue limit reached or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "validation_error",
                    "code": "DIALING_QUEUE_LIMIT_REACHED",
                    "message": "The dialing queue cannot exceed 25,000 numbers.",
                    "retryable": false
                  }
                }
              }
            }
          },
          "409": {
            "description": "Concurrent append conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "conflict_error",
                    "code": "DIALING_QUEUE_APPEND_CONFLICT",
                    "message": "A concurrent append to this queue caused a position conflict.",
                    "retryable": false,
                    "suggestion": "Retry the request — the conflict resolves on the next attempt."
                  }
                }
              }
            }
          },
          "404": {
            "description": "Assignee not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "not_found_error",
                    "code": "ASSIGNEE_NOT_FOUND",
                    "message": "No team member found for the provided 'user_id' or 'email'.",
                    "retryable": false,
                    "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email."
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Clear queue numbers",
        "description": "Removes numbers from the queue assigned to the authenticated user. Exactly one filter must be supplied via query string: `number` (E.164), `position` (0-based index), `number` + `position` together (delete a specific occurrence of a duplicate), or `unassigned=true` (remove every entry that has not been called yet). Combining `unassigned` with `number` or `position` is rejected. Pass `user_id` or `email` to clear a teammate's queue instead — `user_id` wins when both are provided.",
        "operationId": "clearDialingQueueNumbers",
        "tags": [
          "Power Dialer"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Phone number to remove (any format — normalized to E.164). Removes every entry matching this number unless `position` is also supplied.",
            "schema": {
              "type": "string",
              "example": "+12125550010"
            }
          },
          {
            "name": "position",
            "in": "query",
            "required": false,
            "description": "0-based position to remove. Combine with `number` to disambiguate when the same number appears more than once.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "example": 3
            }
          },
          {
            "name": "unassigned",
            "in": "query",
            "required": false,
            "description": "When `true`, removes every queue entry that has not been called yet. Cannot be combined with `number` or `position`.",
            "schema": {
              "type": "boolean",
              "example": true
            }
          },
          {
            "name": "user_id",
            "in": "query",
            "required": false,
            "description": "ID of a teammate whose queue to clear. Resolve teammate ids via [GET /v2/api/users](/en/v2/api-reference/users/list-users). Wins over `email` when both are provided.",
            "schema": {
              "type": "string",
              "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
            }
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "description": "Email of a teammate whose queue to clear. Ignored when `user_id` is also supplied.",
            "schema": {
              "type": "string",
              "format": "email",
              "example": "teammate@acme.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Numbers removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClearQueueNumbersResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "removed": 4
                  }
                }
              }
            }
          },
          "400": {
            "description": "Filter missing or conflicting",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "filter_required": {
                    "summary": "No filter supplied",
                    "value": {
                      "error": {
                        "type": "validation_error",
                        "code": "DIALING_QUEUE_DELETE_FILTER_REQUIRED",
                        "message": "Provide at least one of 'number', 'position', or 'unassigned=true' to clear queue numbers.",
                        "retryable": false,
                        "suggestion": "Add 'number', 'position', or 'unassigned=true' as a query parameter."
                      }
                    }
                  },
                  "filter_conflict": {
                    "summary": "unassigned combined with number/position",
                    "value": {
                      "error": {
                        "type": "validation_error",
                        "code": "DIALING_QUEUE_DELETE_FILTER_CONFLICT",
                        "message": "'unassigned=true' cannot be combined with 'number' or 'position'.",
                        "retryable": false,
                        "suggestion": "Use 'unassigned=true' alone, or remove it and rely on 'number'/'position'."
                      }
                    }
                  },
                  "invalid_phone_number": {
                    "summary": "number is not a valid E.164 number",
                    "value": {
                      "error": {
                        "type": "validation_error",
                        "code": "INVALID_PHONE_NUMBER",
                        "message": "The phone number '+1212' is not a valid E.164 number.",
                        "retryable": false,
                        "param": "number",
                        "suggestion": "Provide a valid E.164 phone number (e.g., +33612345678)."
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Queue or position not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "queue_not_found": {
                    "summary": "User has no Power Dialer queue",
                    "value": {
                      "error": {
                        "type": "not_found_error",
                        "code": "DIALING_QUEUE_NOT_FOUND",
                        "message": "No dialing queue found for the authenticated user.",
                        "retryable": false,
                        "suggestion": "Create a queue by appending numbers with POST /v2/api/dialing-queues/current/numbers."
                      }
                    }
                  },
                  "position_not_found": {
                    "summary": "No entry at the requested position",
                    "value": {
                      "error": {
                        "type": "not_found_error",
                        "code": "QUEUE_NUMBER_POSITION_NOT_FOUND",
                        "message": "No queue number found at position 7.",
                        "retryable": false,
                        "param": "position",
                        "suggestion": "Fetch the current queue with GET /v2/api/dialing-queues/current to see existing positions."
                      }
                    }
                  },
                  "assignee_not_found": {
                    "summary": "user_id or email does not match a teammate",
                    "value": {
                      "error": {
                        "type": "not_found_error",
                        "code": "ASSIGNEE_NOT_FOUND",
                        "message": "No team member found for the provided 'user_id' or 'email'.",
                        "retryable": false,
                        "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/analytics/overview": {
      "post": {
        "summary": "Team metrics",
        "description": "Returns team-wide KPIs with period-over-period comparison and a per-user breakdown. Covers all calls (inbound + outbound).",
        "operationId": "getTeamMetrics",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalyticsBaseRequest"
              },
              "example": {
                "date": {
                  "from": "2026-03-25",
                  "to": "2026-04-21"
                },
                "compare_date": {
                  "from": "2026-02-25",
                  "to": "2026-03-24"
                },
                "user_ids": [
                  "usr-abc123",
                  "usr-def456"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Team summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "date": {
                          "$ref": "#/components/schemas/AnalyticsDateRange"
                        },
                        "compare_date": {
                          "$ref": "#/components/schemas/AnalyticsDateRange"
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "total_calls": {
                              "$ref": "#/components/schemas/MetricValue"
                            },
                            "talk_time_seconds": {
                              "$ref": "#/components/schemas/MetricValue"
                            },
                            "calls_over_1_min": {
                              "$ref": "#/components/schemas/MetricValue"
                            },
                            "answer_rate": {
                              "$ref": "#/components/schemas/MetricValue"
                            }
                          }
                        },
                        "breakdown": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/UserBreakdown"
                          }
                        },
                        "last_updated": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the metrics were last updated"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "date": {
                      "from": "2026-03-25",
                      "to": "2026-04-21"
                    },
                    "compare_date": {
                      "from": "2026-02-25",
                      "to": "2026-03-24"
                    },
                    "summary": {
                      "total_calls": {
                        "value": 2899,
                        "previous": 2512,
                        "change": 0.15
                      },
                      "talk_time_seconds": {
                        "value": 81720,
                        "previous": 103380,
                        "change": -0.21
                      },
                      "calls_over_1_min": {
                        "value": 290,
                        "previous": 310,
                        "change": -0.06
                      },
                      "answer_rate": {
                        "value": 0.503,
                        "previous": 0.46,
                        "change": 0.09
                      }
                    },
                    "breakdown": [
                      {
                        "user": {
                          "id": "usr-abc123",
                          "name": "Adrien Gaucher",
                          "email": "adrien@company.com"
                        },
                        "calls": {
                          "value": 673,
                          "change": -0.05
                        },
                        "talk_time_seconds": {
                          "value": 38460,
                          "change": -0.11
                        },
                        "calls_over_1_min": {
                          "value": 141,
                          "change": -0.1
                        },
                        "answer_rate": {
                          "value": 0.645,
                          "change": -0.03
                        }
                      }
                    ],
                    "last_updated": "2026-04-21T19:07:00Z"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/analytics/outbound": {
      "post": {
        "summary": "Outbound metrics",
        "description": "Returns outbound call metrics: dial funnel (dials → connected → conversations → conversions), time series, heatmap, leaderboard, and time spent metrics.",
        "operationId": "getAnalyticsOutbound",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutboundAnalyticsRequest"
              },
              "example": {
                "date": {
                  "from": "2026-03-25",
                  "to": "2026-04-21"
                },
                "compare_date": {
                  "from": "2026-02-25",
                  "to": "2026-03-24"
                },
                "tags": [
                  "meeting_booked"
                ],
                "granularity": "DAY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Outbound analytics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "date": {
                          "$ref": "#/components/schemas/AnalyticsDateRange"
                        },
                        "compare_date": {
                          "$ref": "#/components/schemas/AnalyticsDateRange"
                        },
                        "funnel": {
                          "type": "object",
                          "properties": {
                            "dials": {
                              "$ref": "#/components/schemas/FunnelStage"
                            },
                            "connected": {
                              "$ref": "#/components/schemas/FunnelStage"
                            },
                            "conversations": {
                              "$ref": "#/components/schemas/FunnelStage"
                            },
                            "conversions": {
                              "$ref": "#/components/schemas/FunnelStage"
                            }
                          }
                        },
                        "time_series": {
                          "type": "object",
                          "properties": {
                            "dials": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/TimeSeriesPoint"
                              }
                            },
                            "connected": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/TimeSeriesPoint"
                              }
                            },
                            "connection_rate": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/TimeSeriesPoint"
                              }
                            },
                            "conversions": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/TimeSeriesPoint"
                              }
                            }
                          }
                        },
                        "heatmap": {
                          "type": "object",
                          "properties": {
                            "dials": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/HeatmapCell"
                              }
                            },
                            "connected": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/HeatmapCell"
                              }
                            },
                            "connection_rate": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/HeatmapCell"
                              }
                            }
                          }
                        },
                        "leaderboard": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "user": {
                                "$ref": "#/components/schemas/UserRef"
                              },
                              "connected": {
                                "type": "integer"
                              }
                            }
                          }
                        },
                        "time_spent": {
                          "type": "object",
                          "properties": {
                            "avg_ringing_time_seconds": {
                              "$ref": "#/components/schemas/MetricValue"
                            },
                            "avg_conversation_time_seconds": {
                              "$ref": "#/components/schemas/MetricValue"
                            },
                            "total_conversation_time_seconds": {
                              "$ref": "#/components/schemas/MetricValue"
                            }
                          }
                        },
                        "last_updated": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the metrics were last updated"
                        },
                        "items": {
                          "type": "object",
                          "nullable": true,
                          "description": "Drilldown call list. Only present when extend=items is set.",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/OutboundDrilldownItem"
                              }
                            },
                            "pagination": {
                              "$ref": "#/components/schemas/Pagination"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/{contact_number}/action": {
      "put": {
        "summary": "Execute conversation action",
        "description": "Execute an action on a conversation.",
        "operationId": "executeConversationAction",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_number",
            "in": "path",
            "required": true,
            "description": "The external phone number in E.164 format. URL-encode the `+` as `%2B`.",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "READ",
                      "UNREAD",
                      "ARCHIVE",
                      "UNARCHIVE"
                    ],
                    "description": "The action to execute."
                  },
                  "allo_number": {
                    "type": "string",
                    "description": "Scope the action to a specific Allo number (E.164). Without this, the action applies across all lines.",
                    "example": "+14155550100"
                  }
                },
                "required": [
                  "action"
                ]
              },
              "example": {
                "action": "READ",
                "allo_number": "+14155550100"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action executed successfully"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/people": {
      "post": {
        "summary": "Create person",
        "description": "Creates a new person in your CRM. Set custom attribute values with `custom_attributes`. A key that is not an active custom attribute returns `400 CUSTOM_ATTRIBUTE_KEY_UNKNOWN`, and a value of the wrong type returns `400 CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
        "operationId": "createPerson",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePersonRequest"
              },
              "example": {
                "name": "John",
                "last_name": "Doe",
                "job_title": "CEO",
                "website": "https://example.com",
                "address": "123 Main St",
                "numbers": [
                  "+33612345678"
                ],
                "emails": [
                  "john@example.com"
                ],
                "company_id": "com-xyz789",
                "custom_attributes": {
                  "lead_source": "Webinar",
                  "budget": 5000
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Person created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmPerson"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "422": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/people/{id}": {
      "get": {
        "summary": "Get person",
        "description": "Returns a single person by ID.",
        "operationId": "getPerson",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Person ID (e.g., \"per-abc123\")",
            "schema": {
              "type": "string",
              "example": "per-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Person details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmPerson"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "put": {
        "summary": "Update person",
        "description": "Updates an existing person. Only provided fields will be updated. Set custom attribute values with `custom_attributes`. A key that is not an active custom attribute returns `400 CUSTOM_ATTRIBUTE_KEY_UNKNOWN`, and a value of the wrong type returns `400 CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
        "operationId": "updatePerson",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Person ID (e.g., \"per-abc123\")",
            "schema": {
              "type": "string",
              "example": "per-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePersonRequest"
              },
              "example": {
                "job_title": "CTO",
                "custom_attributes": {
                  "lead_source": "Referral"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Person updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmPerson"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "422": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/people/search": {
      "post": {
        "summary": "Search people",
        "description": "Search and filter people in your CRM with advanced filtering, sorting, and pagination.",
        "operationId": "searchPeople",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchPeopleRequest"
              },
              "example": {
                "filters": {
                  "job_title": "engineer",
                  "company": "Acme"
                },
                "sort": "NAME_ASC",
                "page": 1,
                "size": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CrmPerson"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/attributes": {
      "get": {
        "summary": "List custom contact fields",
        "description": "Returns the custom fields defined on your team's people, paginated. Includes the fields you created with the API and the ones synced from your CRM integrations. Archived fields and built-in fields such as name or company are not listed.",
        "operationId": "listCrmAttributes",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "List of custom contact fields",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CrmAttribute"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "key": "budget",
                      "label": "Budget",
                      "type": "NUMBER",
                      "source": "allo"
                    },
                    {
                      "key": "lead_status",
                      "label": "Lead status",
                      "type": "DROPDOWN",
                      "options": [
                        {
                          "key": "hot",
                          "label": "Hot"
                        },
                        {
                          "key": "cold",
                          "label": "Cold"
                        }
                      ],
                      "source": "allo"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 2,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create custom contact field",
        "description": "Creates a custom field on your team's people. The key is derived from the label. `DROPDOWN` fields need a non-empty `options` list. Creating the same label with the same type again returns the existing field with `already_existed` set to `true`. Creating a label that matches a deleted field restores it, with its previously stored values.",
        "operationId": "createCrmAttribute",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCrmAttributeRequest"
              },
              "examples": {
                "text": {
                  "summary": "Text field",
                  "value": {
                    "label": "Lead Source",
                    "type": "TEXT"
                  }
                },
                "dropdown": {
                  "summary": "Dropdown field",
                  "value": {
                    "label": "Lead status",
                    "type": "DROPDOWN",
                    "options": [
                      {
                        "label": "Hot"
                      },
                      {
                        "label": "Cold"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The custom field that was created, restored or already existing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreateCrmAttributeResult"
                    }
                  }
                },
                "example": {
                  "data": {
                    "key": "lead_source",
                    "label": "Lead Source",
                    "type": "TEXT",
                    "already_existed": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/attributes/{key}": {
      "patch": {
        "summary": "Update custom contact field",
        "description": "Partially updates a custom field on people: only the fields you send change. `key` and `type` cannot be changed. Fields synced from a CRM integration cannot be edited.",
        "operationId": "updateCrmAttribute",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "Field key, as returned by the list endpoint",
            "schema": {
              "type": "string",
              "example": "lead_status"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCrmAttributeRequest"
              },
              "example": {
                "label": "Lead temperature",
                "options": [
                  {
                    "key": "hot",
                    "label": "Hot"
                  },
                  {
                    "label": "Warm"
                  },
                  {
                    "key": "cold",
                    "label": "Cold"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated field",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmAttribute"
                    }
                  }
                },
                "example": {
                  "data": {
                    "key": "lead_status",
                    "label": "Lead temperature",
                    "type": "DROPDOWN",
                    "options": [
                      {
                        "key": "hot",
                        "label": "Hot"
                      },
                      {
                        "key": "warm",
                        "label": "Warm"
                      },
                      {
                        "key": "cold",
                        "label": "Cold"
                      }
                    ],
                    "source": "allo"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete custom contact field",
        "description": "Removes a custom field from the API: it disappears from the list, its values are no longer returned on people, and writing to it with `custom_attributes` returns `CUSTOM_ATTRIBUTE_KEY_UNKNOWN`. The stored values are kept, and creating a field with the same label and type restores it with them. Built-in fields and fields synced from a CRM integration cannot be deleted.",
        "operationId": "deleteCrmAttribute",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "Field key, as returned by the list endpoint",
            "schema": {
              "type": "string",
              "example": "lead_status"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Field deleted"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/companies/attributes": {
      "get": {
        "summary": "List custom company attributes",
        "description": "Returns the custom attributes defined on your team's companies, paginated, including the ones synced from your CRM integrations. Archived attributes are not listed. Only available to teams on the new contact model.",
        "operationId": "listCompanyAttributes",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of company attributes",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CompanyAttribute"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "key": "industry_segment",
                      "label": "Industry segment",
                      "type": "DROPDOWN",
                      "options": [
                        {
                          "key": "smb",
                          "label": "SMB"
                        },
                        {
                          "key": "enterprise",
                          "label": "Enterprise"
                        }
                      ],
                      "is_visible": true,
                      "prompt": "Pick the segment that matches the company size mentioned on the call.",
                      "should_prompt_override": false,
                      "source": "allo",
                      "created_at": "2026-10-07T14:21:08",
                      "updated_at": "2026-10-07T14:21:08"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 1,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ]
      },
      "post": {
        "summary": "Create custom company attribute",
        "description": "Creates a custom attribute on your team's companies. The key is derived from the label. The call is idempotent: if an attribute with the same key and type already exists, it returns `201` with that attribute and `already_existed` set to `true`. `options` is required for `DROPDOWN` attributes and rejected for other types.",
        "operationId": "createCompanyAttribute",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCompanyAttributeRequest"
              },
              "example": {
                "label": "Industry segment",
                "type": "DROPDOWN",
                "options": [
                  {
                    "label": "SMB"
                  },
                  {
                    "label": "Enterprise"
                  }
                ],
                "prompt": "Pick the segment that matches the company size mentioned on the call."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The attribute that was created, or the existing one when `already_existed` is `true`",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/CompanyAttribute"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "already_existed": {
                              "type": "boolean",
                              "description": "`true` when an attribute with the same key and type already existed and nothing was created"
                            }
                          }
                        }
                      ]
                    }
                  }
                },
                "example": {
                  "data": {
                    "key": "industry_segment",
                    "label": "Industry segment",
                    "type": "DROPDOWN",
                    "options": [
                      {
                        "key": "smb",
                        "label": "SMB"
                      },
                      {
                        "key": "enterprise",
                        "label": "Enterprise"
                      }
                    ],
                    "is_visible": true,
                    "prompt": "Pick the segment that matches the company size mentioned on the call.",
                    "should_prompt_override": false,
                    "source": "allo",
                    "created_at": "2026-10-07T14:21:08",
                    "updated_at": "2026-10-07T14:21:08",
                    "already_existed": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/companies/attributes/{key}": {
      "patch": {
        "summary": "Update custom company attribute",
        "description": "Partially updates an attribute: only the fields you send change. `key` and `type` cannot be changed. Attributes synced from a CRM integration only accept `prompt`, `should_prompt_override` and `is_visible`.",
        "operationId": "updateCompanyAttribute",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "Attribute key, as returned by the list endpoint",
            "schema": {
              "type": "string",
              "example": "industry_segment"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCompanyAttributeRequest"
              },
              "example": {
                "label": "Segment",
                "is_visible": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated attribute",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompanyAttribute"
                    }
                  }
                },
                "example": {
                  "data": {
                    "key": "industry_segment",
                    "label": "Industry segment",
                    "type": "DROPDOWN",
                    "options": [
                      {
                        "key": "smb",
                        "label": "SMB"
                      },
                      {
                        "key": "enterprise",
                        "label": "Enterprise"
                      }
                    ],
                    "is_visible": true,
                    "prompt": "Pick the segment that matches the company size mentioned on the call.",
                    "should_prompt_override": false,
                    "source": "allo",
                    "created_at": "2026-10-07T14:21:08",
                    "updated_at": "2026-10-07T14:21:08"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete custom company attribute",
        "description": "Deletes an attribute and clears its value on every company. This cannot be undone. Attributes synced from a CRM integration cannot be deleted.",
        "operationId": "deleteCompanyAttribute",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "Attribute key, as returned by the list endpoint",
            "schema": {
              "type": "string",
              "example": "industry_segment"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Attribute deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/companies": {
      "post": {
        "summary": "Create company",
        "description": "Creates a new company in your CRM. Set custom attribute values with `custom_attributes`. A key that is not an active company attribute returns `400 CUSTOM_ATTRIBUTE_KEY_UNKNOWN`, and a value of the wrong type returns `400 CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
        "operationId": "createCompany",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCompanyRequest"
              },
              "example": {
                "name": "Acme Corp",
                "website": "https://acme.com",
                "industry": "Technology",
                "custom_attributes": {
                  "ping_pong_level": "Advanced"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Company created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmCompany"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/companies/{id}": {
      "get": {
        "summary": "Get company",
        "description": "Returns a single company by ID.",
        "operationId": "getCompany",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Company ID (e.g., \"com-xyz789\")",
            "schema": {
              "type": "string",
              "example": "com-xyz789"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Company details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmCompany"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "put": {
        "summary": "Update company",
        "description": "Updates an existing company. Only provided fields will be updated. Set custom attribute values with `custom_attributes`. A key that is not an active company attribute returns `400 CUSTOM_ATTRIBUTE_KEY_UNKNOWN`, and a value of the wrong type returns `400 CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
        "operationId": "updateCompany",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Company ID (e.g., \"com-xyz789\")",
            "schema": {
              "type": "string",
              "example": "com-xyz789"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCompanyRequest"
              },
              "example": {
                "industry": "SaaS",
                "custom_attributes": {
                  "ping_pong_level": "Advanced"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Company updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmCompany"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "422": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/companies/search": {
      "post": {
        "summary": "Search companies",
        "description": "Search and filter companies in your CRM.",
        "operationId": "searchCompanies",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchCompaniesRequest"
              },
              "example": {
                "filters": {
                  "name": "Acme",
                  "industry": "Technology"
                },
                "sort": "NAME_ASC",
                "page": 1,
                "size": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CrmCompany"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/deals/{id}": {
      "get": {
        "summary": "Get deal",
        "description": "Returns a single deal by ID.",
        "operationId": "getDeal",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Deal ID (e.g., \"dea-def456\")",
            "schema": {
              "type": "string",
              "example": "dea-def456"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deal details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmDeal"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/deals/search": {
      "post": {
        "summary": "Search deals",
        "description": "Search and filter deals in your CRM.",
        "operationId": "searchDeals",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchDealsRequest"
              },
              "example": {
                "search": "Enterprise",
                "page": 1,
                "size": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CrmDeal"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/{contact_number}/notes": {
      "get": {
        "summary": "List conversation notes",
        "description": "Returns the internal team notes on a conversation, paginated.",
        "operationId": "listConversationNotes",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_number",
            "in": "path",
            "required": true,
            "description": "The contact's phone number (E.164)",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          },
          {
            "name": "allo_number",
            "in": "query",
            "required": true,
            "description": "The Allo line the conversation belongs to (E.164). List your numbers with GET /v2/api/numbers.",
            "schema": {
              "type": "string",
              "example": "+14155550100"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "List of conversation notes",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ConversationNote"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "not-2NyMabc123",
                      "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow",
                      "contact_number": "+14155551234",
                      "allo_number": "+14155550100",
                      "user": {
                        "id": "usr-def456",
                        "name": "John Smith"
                      },
                      "mentions": [
                        {
                          "user_id": "usr-abc123",
                          "name": "Jane Doe",
                          "deleted": false
                        }
                      ],
                      "created_at": "2026-07-13T10:00:00",
                      "updated_at": "2026-07-13T10:00:00"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 1,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create conversation note",
        "description": "Adds an internal team note to a conversation. Notes are never visible to the contact.",
        "operationId": "createConversationNote",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_number",
            "in": "path",
            "required": true,
            "description": "The contact's phone number (E.164)",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Note text (max 4000 characters). Mention teammates inline with `@[Name](usr-...)`, or `@[all](all)` to notify the whole team.",
                    "example": "Escalate to @[Jane Doe](usr-abc123) tomorrow"
                  },
                  "allo_number": {
                    "type": "string",
                    "description": "The Allo line the conversation belongs to (E.164). Required unless `sender_id` is provided.",
                    "example": "+14155550100"
                  },
                  "sender_id": {
                    "type": "string",
                    "nullable": true,
                    "description": "Sender-ID inbox identifier, as an alternative to `allo_number` for sender-ID conversations."
                  }
                },
                "required": [
                  "content"
                ]
              },
              "example": {
                "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow",
                "allo_number": "+14155550100"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Note created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConversationNote"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "not-2NyMabc123",
                    "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow",
                    "contact_number": "+14155551234",
                    "allo_number": "+14155550100",
                    "user": {
                      "id": "usr-def456",
                      "name": "John Smith"
                    },
                    "mentions": [
                      {
                        "user_id": "usr-abc123",
                        "name": "Jane Doe",
                        "deleted": false
                      }
                    ],
                    "created_at": "2026-07-13T10:00:00",
                    "updated_at": "2026-07-13T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/notes/{id}": {
      "get": {
        "summary": "Get conversation note",
        "description": "Returns a single conversation note by ID.",
        "operationId": "getConversationNote",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Note ID (`not-*`)",
            "schema": {
              "type": "string",
              "example": "not-2NyMabc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Note details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConversationNote"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "not-2NyMabc123",
                    "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow",
                    "contact_number": "+14155551234",
                    "allo_number": "+14155550100",
                    "user": {
                      "id": "usr-def456",
                      "name": "John Smith"
                    },
                    "mentions": [
                      {
                        "user_id": "usr-abc123",
                        "name": "Jane Doe",
                        "deleted": false
                      }
                    ],
                    "created_at": "2026-07-13T10:00:00",
                    "updated_at": "2026-07-13T10:00:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "patch": {
        "summary": "Update conversation note",
        "description": "Updates a note's content. Only the note's author can edit it.",
        "operationId": "updateConversationNote",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Note ID (`not-*`)",
            "schema": {
              "type": "string",
              "example": "not-2NyMabc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Note text (max 4000 characters). Mention teammates inline with `@[Name](usr-...)`, or `@[all](all)` to notify the whole team.",
                    "example": "Escalate to @[Jane Doe](usr-abc123) tomorrow"
                  }
                },
                "required": [
                  "content"
                ]
              },
              "example": {
                "content": "Escalate to @[Jane Doe](usr-abc123) on Monday instead"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated note",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConversationNote"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "not-2NyMabc123",
                    "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow",
                    "contact_number": "+14155551234",
                    "allo_number": "+14155550100",
                    "user": {
                      "id": "usr-def456",
                      "name": "John Smith"
                    },
                    "mentions": [
                      {
                        "user_id": "usr-abc123",
                        "name": "Jane Doe",
                        "deleted": false
                      }
                    ],
                    "created_at": "2026-07-13T10:00:00",
                    "updated_at": "2026-07-13T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete conversation note",
        "description": "Deletes a note. Only the note's author can delete it.",
        "operationId": "deleteConversationNote",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Note ID (`not-*`)",
            "schema": {
              "type": "string",
              "example": "not-2NyMabc123"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Note deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/people/{person_id}/notes": {
      "get": {
        "summary": "List person notes",
        "description": "Returns the notes on a person's CRM profile, paginated.",
        "operationId": "listPersonNotes",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "person_id",
            "in": "path",
            "required": true,
            "description": "Person ID (`per-*`) — the `id` field from the People API.",
            "schema": {
              "type": "string",
              "example": "per-abc123"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "List of person notes",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/PersonNote"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "cno-abc123",
                      "person_id": "per-abc123",
                      "content": "Prefers email over calls. Intro by @[Jane Doe](usr-abc123).",
                      "user": {
                        "id": "usr-def456",
                        "name": "John Smith"
                      },
                      "mentions": [
                        {
                          "user_id": "usr-abc123",
                          "name": "Jane Doe",
                          "deleted": false
                        }
                      ],
                      "created_at": "2026-07-13T10:00:00",
                      "updated_at": "2026-07-13T10:00:00"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 1,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create person note",
        "description": "Adds a note to a person's CRM profile.",
        "operationId": "createPersonNote",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "person_id",
            "in": "path",
            "required": true,
            "description": "Person ID (`per-*`) — the `id` field from the People API.",
            "schema": {
              "type": "string",
              "example": "per-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Note text (max 4000 characters). Mention teammates inline with `@[Name](usr-...)`, or `@[all](all)` to notify the whole team.",
                    "example": "Escalate to @[Jane Doe](usr-abc123) tomorrow"
                  }
                },
                "required": [
                  "content"
                ]
              },
              "example": {
                "content": "Prefers email over calls. Intro by @[Jane Doe](usr-abc123)."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Note created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PersonNote"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cno-abc123",
                    "person_id": "per-abc123",
                    "content": "Prefers email over calls. Intro by @[Jane Doe](usr-abc123).",
                    "user": {
                      "id": "usr-def456",
                      "name": "John Smith"
                    },
                    "mentions": [
                      {
                        "user_id": "usr-abc123",
                        "name": "Jane Doe",
                        "deleted": false
                      }
                    ],
                    "created_at": "2026-07-13T10:00:00",
                    "updated_at": "2026-07-13T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/people/{person_id}/notes/{note_id}": {
      "patch": {
        "summary": "Update person note",
        "description": "Updates a person note's content. Only the note's author can edit it.",
        "operationId": "updatePersonNote",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "person_id",
            "in": "path",
            "required": true,
            "description": "Person ID (`per-*`) — the `id` field from the People API.",
            "schema": {
              "type": "string",
              "example": "per-abc123"
            }
          },
          {
            "name": "note_id",
            "in": "path",
            "required": true,
            "description": "Note ID (`cno-*`)",
            "schema": {
              "type": "string",
              "example": "cno-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Note text (max 4000 characters). Mention teammates inline with `@[Name](usr-...)`, or `@[all](all)` to notify the whole team.",
                    "example": "Escalate to @[Jane Doe](usr-abc123) tomorrow"
                  }
                },
                "required": [
                  "content"
                ]
              },
              "example": {
                "content": "Prefers email over calls. Renewal due in Q4."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated note",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PersonNote"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cno-abc123",
                    "person_id": "per-abc123",
                    "content": "Prefers email over calls. Intro by @[Jane Doe](usr-abc123).",
                    "user": {
                      "id": "usr-def456",
                      "name": "John Smith"
                    },
                    "mentions": [
                      {
                        "user_id": "usr-abc123",
                        "name": "Jane Doe",
                        "deleted": false
                      }
                    ],
                    "created_at": "2026-07-13T10:00:00",
                    "updated_at": "2026-07-13T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete person note",
        "description": "Deletes a person note. Only the note's author can delete it.",
        "operationId": "deletePersonNote",
        "tags": [
          "Notes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "person_id",
            "in": "path",
            "required": true,
            "description": "Person ID (`per-*`) — the `id` field from the People API.",
            "schema": {
              "type": "string",
              "example": "per-abc123"
            }
          },
          {
            "name": "note_id",
            "in": "path",
            "required": true,
            "description": "Note ID (`cno-*`)",
            "schema": {
              "type": "string",
              "example": "cno-abc123"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Note deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/threads": {
      "get": {
        "summary": "Find thread",
        "description": "Finds the discussion thread attached to a conversation item. Returns zero or one thread — each item has at most one thread.",
        "operationId": "findThread",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "entity_type",
            "in": "query",
            "required": true,
            "description": "Type of the conversation item",
            "schema": {
              "type": "string",
              "enum": [
                "CALL",
                "TEXT_MESSAGE",
                "CONVERSATION_NOTE"
              ]
            }
          },
          {
            "name": "entity_id",
            "in": "query",
            "required": true,
            "description": "ID of the conversation item (`cll-*`, `msg-*`, or `not-*`)",
            "schema": {
              "type": "string",
              "example": "cll-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The item's thread, or an empty list if none exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Thread"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "cth-abc123",
                      "entity_type": "CALL",
                      "entity_id": "cll-abc123",
                      "contact_number": "+14155551234",
                      "resolved": false,
                      "resolved_at": null,
                      "resolved_by": null,
                      "comment_count": 2,
                      "created_at": "2026-07-13T10:00:00",
                      "comments": [
                        {
                          "id": "thc-abc123",
                          "content": "Can someone call them back today? @[Jane Doe](usr-abc123)",
                          "user": {
                            "id": "usr-def456",
                            "name": "John Smith"
                          },
                          "mentions": [
                            {
                              "user_id": "usr-abc123",
                              "name": "Jane Doe",
                              "deleted": false
                            }
                          ],
                          "created_at": "2026-07-13T10:00:00",
                          "updated_at": "2026-07-13T10:00:00"
                        },
                        {
                          "id": "thc-def456",
                          "content": "On it.",
                          "user": {
                            "id": "usr-abc123",
                            "name": "Jane Doe"
                          },
                          "mentions": [],
                          "created_at": "2026-07-13T10:05:00",
                          "updated_at": "2026-07-13T10:05:00"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create thread",
        "description": "Starts a discussion thread on a conversation item with a first comment. Each item can have only one thread.",
        "operationId": "createThread",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entity_type": {
                    "type": "string",
                    "enum": [
                      "CALL",
                      "TEXT_MESSAGE",
                      "CONVERSATION_NOTE"
                    ],
                    "description": "Type of the conversation item to attach the thread to."
                  },
                  "entity_id": {
                    "type": "string",
                    "description": "ID of the conversation item (`cll-*`, `msg-*`, or `not-*`).",
                    "example": "cll-abc123"
                  },
                  "content": {
                    "type": "string",
                    "description": "First comment text (max 4000 characters). Mention teammates inline with `@[Name](usr-...)`.",
                    "example": "Can someone call them back today? @[Jane Doe](usr-abc123)"
                  }
                },
                "required": [
                  "entity_type",
                  "entity_id",
                  "content"
                ]
              },
              "example": {
                "entity_type": "CALL",
                "entity_id": "cll-abc123",
                "content": "Can someone call them back today? @[Jane Doe](usr-abc123)"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Thread created with its first comment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Thread"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cth-abc123",
                    "entity_type": "CALL",
                    "entity_id": "cll-abc123",
                    "contact_number": "+14155551234",
                    "resolved": false,
                    "resolved_at": null,
                    "resolved_by": null,
                    "comment_count": 1,
                    "created_at": "2026-07-13T10:00:00",
                    "comments": [
                      {
                        "id": "thc-abc123",
                        "content": "Can someone call them back today? @[Jane Doe](usr-abc123)",
                        "user": {
                          "id": "usr-def456",
                          "name": "John Smith"
                        },
                        "mentions": [
                          {
                            "user_id": "usr-abc123",
                            "name": "Jane Doe",
                            "deleted": false
                          }
                        ],
                        "created_at": "2026-07-13T10:00:00",
                        "updated_at": "2026-07-13T10:00:00"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/threads/{id}": {
      "get": {
        "summary": "Get thread",
        "description": "Returns a thread with all its comments.",
        "operationId": "getThread",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Thread ID (`cth-*`)",
            "schema": {
              "type": "string",
              "example": "cth-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Thread with comments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Thread"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cth-abc123",
                    "entity_type": "CALL",
                    "entity_id": "cll-abc123",
                    "contact_number": "+14155551234",
                    "resolved": false,
                    "resolved_at": null,
                    "resolved_by": null,
                    "comment_count": 2,
                    "created_at": "2026-07-13T10:00:00",
                    "comments": [
                      {
                        "id": "thc-abc123",
                        "content": "Can someone call them back today? @[Jane Doe](usr-abc123)",
                        "user": {
                          "id": "usr-def456",
                          "name": "John Smith"
                        },
                        "mentions": [
                          {
                            "user_id": "usr-abc123",
                            "name": "Jane Doe",
                            "deleted": false
                          }
                        ],
                        "created_at": "2026-07-13T10:00:00",
                        "updated_at": "2026-07-13T10:00:00"
                      },
                      {
                        "id": "thc-def456",
                        "content": "On it.",
                        "user": {
                          "id": "usr-abc123",
                          "name": "Jane Doe"
                        },
                        "mentions": [],
                        "created_at": "2026-07-13T10:05:00",
                        "updated_at": "2026-07-13T10:05:00"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/threads/{id}/comments": {
      "post": {
        "summary": "Create thread comment",
        "description": "Adds a comment to an existing thread.",
        "operationId": "createThreadComment",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Thread ID (`cth-*`)",
            "schema": {
              "type": "string",
              "example": "cth-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Comment text (max 4000 characters). Mention teammates inline with `@[Name](usr-...)`.",
                    "example": "On it."
                  }
                },
                "required": [
                  "content"
                ]
              },
              "example": {
                "content": "On it."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Comment created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ThreadComment"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "thc-def456",
                    "content": "On it.",
                    "user": {
                      "id": "usr-abc123",
                      "name": "Jane Doe"
                    },
                    "mentions": [],
                    "created_at": "2026-07-13T10:05:00",
                    "updated_at": "2026-07-13T10:05:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/threads/comments/{comment_id}": {
      "patch": {
        "summary": "Update thread comment",
        "description": "Updates a comment's content. Only the comment's author can edit it.",
        "operationId": "updateThreadComment",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "Comment ID (`thc-*`)",
            "schema": {
              "type": "string",
              "example": "thc-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Comment text (max 4000 characters). Mention teammates inline with `@[Name](usr-...)`."
                  }
                },
                "required": [
                  "content"
                ]
              },
              "example": {
                "content": "Calling them back at 3pm."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated comment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ThreadComment"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "thc-abc123",
                    "content": "Can someone call them back today? @[Jane Doe](usr-abc123)",
                    "user": {
                      "id": "usr-def456",
                      "name": "John Smith"
                    },
                    "mentions": [
                      {
                        "user_id": "usr-abc123",
                        "name": "Jane Doe",
                        "deleted": false
                      }
                    ],
                    "created_at": "2026-07-13T10:00:00",
                    "updated_at": "2026-07-13T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/threads/{id}/resolve": {
      "post": {
        "summary": "Resolve thread",
        "description": "Marks a thread as resolved.",
        "operationId": "resolveThread",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Thread ID (`cth-*`)",
            "schema": {
              "type": "string",
              "example": "cth-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Thread summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ThreadSummary"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cth-abc123",
                    "resolved": true,
                    "resolved_at": "2026-07-13T11:00:00",
                    "resolved_by": {
                      "id": "usr-def456",
                      "name": "John Smith"
                    },
                    "comment_count": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/threads/{id}/unresolve": {
      "post": {
        "summary": "Unresolve thread",
        "description": "Reopens a resolved thread.",
        "operationId": "unresolveThread",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Thread ID (`cth-*`)",
            "schema": {
              "type": "string",
              "example": "cth-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Thread summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ThreadSummary"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cth-abc123",
                    "resolved": false,
                    "resolved_at": null,
                    "resolved_by": null,
                    "comment_count": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/agent": {
      "get": {
        "summary": "Get AI receptionist configuration",
        "description": "Returns the whole configuration of a line's AI receptionist in one call: business details, voice and language, prompt, capabilities, business hours, transfer rules, connected calendars and knowledge sources. Call this before a write, because `PATCH` replaces whole collections.",
        "operationId": "getAgent",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The line's receptionist configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentSnapshot"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "patch": {
        "summary": "Update AI receptionist configuration",
        "description": "Updates any part of the configuration except the prompt and the on/off status. Single values are merged, collections are replaced. This does not put the receptionist on the line: that is `PUT /v2/api/numbers/{number}/agent/status`.",
        "operationId": "updateAgent",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The configuration after the write",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentSnapshot"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/agent/status": {
      "put": {
        "summary": "Turn the AI receptionist on or off",
        "description": "Puts the receptionist on the line (`ACTIVE`) or takes it off (`FORWARDING`, which sends calls to your business phone instead). This reprograms how a live line routes real calls, so confirm with a person before calling it.",
        "operationId": "setAgentStatus",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetAgentStatusRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The configuration, with the new status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentSnapshot"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/agent/prompt": {
      "put": {
        "summary": "Set the AI receptionist prompt",
        "description": "Replaces the receptionist's prompt: what it is trying to achieve, who it is, how it handles the call. A prompt is only valid whole, so read the current sections with `GET /v2/api/numbers/{number}/agent` and send them all back, including the ones you are not changing. Facts about the business belong in `knowledge`, not here.",
        "operationId": "setAgentPrompt",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetAgentPromptRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The prompt after the write, with server-derived titles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentPrompt"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/agent/knowledge/websites": {
      "post": {
        "summary": "Add website knowledge",
        "description": "Adds a website to the receptionist's knowledge. Allo crawls the site from this URL in the background and returns the entry right away; the receptionist can answer from it once indexing has finished. A crawl failure is not reported back. If another line of the team already added the URL, the existing website is linked to this line instead of crawled again.",
        "operationId": "addAgentWebsiteKnowledge",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL of a publicly reachable site. A URL without a scheme is stored as https://.",
                    "example": "https://acme.test/pricing"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The entry that was created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentWebsiteKnowledge"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/agent/knowledge/websites/{id}": {
      "patch": {
        "summary": "Enable or disable website knowledge",
        "description": "Turns a website on or off for this line without losing its crawled content. `ACTIVE` on a website of the team's library that this line does not use yet adds it to this line.",
        "operationId": "updateAgentWebsiteKnowledge",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier of the website knowledge entry, as returned by `GET /v2/api/numbers/{number}/agent`",
            "schema": {
              "type": "string",
              "example": "ksrc-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "ACTIVE",
                      "DISABLED"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The entry after the write",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentWebsiteKnowledge"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete website knowledge",
        "description": "Deletes a website from the team's knowledge library, for every line of the team. To stop only this line using it, disable it instead.",
        "operationId": "deleteAgentWebsiteKnowledge",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier of the website knowledge entry, as returned by `GET /v2/api/numbers/{number}/agent`",
            "schema": {
              "type": "string",
              "example": "ksrc-abc123"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/agent/knowledge/files/{id}": {
      "delete": {
        "summary": "Delete file knowledge",
        "description": "Deletes an uploaded document from the team's knowledge library, for every line of the team. Documents are uploaded in the Allo app; this API lists and deletes them.",
        "operationId": "deleteAgentFileKnowledge",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo phone number in E.164 format",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier of the file knowledge entry, as returned by `GET /v2/api/numbers/{number}/agent`",
            "schema": {
              "type": "string",
              "example": "ksrc-def456"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/calendars": {
      "get": {
        "summary": "List connected calendars",
        "description": "Lists the calendars connected to your workspace that you can see, whether or not a receptionist books on them. An admin sees every calendar in the workspace, a team member only the ones they connected. Connecting a calendar is an OAuth flow done in the Allo app.",
        "operationId": "listCalendars",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The calendars you can see",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Calendar"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/calendars/{id}": {
      "get": {
        "summary": "Get a connected calendar",
        "description": "Returns one connected calendar with the event types its provider currently offers, read live from the provider. This is the catalog you pick from when filling `scheduling.calendars`.",
        "operationId": "getCalendar",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Calendar identifier from `GET /v2/api/calendars`",
            "schema": {
              "type": "string",
              "example": "exc-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The calendar and its available event types",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Calendar"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/voices": {
      "get": {
        "summary": "List voices",
        "description": "Lists the voices an AI receptionist can speak with, the same catalog the Allo app offers. Each `id` is what `voice_id` takes, and a voice speaks the language it is listed under.",
        "operationId": "listVoices",
        "tags": [
          "AI Receptionist"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The voice catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Voice"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/dialing-queues/{queue_id}/assignee": {
      "patch": {
        "summary": "Reassign queue",
        "description": "Reassigns a dialing queue to another member of the team. The queue keeps its numbers and its creator. Only API keys of a team admin or manager can call this endpoint, and the API key owner must be the queue's creator or current assignee.",
        "operationId": "assignDialingQueue",
        "tags": [
          "Power Dialer"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "queue_id",
            "in": "path",
            "required": true,
            "description": "Id of the dialing queue.",
            "schema": {
              "type": "string",
              "example": "pdl-174AB37D545367EB5CE26784EE7A376202B2BFAE"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignDialingQueueRequest"
              },
              "examples": {
                "by_user_id": {
                  "summary": "Reassign by user_id",
                  "value": {
                    "user_id": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
                  }
                },
                "by_email": {
                  "summary": "Reassign by email",
                  "value": {
                    "email": "rep@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reassigned queue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DialingQueue"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither `user_id` nor `email` provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "validation_error",
                    "code": "DIALING_QUEUE_ASSIGNEE_REQUIRED",
                    "message": "Provide 'user_id' or 'email' of the team member the dialing queue should be assigned to.",
                    "retryable": false,
                    "suggestion": "List your teammates with GET /v2/api/users and pass one of their ids as 'user_id'."
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "description": "The API key belongs to a team member without the admin or manager role, or lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "permission_error",
                    "code": "DIALING_QUEUE_ASSIGN_FORBIDDEN",
                    "message": "Only a team admin or manager can reassign a dialing queue.",
                    "retryable": false,
                    "suggestion": "Use an API key that belongs to a team admin or manager."
                  }
                }
              }
            }
          },
          "404": {
            "description": "Queue or assignee not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "not_found_error",
                    "code": "DIALING_QUEUE_NOT_FOUND",
                    "message": "No dialing queue found for the requested id.",
                    "retryable": false,
                    "suggestion": "List queues with GET /v2/api/dialing-queues or create one with POST /v2/api/dialing-queues."
                  }
                }
              }
            }
          },
          "409": {
            "description": "The queue has an open dialing session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "type": "conflict_error",
                    "code": "DIALING_QUEUE_SESSION_ACTIVE",
                    "message": "The dialing queue has an open dialing session, so its assignee cannot change.",
                    "retryable": false,
                    "suggestion": "End the session in the Allo app, then retry the request."
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/views": {
      "get": {
        "summary": "List contact views",
        "description": "Returns the saved contact views you can see: your private views and your team's shared views. `page` below 1 or `size` outside 1..100 returns 400 `INVALID_PAGE_SIZE`.",
        "operationId": "listCrmViews",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "List of views",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CrmView"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    }
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "cvw_2abc",
                      "name": "Hot leads",
                      "filters": [
                        {
                          "field": "company",
                          "operator": "CONTAINS",
                          "value": "Acme"
                        }
                      ],
                      "sort": [
                        {
                          "field": "created_at",
                          "order": "desc"
                        }
                      ],
                      "owner_type": "USER",
                      "user_id": "usr_2abc",
                      "team_id": null,
                      "created_at": "2026-10-23T10:00:00",
                      "updated_at": "2026-10-23T10:00:00"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "size": 20,
                    "total_count": 1,
                    "total_pages": 1,
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create contact view",
        "description": "Creates a saved view: a named filter and sort over people. Filter conditions are combined with AND. Returns 400 `validation_error` with `INVALID_REQUEST_BODY` (per-field `errors[]`) for a blank or too long `name` or more than 50 `filters`; `INVALID_FILTER_FIELD`, `INVALID_FILTER_OPERATOR`, `INVALID_FILTER_VALUE`, `INVALID_SORT_FIELD` or `FIELD_NOT_SORTABLE` for an invalid filter or sort; `USER_HAS_NO_TEAM` for `owner_type: TEAM` when the user has no team.",
        "operationId": "createCrmView",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCrmViewRequest"
              },
              "example": {
                "name": "Hot leads",
                "filters": [
                  {
                    "field": "company",
                    "operator": "CONTAINS",
                    "value": "Acme"
                  }
                ],
                "sort": [
                  {
                    "field": "created_at",
                    "order": "desc"
                  }
                ],
                "owner_type": "USER"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The view that was created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmView"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cvw_2abc",
                    "name": "Hot leads",
                    "filters": [
                      {
                        "field": "company",
                        "operator": "CONTAINS",
                        "value": "Acme"
                      }
                    ],
                    "sort": [
                      {
                        "field": "created_at",
                        "order": "desc"
                      }
                    ],
                    "owner_type": "USER",
                    "user_id": "usr_2abc",
                    "team_id": null,
                    "created_at": "2026-10-23T10:00:00",
                    "updated_at": "2026-10-23T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/crm/views/{id}": {
      "get": {
        "summary": "Get contact view",
        "description": "Returns one saved view by ID. Returns 404 `VIEW_NOT_FOUND` for another user's private view.",
        "operationId": "getCrmView",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public ID of the view, as returned by the list endpoint",
            "schema": {
              "type": "string",
              "example": "cvw_2abc"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The view",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmView"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cvw_2abc",
                    "name": "Hot leads",
                    "filters": [
                      {
                        "field": "company",
                        "operator": "CONTAINS",
                        "value": "Acme"
                      }
                    ],
                    "sort": [
                      {
                        "field": "created_at",
                        "order": "desc"
                      }
                    ],
                    "owner_type": "USER",
                    "user_id": "usr_2abc",
                    "team_id": null,
                    "created_at": "2026-10-23T10:00:00",
                    "updated_at": "2026-10-23T10:00:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "patch": {
        "summary": "Update contact view",
        "description": "Partially updates a view: only the fields you send change. `filters: []` clears the filters. Updating a team view requires being its owner or a team ADMIN or MANAGER. Returns 400 `INVALID_REQUEST_BODY` (per-field `errors[]`) for a blank or too long `name` or more than 50 `filters`; `INVALID_FILTER_FIELD`, `INVALID_FILTER_OPERATOR`, `INVALID_FILTER_VALUE`, `INVALID_SORT_FIELD` or `FIELD_NOT_SORTABLE` for an invalid filter or sort; `USER_HAS_NO_TEAM` for `owner_type: TEAM` when the user has no team; 403 `VIEW_PERMISSION_DENIED` for a team view you do not own unless you are a team ADMIN or MANAGER; 404 `VIEW_NOT_FOUND` for a view you cannot see, such as another user's private view.",
        "operationId": "updateCrmView",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public ID of the view, as returned by the list endpoint",
            "schema": {
              "type": "string",
              "example": "cvw_2abc"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCrmViewRequest"
              },
              "example": {
                "name": "Acme leads"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated view",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmView"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "cvw_2abc",
                    "name": "Acme leads",
                    "filters": [
                      {
                        "field": "company",
                        "operator": "CONTAINS",
                        "value": "Acme"
                      }
                    ],
                    "sort": [
                      {
                        "field": "created_at",
                        "order": "desc"
                      }
                    ],
                    "owner_type": "USER",
                    "user_id": "usr_2abc",
                    "team_id": null,
                    "created_at": "2026-10-23T10:00:00",
                    "updated_at": "2026-10-23T10:00:00"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete contact view",
        "description": "Deletes a view. Deleting a team view requires being its owner or a team ADMIN or MANAGER. Returns 403 `VIEW_PERMISSION_DENIED` otherwise, and 404 `VIEW_NOT_FOUND` for a view you cannot see, such as another user's private view.",
        "operationId": "deleteCrmView",
        "tags": [
          "CRM"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public ID of the view, as returned by the list endpoint",
            "schema": {
              "type": "string",
              "example": "cvw_2abc"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "View deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/inboxes": {
      "get": {
        "summary": "List inboxes",
        "description": "Returns the caller's inboxes. With `user_id`, returns a teammate's inboxes that have at least one source in a workspace the caller manages, showing only those sources.",
        "operationId": "listInboxes",
        "tags": [
          "Inboxes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "query",
            "description": "Act on a teammate's inbox (`usr-*`). The caller must be an admin or manager of that teammate's workspace, and only reaches inboxes and sources in workspaces they manage. Omit to act on your own inboxes.",
            "schema": {
              "type": "string",
              "example": "usr-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The inboxes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Inbox"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "inb-abc123",
                      "name": "Sales",
                      "emoji": "💼",
                      "sources": [
                        {
                          "allo_number": "+33612345678",
                          "conditions": [
                            {
                              "type": "MENU_BRANCH",
                              "branches": [
                                [
                                  {
                                    "node_id": "node-1",
                                    "digit": "1"
                                  },
                                  {
                                    "node_id": "node-3",
                                    "digit": "2"
                                  }
                                ]
                              ],
                              "include_no_choice": false
                            }
                          ]
                        }
                      ],
                      "filters": {
                        "types": [
                          "INBOUND_CALL"
                        ],
                        "user_ids": [],
                        "contact_ids": [],
                        "contact_list_ids": []
                      },
                      "notifications_muted": false,
                      "favorited_at": null
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "post": {
        "summary": "Create inbox",
        "description": "Creates an inbox for the caller, or for a teammate with `user_id` in the body. Every source line must be accessible to the inbox owner. Up to 50 inboxes per user. Size limits (`name` over 80 characters, `emoji` over 16, more than 100 sources or 10 conditions per source) return `400` `INVALID_REQUEST_BODY` with `field_errors`. A menu path not listed by the line's `menu_options`, or a null source, condition or digit, returns `400` `INVALID_INBOX_SOURCE`. Menu conditions are only accepted on a line whose `menu_options` list is not empty, with paths from that list; on other lines use a whole-line source (empty `conditions`). For a teammate, the inbox must hold at least one line of the caller's workspace.",
        "operationId": "createInbox",
        "tags": [
          "Inboxes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 80,
                    "example": "Sales",
                    "description": "Required and non-blank."
                  },
                  "emoji": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 16,
                    "example": "💼"
                  },
                  "sources": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "$ref": "#/components/schemas/InboxSourceInput"
                    }
                  },
                  "filters": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/InboxFilters"
                      }
                    ],
                    "nullable": true
                  },
                  "notifications_muted": {
                    "type": "boolean",
                    "example": false
                  },
                  "user_id": {
                    "type": "string",
                    "description": "Create the inbox for this teammate (`usr-*`). The caller must be an admin or manager of that teammate's workspace.",
                    "example": "usr-abc123"
                  }
                },
                "required": [
                  "name",
                  "sources"
                ]
              },
              "example": {
                "name": "Sales",
                "emoji": "💼",
                "sources": [
                  {
                    "allo_number": "+33612345678",
                    "conditions": [
                      {
                        "type": "MENU_BRANCH",
                        "branches": [
                          [
                            {
                              "node_id": "node-1",
                              "digit": "1"
                            },
                            {
                              "node_id": "node-3",
                              "digit": "2"
                            }
                          ]
                        ],
                        "include_no_choice": false
                      }
                    ]
                  }
                ],
                "filters": {
                  "types": [
                    "INBOUND_CALL"
                  ],
                  "user_ids": [],
                  "contact_ids": [],
                  "contact_list_ids": []
                },
                "notifications_muted": false,
                "favorited_at": null
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Inbox created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Inbox"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "inb-abc123",
                    "name": "Sales",
                    "emoji": "💼",
                    "sources": [
                      {
                        "allo_number": "+33612345678",
                        "conditions": [
                          {
                            "type": "MENU_BRANCH",
                            "branches": [
                              [
                                {
                                  "node_id": "node-1",
                                  "digit": "1"
                                },
                                {
                                  "node_id": "node-3",
                                  "digit": "2"
                                }
                              ]
                            ],
                            "include_no_choice": false
                          }
                        ]
                      }
                    ],
                    "filters": {
                      "types": [
                        "INBOUND_CALL"
                      ],
                      "user_ids": [],
                      "contact_ids": [],
                      "contact_list_ids": []
                    },
                    "notifications_muted": false,
                    "favorited_at": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/inboxes/suggestions": {
      "get": {
        "summary": "Get inbox suggestions",
        "description": "Ready-made inbox sources ranked from the caller's recent calls and texts, including phone-menu branches. Each suggestion carries a `source` to put in `sources` as is. Suggestions are for the caller only.",
        "operationId": "getInboxSuggestions",
        "tags": [
          "Inboxes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Suggestions, best first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InboxSuggestion"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "allo_number": "+33612345678",
                      "name": "Sales",
                      "description": "Website FR, option 2",
                      "branch": [
                        {
                          "node_id": "node-1",
                          "digit": "1"
                        },
                        {
                          "node_id": "node-3",
                          "digit": "2"
                        }
                      ],
                      "answered": 42,
                      "rung": 57,
                      "texted": 3,
                      "score": 91,
                      "source": {
                        "allo_number": "+33612345678",
                        "conditions": [
                          {
                            "type": "MENU_BRANCH",
                            "branches": [
                              [
                                {
                                  "node_id": "node-1",
                                  "digit": "1"
                                },
                                {
                                  "node_id": "node-3",
                                  "digit": "2"
                                }
                              ]
                            ],
                            "include_no_choice": false
                          }
                        ]
                      }
                    },
                    {
                      "allo_number": "+14155550100",
                      "name": null,
                      "description": null,
                      "branch": null,
                      "answered": 12,
                      "rung": 20,
                      "texted": 8,
                      "score": 40,
                      "source": {
                        "allo_number": "+14155550100",
                        "conditions": []
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/inboxes/{inbox_id}": {
      "patch": {
        "summary": "Update inbox",
        "description": "Updates the fields sent and leaves the others unchanged. Use `notifications_muted` to mute or unmute the inbox, and `favorite` to star or unstar it. Sending `sources` replaces the whole list. For a teammate's inbox, send `user_id` in the body. Size limits (`name` over 80 characters, `emoji` over 16, more than 100 sources or 10 conditions per source) return `400` `INVALID_REQUEST_BODY` with `field_errors`. A menu path not listed by the line's `menu_options`, or a null source, condition or digit, returns `400` `INVALID_INBOX_SOURCE`. Menu conditions are only accepted on a line whose `menu_options` list is not empty, with paths from that list; on other lines use a whole-line source (empty `conditions`). With `user_id`, an inbox with no source in a workspace the caller manages returns `404`, and `sources` replaces only the lines in the caller's workspaces: the teammate's other-workspace lines are kept.",
        "operationId": "updateInbox",
        "tags": [
          "Inboxes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "inbox_id",
            "in": "path",
            "required": true,
            "description": "Inbox ID (`inb-*`).",
            "schema": {
              "type": "string",
              "example": "inb-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 80,
                    "example": "Sales",
                    "description": "Cannot be blank."
                  },
                  "emoji": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 16,
                    "description": "`\"\"` clears the emoji. Absent or `null` keeps it.",
                    "example": "💼"
                  },
                  "sources": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "$ref": "#/components/schemas/InboxSourceInput"
                    },
                    "description": "Replaces the whole list. With `user_id`, only the lines in the caller's workspaces are replaced."
                  },
                  "filters": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/InboxFilters"
                      }
                    ],
                    "nullable": true,
                    "description": "Replaces the saved filters. `null` clears them, absent keeps them. The app's Needs action and Mine settings are kept either way."
                  },
                  "notifications_muted": {
                    "type": "boolean",
                    "example": false
                  },
                  "favorite": {
                    "type": "boolean",
                    "description": "`true` stars the inbox (starring it again keeps its first `favorited_at`), `false` unstars it. Absent keeps it.",
                    "example": true
                  },
                  "user_id": {
                    "type": "string",
                    "description": "Update this teammate's inbox (`usr-*`). The caller must be an admin or manager of that teammate's workspace.",
                    "example": "usr-abc123"
                  }
                }
              },
              "example": {
                "notifications_muted": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inbox updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Inbox"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "inb-abc123",
                    "name": "Sales",
                    "emoji": "💼",
                    "sources": [
                      {
                        "allo_number": "+33612345678",
                        "conditions": [
                          {
                            "type": "MENU_BRANCH",
                            "branches": [
                              [
                                {
                                  "node_id": "node-1",
                                  "digit": "1"
                                },
                                {
                                  "node_id": "node-3",
                                  "digit": "2"
                                }
                              ]
                            ],
                            "include_no_choice": false
                          }
                        ]
                      }
                    ],
                    "filters": {
                      "types": [
                        "INBOUND_CALL"
                      ],
                      "user_ids": [],
                      "contact_ids": [],
                      "contact_list_ids": []
                    },
                    "notifications_muted": true,
                    "favorited_at": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Delete inbox",
        "description": "Deletes the inbox. Conversations are not affected. With `user_id`, an inbox with no source in a workspace the caller manages returns `404`, and an inbox that also holds lines from another workspace returns `403` `FORBIDDEN`.",
        "operationId": "deleteInbox",
        "tags": [
          "Inboxes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "inbox_id",
            "in": "path",
            "required": true,
            "description": "Inbox ID (`inb-*`).",
            "schema": {
              "type": "string",
              "example": "inb-abc123"
            }
          },
          {
            "name": "user_id",
            "in": "query",
            "description": "Act on a teammate's inbox (`usr-*`). The caller must be an admin or manager of that teammate's workspace, and only reaches inboxes and sources in workspaces they manage. Omit to act on your own inboxes.",
            "schema": {
              "type": "string",
              "example": "usr-abc123"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Inbox deleted"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/numbers/{number}/menu_options": {
      "get": {
        "summary": "List menu options",
        "description": "Flattens the phone-menu tree of the line's published call flow. Each option carries a ready `MENU_BRANCH` condition. A line without a phone menu, or whose calls are not routed by the call-flow engine, returns an empty list. Menu conditions are only accepted on lines where this list is not empty.",
        "operationId": "listMenuOptions",
        "tags": [
          "Inboxes"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Allo line in E.164 format. URL-encode the `+` as `%2B`.",
            "schema": {
              "type": "string",
              "example": "+33612345678"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Menu options",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MenuOption"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "node_id": "node-1",
                      "path": [
                        {
                          "node_id": "node-1",
                          "digit": "1"
                        }
                      ],
                      "digits": "1",
                      "label": "Website FR",
                      "condition": {
                        "type": "MENU_BRANCH",
                        "branches": [
                          [
                            {
                              "node_id": "node-1",
                              "digit": "1"
                            }
                          ]
                        ],
                        "include_no_choice": false
                      }
                    },
                    {
                      "node_id": "node-3",
                      "path": [
                        {
                          "node_id": "node-1",
                          "digit": "1"
                        },
                        {
                          "node_id": "node-3",
                          "digit": "2"
                        }
                      ],
                      "digits": "1>2",
                      "label": "Sales",
                      "condition": {
                        "type": "MENU_BRANCH",
                        "branches": [
                          [
                            {
                              "node_id": "node-1",
                              "digit": "1"
                            },
                            {
                              "node_id": "node-3",
                              "digit": "2"
                            }
                          ]
                        ],
                        "include_no_choice": false
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/conversations/{contact_number}/pin": {
      "put": {
        "summary": "Pin conversation",
        "description": "Pins a conversation for the caller. Up to 10 conversations can be pinned. Pinning a conversation that is already pinned returns `204` and changes nothing. A missing or blank `allo_number` returns `400` `INVALID_REQUEST_BODY`.",
        "operationId": "pinConversation",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_number",
            "in": "path",
            "required": true,
            "description": "The external phone number in E.164 format. URL-encode the `+` as `%2B`.",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "allo_number": {
                    "type": "string",
                    "description": "Allo line the conversation is on (E.164).",
                    "example": "+14155550100"
                  }
                },
                "required": [
                  "allo_number"
                ]
              },
              "example": {
                "allo_number": "+14155550100"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Conversation pinned"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "409": {
            "$ref": "#/components/responses/ApiConflict"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      },
      "delete": {
        "summary": "Unpin conversation",
        "description": "Unpins a conversation for the caller. Unpinning a conversation that is not pinned returns `204` and changes nothing.",
        "operationId": "unpinConversation",
        "tags": [
          "Conversations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contact_number",
            "in": "path",
            "required": true,
            "description": "The external phone number in E.164 format. URL-encode the `+` as `%2B`.",
            "schema": {
              "type": "string",
              "example": "+14155551234"
            }
          },
          {
            "name": "allo_number",
            "in": "query",
            "required": true,
            "description": "Allo line the conversation is on (E.164).",
            "schema": {
              "type": "string",
              "example": "+14155550100"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Conversation unpinned"
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/faxes": {
      "post": {
        "summary": "Send fax",
        "description": "Sends a PDF as a fax from one of your Allo lines. The line must be a US or Canada local number on which fax is turned on in the number settings (\"Send and receive faxes\"), and fax must be enabled on your account. Each page uses message credits.\n\nThe request is `multipart/form-data`, not JSON. The fax is sent asynchronously: the response returns the new conversation item with `status` `PENDING`, and `page_count` is set once the fax has been sent.",
        "operationId": "sendFax",
        "tags": [
          "Fax"
        ],
        "security": [
          {
            "FaxAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string",
                    "description": "Allo line to send from, in E.164 format. Must be a line you can use with fax turned on. List your lines with `GET /v2/api/numbers`.",
                    "example": "+14155550100"
                  },
                  "to": {
                    "type": "string",
                    "description": "Fax number of the recipient, in E.164 format.",
                    "example": "+14155551234"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The document to fax: a PDF (`application/pdf`) of at most 12 MB."
                  }
                },
                "required": [
                  "from",
                  "to",
                  "file"
                ]
              },
              "encoding": {
                "file": {
                  "contentType": "application/pdf"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Fax accepted for sending. Returns the new conversation item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConversationItem"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "msg-abc123",
                    "type": "SMS",
                    "direction": "OUTBOUND",
                    "allo_number": "+14155550100",
                    "contact_number": "+14155551234",
                    "contacts": [],
                    "user": {
                      "id": "usr-abc123",
                      "name": "Alex Kim",
                      "email": "alex@example.com"
                    },
                    "date": "2026-11-10T14:30:00",
                    "content": "",
                    "status": "PENDING",
                    "message_type": "FAX",
                    "attachments": [
                      {
                        "file_name": "contract.pdf",
                        "content_type": "application/pdf",
                        "file_size": 184320,
                        "download_url": "https://...contract.pdf?X-Amz-Expires=1800&X-Amz-Signature=...",
                        "download_expires_at": "2026-11-10T15:00:00Z"
                      }
                    ],
                    "page_count": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiValidationError"
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "Not enough message credits to send the fax",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/ApiForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ApiNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          }
        }
      }
    },
    "/v2/api/partner/esims/{id}/tier": {
      "put": {
        "summary": "Change eSIM tier",
        "description": "Moves an eSIM to another data tier. An upgrade is charged now, prorated for the rest of the billing period: Allo draws on your prepaid credit first, then charges your card on file. The extra data is added within about a minute once the payment is confirmed. A downgrade is scheduled for the end of the period already paid, and nothing is refunded. A card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED` and the attempt is cancelled. Only the number's latest eSIM can change tier. Requires the `PARTNER` scope.",
        "operationId": "changePartnerEsimTier",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The eSIM id returned by Order eSIM (`eso-*`)."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,100}$"
            },
            "description": "Optional. 8 to 100 letters, digits, `-` or `_`, for example a UUID. Retrying with the same key does not charge you twice.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tier"
                ],
                "properties": {
                  "tier": {
                    "type": "string",
                    "description": "A tier `code` from Get eSIM offer. `ESIM` is the tier with no mobile data.",
                    "example": "ESIM_20GB"
                  }
                }
              },
              "example": {
                "tier": "ESIM_20GB"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tier change accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "esim_id": {
                          "type": "string",
                          "description": "The eSIM id (`eso-*`).",
                          "example": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61"
                        },
                        "tier": {
                          "type": "string",
                          "description": "The tier you asked for.",
                          "example": "ESIM_20GB"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "ACTIVE",
                            "PENDING",
                            "SCHEDULED"
                          ],
                          "description": "`ACTIVE`: the eSIM is already on this tier, nothing is charged. `PENDING`: upgrade charged, the extra data is added once the payment is confirmed. `SCHEDULED`: downgrade, it applies at `effective_at`.",
                          "example": "PENDING"
                        },
                        "effective_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "When a scheduled downgrade applies: the end of the period already paid. `null` unless `status` is `SCHEDULED`.",
                          "example": null
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                    "tier": "ESIM_20GB",
                    "status": "PENDING",
                    "effective_at": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: MISSING_FIELD (`tier`), INVALID_ESIM_TIER or INVALID_IDEMPOTENCY_KEY.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure, and the attempt was cancelled: retry with another payment method or after topping up your credit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND), or the account the eSIM belongs to is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The eSIM is still provisioning (ESIM_NOT_READY), was deleted or is not the number's latest eSIM (ESIM_NOT_ACTIVE), already has a downgrade scheduled (ESIM_TIER_CHANGE_CONFLICT), or the subscription you pay for the account cannot be charged for eSIMs right now (ESIM_SUBSCRIPTION_CONFLICT).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "The eSIM's data cannot be changed right now (ESIM_UNAVAILABLE). The message gives the reason.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/api/partner/esims/{id}/topups": {
      "post": {
        "summary": "Buy eSIM top-up",
        "description": "Buys a data top-up for an eSIM. The top-up is charged once: Allo draws on your prepaid credit first, then charges your card on file. Its data is added to the eSIM once the payment is confirmed, for the current calendar month (Paris time). Unused data lapses at the end of that month. The `Idempotency-Key` header is required: send a new UUID for each top-up and the same one when you retry it. A card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED` and the attempt is cancelled. Only the number's latest eSIM can be topped up. Requires the `PARTNER` scope.",
        "operationId": "buyPartnerEsimTopUp",
        "tags": [
          "White label"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The eSIM id returned by Order eSIM (`eso-*`)."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,100}$"
            },
            "description": "Required. 8 to 100 letters, digits, `-` or `_`, for example a UUID. Send a new key for each top-up and the same key when you retry it: Allo does not charge you twice.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "A top-up `code` from Get eSIM offer.",
                    "example": "TOPUP_5GB"
                  }
                }
              },
              "example": {
                "code": "TOPUP_5GB"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Top-up bought",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "esim_id": {
                          "type": "string",
                          "description": "The eSIM id (`eso-*`).",
                          "example": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61"
                        },
                        "code": {
                          "type": "string",
                          "description": "The top-up you bought.",
                          "example": "TOPUP_5GB"
                        },
                        "data_mb": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Mobile data the top-up adds, in MB.",
                          "example": 5120
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "PENDING",
                            "ACTIVE"
                          ],
                          "description": "`PENDING`: charged, the data is added once the payment is confirmed. `ACTIVE`: a retry with the same `Idempotency-Key` of a top-up already added.",
                          "example": "PENDING"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
                    "code": "TOPUP_5GB",
                    "data_mb": 5120,
                    "status": "PENDING"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: MISSING_FIELD (`code`), INVALID_ESIM_TOPUP, IDEMPOTENCY_KEY_REQUIRED (no `Idempotency-Key` header) or INVALID_IDEMPOTENCY_KEY.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiUnauthorized"
          },
          "402": {
            "description": "Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure, and the attempt was cancelled: retry with another payment method or after topping up your credit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks the PARTNER scope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND), or the account the eSIM belongs to is deactivated (PARTNER_ACCOUNT_NOT_FOUND).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The eSIM is still provisioning (ESIM_NOT_READY), was deleted or is not the number's latest eSIM (ESIM_NOT_ACTIVE), another top-up for it is still being paid (ESIM_TOPUP_PENDING, retryable), the `Idempotency-Key` was already used for another top-up on this eSIM (IDEMPOTENCY_KEY_ALREADY_USED), or the subscription you pay for the account cannot be charged for eSIMs right now (ESIM_SUBSCRIPTION_CONFLICT).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ApiRateLimited"
          },
          "500": {
            "description": "The eSIM's data cannot be changed right now (ESIM_UNAVAILABLE). The message gives the reason.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "CallsAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Scope needed: `CONVERSATIONS_READ`"
      },
      "ContactsAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Scope needed: `CRM_READ`"
      },
      "ContactsWriteAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Scope needed: `CRM_WRITE`"
      },
      "SmsAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Scope needed: `SMS_SEND`"
      },
      "FaxAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Scope needed: `FAX_SEND`"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    },
    "schemas": {
      "SummaryTemplate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "tst-abc123"
          },
          "name": {
            "type": "string",
            "example": "Sales call"
          },
          "call_context": {
            "type": "string",
            "nullable": true,
            "example": "B2B SaaS sales calls"
          },
          "icon": {
            "type": "string",
            "nullable": true,
            "example": "📞"
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SummaryTemplateSection"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SummaryTemplateSection": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "example": "Pain points"
          },
          "instructions": {
            "type": "string",
            "example": "List the prospect's pain points"
          },
          "order": {
            "type": "integer",
            "description": "0-based position of the section in the summary.",
            "example": 0
          }
        }
      },
      "MeResponse": {
        "type": "object",
        "description": "Information about the authenticated API key and its capabilities",
        "properties": {
          "api_key_id": {
            "type": "string",
            "description": "Unique identifier of this API key"
          },
          "scopes": {
            "type": "array",
            "description": "Scopes granted to this key. Determines which endpoints appear in the endpoints list",
            "items": {
              "type": "string"
            }
          },
          "endpoints": {
            "type": "array",
            "description": "Endpoints this key can call, filtered by granted scopes",
            "items": {
              "type": "object",
              "properties": {
                "method": {
                  "type": "string",
                  "description": "HTTP method",
                  "enum": [
                    "GET",
                    "POST",
                    "PUT",
                    "DELETE"
                  ]
                },
                "path": {
                  "type": "string",
                  "description": "Endpoint path with parameter placeholders"
                },
                "description": {
                  "type": "string",
                  "description": "What the endpoint does"
                },
                "scope": {
                  "type": "string",
                  "description": "The scope that grants access to this endpoint"
                }
              }
            }
          },
          "team": {
            "type": "object",
            "nullable": true,
            "description": "The team this key belongs to. Null if the user has no team",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "rate_limits": {
            "type": "object",
            "description": "Request rate limits for this API key",
            "properties": {
              "read_per_second": {
                "type": "integer",
                "description": "Maximum GET requests per second"
              },
              "write_per_second": {
                "type": "integer",
                "description": "Maximum POST/PUT/DELETE requests per second"
              }
            }
          }
        }
      },
      "SearchCallsApiResponse": {
        "type": "object",
        "description": "Standard response wrapper for paginated call results",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CallApiResponse"
                }
              },
              "metadata": {
                "$ref": "#/components/schemas/SearchMetadata"
              }
            }
          }
        }
      },
      "CallApiResponse": {
        "type": "object",
        "description": "A call record with details about the conversation",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique call identifier",
            "example": "call_abc123"
          },
          "from_number": {
            "type": "string",
            "description": "Phone number that initiated the call (E.164 format or 'anonymous')",
            "example": "+1234567890"
          },
          "to_number": {
            "type": "string",
            "nullable": true,
            "description": "Phone number that received the call",
            "example": "+0987654321"
          },
          "length_in_minutes": {
            "type": "number",
            "format": "double",
            "description": "Duration of the call in minutes",
            "example": 5.5
          },
          "type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "INBOUND",
              "OUTBOUND"
            ],
            "description": "Direction of the call"
          },
          "result": {
            "type": "string",
            "enum": [
              "ANSWERED",
              "VOICEMAIL",
              "TRANSFERRED_AI",
              "TRANSFERRED_EXTERNAL",
              "BLOCKED",
              "FAILED",
              "FAILED_EXTERNAL",
              "RECEIVED",
              "CLOSED"
            ],
            "description": "The outcome of the call. For outbound calls that reached voicemail, this will be VOICEMAIL regardless of the routing result. Common values: ANSWERED (call was answered), VOICEMAIL (call went to voicemail), TRANSFERRED_AI (transferred to AI agent), BLOCKED (call was blocked)",
            "example": "ANSWERED"
          },
          "summary": {
            "type": "string",
            "nullable": true,
            "description": "AI-generated summary of the call conversation",
            "example": "Customer inquired about order status"
          },
          "tag": {
            "type": "string",
            "nullable": true,
            "description": "Tag/category assigned to the call",
            "example": "support"
          },
          "recording_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "URL to access the call recording"
          },
          "start_date": {
            "type": "string",
            "format": "date-time",
            "description": "When the call started (ISO 8601 format)",
            "example": "2024-01-15T10:30:00"
          },
          "transcript": {
            "type": "array",
            "nullable": true,
            "description": "Transcript of the call conversation",
            "items": {
              "$ref": "#/components/schemas/TranscriptRow"
            }
          }
        }
      },
      "TranscriptRow": {
        "type": "object",
        "description": "A single row in the call transcript",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "AGENT",
              "EXTERNAL",
              "USER"
            ],
            "description": "The source of this transcript entry (AGENT for AI assistant, EXTERNAL for the caller, USER for the Allo user)"
          },
          "text": {
            "type": "string",
            "description": "The transcribed text content",
            "example": "Hello, how can I help you today?"
          },
          "time": {
            "type": "string",
            "format": "date-time",
            "description": "When this transcript entry occurred (ISO 8601 format)",
            "example": "2024-01-15T10:30:15"
          },
          "start_seconds": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Start time of this segment in seconds from call start",
            "example": 15.0
          },
          "end_seconds": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "End time of this segment in seconds from call start",
            "example": 18.5
          }
        }
      },
      "SearchContactsApiResponse": {
        "type": "object",
        "description": "Standard response wrapper for paginated contact results",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "results": {
                "type": "array",
                "nullable": true,
                "items": {
                  "$ref": "#/components/schemas/ContactWithEngagementApiResponse"
                }
              },
              "metadata": {
                "$ref": "#/components/schemas/PaginationMeta"
              }
            }
          }
        }
      },
      "ContactWithEngagementApiResponse": {
        "type": "object",
        "description": "A contact record with engagement information",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique contact identifier",
            "example": "cnt_abc123"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "First name",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name",
            "example": "Doe"
          },
          "company": {
            "type": "object",
            "nullable": true,
            "description": "Company information",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true,
                "example": "Acme Corp"
              },
              "id": {
                "type": "string",
                "nullable": true,
                "example": "com_xyz789"
              }
            }
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title",
            "example": "Manager"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Website URL"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Contact status",
            "example": "active"
          },
          "is_archived": {
            "type": "boolean",
            "description": "Whether the contact is archived"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the contact was created"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the contact was last updated"
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of phone numbers",
            "example": [
              "+1234567890"
            ]
          },
          "is_whitelisted": {
            "type": "boolean",
            "description": "Whether the contact is whitelisted"
          },
          "last_activity_date": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Date of the last activity"
          },
          "engagement": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ENGAGED",
              "COOLING",
              "COLD"
            ],
            "description": "Engagement level of the contact"
          }
        }
      },
      "CreateContactRequest": {
        "type": "object",
        "description": "Request body for creating a new contact",
        "required": [
          "numbers"
        ],
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "First name",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name",
            "example": "Doe"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title",
            "example": "CEO"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Website URL",
            "example": "https://acme.com"
          },
          "emails": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Email addresses",
            "example": [
              "john@acme.com"
            ]
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Phone numbers (at least one required, E.164 format)",
            "example": [
              "+15551234567"
            ]
          }
        }
      },
      "UpdateContactRequest": {
        "type": "object",
        "description": "Request body for updating an existing contact. Only provided fields will be updated.",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "First name"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Website URL"
          },
          "emails": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Email addresses (replaces all existing emails)"
          },
          "numbers": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Phone numbers (replaces all existing numbers)"
          }
        }
      },
      "ContactApiResponse": {
        "type": "object",
        "description": "Standard response wrapper for a single contact",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ContactWithEngagementApiResponse"
          }
        }
      },
      "SendSMSRequest": {
        "type": "object",
        "description": "Request body for sending an SMS message (US)",
        "required": [
          "from",
          "to",
          "message"
        ],
        "properties": {
          "from": {
            "type": "string",
            "description": "Your Allo phone number (must be owned by your account)",
            "example": "+1234567890"
          },
          "to": {
            "type": "string",
            "description": "Recipient phone number (E.164 format, same country as 'from')",
            "example": "+0987654321"
          },
          "message": {
            "type": "string",
            "description": "Message content",
            "minLength": 1,
            "maxLength": 1000,
            "example": "Hello, this is a test message"
          }
        }
      },
      "SendSMSFranceRequest": {
        "type": "object",
        "description": "Request body for sending an SMS message in France using a verified Sender ID",
        "required": [
          "sender_id",
          "to",
          "message"
        ],
        "properties": {
          "sender_id": {
            "type": "string",
            "description": "Your verified Sender ID (must be verified by the Allo team). This is an alphanumeric identifier that will appear as the sender of the SMS.",
            "example": "MyCompany"
          },
          "to": {
            "type": "string",
            "description": "Recipient phone number in France (E.164 format, must start with +33)",
            "example": "+33612345678"
          },
          "message": {
            "type": "string",
            "description": "Message content",
            "minLength": 1,
            "maxLength": 1000,
            "example": "Bonjour, ceci est un message de test"
          }
        }
      },
      "SendSMSResponse": {
        "type": "object",
        "description": "Standard response wrapper for sent SMS",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TextMessageApiResponse"
          }
        }
      },
      "TextMessageApiResponse": {
        "type": "object",
        "description": "Sent SMS message details",
        "properties": {
          "from_number": {
            "type": "string",
            "nullable": true,
            "description": "Phone number that sent the message. Null when sender_id is used instead.",
            "example": "+1234567890"
          },
          "sender_id": {
            "type": "string",
            "nullable": true,
            "description": "Sender ID used for the message (alphanumeric identifier). Only populated when sending with a verified Sender ID (e.g., for France SMS). Null when from_number is used.",
            "example": "MyCompany"
          },
          "to_number": {
            "type": "string",
            "description": "Phone number that received the message",
            "example": "+0987654321"
          },
          "type": {
            "type": "string",
            "enum": [
              "OUTBOUND"
            ],
            "description": "Direction of the message (always OUTBOUND for sent messages)"
          },
          "content": {
            "type": "string",
            "description": "Content of the SMS message",
            "example": "Hello, this is a test message"
          },
          "start_date": {
            "type": "string",
            "format": "date-time",
            "description": "When the message was sent",
            "example": "2024-01-15T10:30:00"
          }
        }
      },
      "SearchMetadata": {
        "type": "object",
        "description": "Pagination metadata for calls endpoint",
        "properties": {
          "total_pages": {
            "type": "integer",
            "example": 5
          },
          "current_page": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "description": "Pagination metadata wrapper for contacts endpoint",
        "nullable": true,
        "properties": {
          "pagination": {
            "type": "object",
            "properties": {
              "total_pages": {
                "type": "integer",
                "example": 5
              },
              "current_page": {
                "type": "integer",
                "example": 0
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code identifying the type of error"
          },
          "details": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "description": "Additional error details, or null if not applicable"
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "field": {
            "type": "string"
          }
        }
      },
      "GetNumbersResponse": {
        "type": "object",
        "description": "Standard response wrapper containing list of phone numbers",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PhoneNumberApiResponse"
            }
          }
        }
      },
      "PhoneNumberApiResponse": {
        "type": "object",
        "description": "An Allo phone number with basic information",
        "properties": {
          "number": {
            "type": "string",
            "nullable": true,
            "description": "Phone number in E.164 format",
            "example": "+1234567890"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display name for the phone number",
            "example": "Main Line"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "Two-letter country code (ISO 3166-1 alpha-2)",
            "example": "US"
          },
          "is_shared_number": {
            "type": "boolean",
            "description": "Whether this number is shared across team members"
          }
        }
      },
      "CallFlow": {
        "type": "object",
        "description": "A version of a phone number's call flow.",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "The call flow version ID. Null for a synthesized (never-persisted) flow.",
            "example": "cflv-abc123"
          },
          "flow_id": {
            "type": "string",
            "nullable": true,
            "description": "The parent call flow ID. Null for a synthesized flow.",
            "example": "cflw-abc123"
          },
          "version": {
            "type": "integer",
            "description": "Monotonic version number within the flow.",
            "example": 3
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "PUBLISHED",
              "SYNTHESIZED"
            ],
            "description": "DRAFT (working copy), PUBLISHED (live), or SYNTHESIZED (in-memory representation of a legacy IVR-only line).",
            "example": "PUBLISHED"
          },
          "lock_version": {
            "type": "integer",
            "description": "Optimistic-concurrency token; pass it back on the next draft save.",
            "example": 0
          },
          "schema_version": {
            "type": "integer",
            "description": "The call flow schema version this definition conforms to.",
            "example": 1
          },
          "engine_subset": {
            "type": "string",
            "enum": [
              "NESTED_IVR",
              "FULL_FLOW"
            ],
            "example": "FULL_FLOW",
            "description": "`FULL_FLOW` runs the whole tree on live calls. `NESTED_IVR` runs only the root phone menu: its keys that lead to a nested menu, a condition or a voicemail node do nothing."
          },
          "number": {
            "type": "string",
            "nullable": true,
            "description": "E.164 of the line this flow routes. Null for a never-persisted SYNTHESIZED flow.",
            "example": "+14155551234"
          },
          "confirmation_url": {
            "type": "string",
            "nullable": true,
            "description": "A link where a signed-in user reviews this draft and publishes it. Present only on a `DRAFT` (a `PUBLISHED` or `SYNTHESIZED` version has nothing to confirm). Use it when a person should approve the change; to go live without one, call `POST /v2/api/numbers/{number}/call_flow/publish`. Treat it as opaque: pass it through verbatim, and never construct or parse it.",
            "example": "https://app.withallo.com/call-flow-draft/cflv-abc123"
          },
          "entry_node_id": {
            "type": "string",
            "description": "The id of the entry node in `definition.nodes`.",
            "example": "node-22"
          },
          "definition": {
            "type": "object",
            "description": "The call flow tree document (opaque; camelCase keys).",
            "additionalProperties": true
          }
        }
      },
      "GetContactContextResponse": {
        "type": "object",
        "description": "Standard response wrapper for contact context",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ContactContextApiResponse"
          }
        }
      },
      "ContactContextApiResponse": {
        "type": "object",
        "description": "Comprehensive contact context including integration data and activity",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique contact identifier",
            "example": "cnt_abc123"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "First name",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name",
            "example": "Doe"
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of phone numbers",
            "example": [
              "+1234567890"
            ]
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of email addresses",
            "example": [
              "john@acme.com"
            ]
          },
          "company": {
            "type": "object",
            "nullable": true,
            "description": "Company information",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true,
                "example": "Acme Corp"
              },
              "id": {
                "type": "string",
                "nullable": true,
                "example": "com_xyz789"
              }
            }
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title",
            "example": "CEO"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Website URL",
            "example": "https://acme.com"
          },
          "integration_data": {
            "type": "object",
            "description": "Data from connected CRM integrations, keyed by integration type (e.g., HUBSPOT, SALESFORCE, PIPEDRIVE)",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": true
            },
            "example": {
              "HUBSPOT": {
                "contact_id": "12345",
                "deal_stage": "Negotiation"
              }
            }
          },
          "custom_properties": {
            "type": "object",
            "nullable": true,
            "description": "Custom properties defined for this contact",
            "additionalProperties": true,
            "example": {
              "preferred_language": "English",
              "vip_status": true
            }
          },
          "engagement": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ENGAGED",
              "COOLING",
              "COLD"
            ],
            "description": "Engagement level of the contact. Only included when `extend=engagement` is specified."
          },
          "activity": {
            "type": "array",
            "nullable": true,
            "description": "Recent communication activities with this contact (calls and SMS). Only included when `extend=activity` is specified.",
            "items": {
              "$ref": "#/components/schemas/ContactActivityApiResponse"
            }
          },
          "conversation_url": {
            "type": "string",
            "description": "URL path to retrieve the full conversation history for this contact",
            "example": "/v1/api/contact/cnt_abc123/conversation"
          }
        }
      },
      "ContactActivityApiResponse": {
        "type": "object",
        "description": "A communication activity (call or SMS) with a contact",
        "required": [
          "type",
          "made_at"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "INBOUND_CALL",
              "OUTBOUND_CALL",
              "INBOUND_SMS",
              "OUTBOUND_SMS"
            ],
            "description": "Type of communication activity. Possible values:\n- `INBOUND_CALL`: An incoming call from the contact\n- `OUTBOUND_CALL`: An outgoing call to the contact\n- `INBOUND_SMS`: An incoming SMS from the contact\n- `OUTBOUND_SMS`: An outgoing SMS to the contact"
          },
          "made_by": {
            "type": "string",
            "nullable": true,
            "description": "Name of the team member who handled the activity",
            "example": "John Doe"
          },
          "made_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the activity occurred (ISO 8601 format)",
            "example": "2024-01-15T10:30:00"
          },
          "allo_number": {
            "type": "string",
            "nullable": true,
            "description": "The Allo phone number used for the call. Only present for call activities (INBOUND_CALL, OUTBOUND_CALL).",
            "example": "+1234567890"
          },
          "content": {
            "type": "string",
            "nullable": true,
            "description": "The content/text of the SMS message. Only present for SMS activities (INBOUND_SMS, OUTBOUND_SMS).",
            "example": "Hello, this is a test message"
          }
        }
      },
      "GetContactConversationResponse": {
        "type": "object",
        "description": "Standard response wrapper for contact conversation",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ConversationApiResponse"
          }
        }
      },
      "ConversationApiResponse": {
        "type": "object",
        "description": "Paginated conversation history with calls and messages",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationItemApiResponse"
            },
            "description": "List of conversation items (calls and messages)"
          },
          "metadata": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "ConversationItemApiResponse": {
        "type": "object",
        "description": "A single item in the conversation (either a call or a message)",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "CALL",
              "TEXT_MESSAGE"
            ],
            "description": "Type of conversation item"
          },
          "call": {
            "$ref": "#/components/schemas/CallApiResponse",
            "nullable": true,
            "description": "Call details (only present when type is CALL)"
          },
          "message": {
            "$ref": "#/components/schemas/TextMessageApiResponse",
            "nullable": true,
            "description": "Message details (only present when type is TEXT_MESSAGE)"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "size": {
            "type": "integer"
          },
          "total_count": {
            "type": "integer"
          },
          "total_pages": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "PaginatedResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "cnt-abc123"
          },
          "name": {
            "type": "string",
            "example": "Sarah Johnson"
          },
          "company": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "example": "com-xyz789"
              },
              "name": {
                "type": "string",
                "example": "Acme Corp"
              }
            }
          },
          "deals": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "dea-def456"
                },
                "name": {
                  "type": "string",
                  "example": "Enterprise Plan"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "OPEN",
                    "WON",
                    "LOST"
                  ]
                }
              }
            }
          }
        }
      },
      "UserRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "usr-abc123"
          },
          "name": {
            "type": "string",
            "example": "John"
          },
          "email": {
            "type": "string",
            "example": "john@acme.com"
          }
        }
      },
      "TranscriptEntry": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "USER",
              "EXTERNAL"
            ]
          },
          "time": {
            "type": "string",
            "format": "date-time"
          },
          "text": {
            "type": "string"
          }
        }
      },
      "ConversationItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "cll-abc123"
          },
          "type": {
            "type": "string",
            "enum": [
              "CALL",
              "SMS"
            ],
            "description": "`CALL` for a call, `SMS` for a message. Faxes are `SMS` items with `message_type` set to `FAX`."
          },
          "direction": {
            "type": "string",
            "enum": [
              "INBOUND",
              "OUTBOUND"
            ]
          },
          "allo_number": {
            "type": "string",
            "example": "+14155550100"
          },
          "contact_number": {
            "type": "string",
            "example": "+14155551234"
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "user": {
            "$ref": "#/components/schemas/UserRef"
          },
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "duration": {
            "type": "integer",
            "nullable": true,
            "description": "Total call length in seconds, from when the call starts (ringing included) to when it ends. For the talk time shown in the Allo app, use `recording_duration`."
          },
          "result": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ANSWERED",
              "VOICEMAIL",
              "TRANSFERRED_AI",
              "TRANSFERRED_EXTERNAL",
              "BLOCKED",
              "FAILED",
              "FAILED_EXTERNAL",
              "RECEIVED",
              "CLOSED"
            ],
            "description": "Call outcome. Null for SMS items. An outbound call that reached voicemail reports `VOICEMAIL`. `FAILED_EXTERNAL` only appears on older calls. New values may be added: handle unknown values gracefully."
          },
          "detected_outbound_voicemail": {
            "type": "boolean",
            "nullable": true,
            "description": "Outbound calls only. `true` when the call was answered by an answering machine, `false` when a human answered, `null` when no detection ran for this call (never set on inbound calls or SMS). Note that `result` stays `ANSWERED` for these calls — the carrier considers a machine pickup an answer."
          },
          "voicemail_left": {
            "type": "boolean",
            "nullable": true,
            "description": "Outbound calls only. `true` when a message was actually left on the voicemail, `false` when the caller hung up without leaving one, `null` when not determined. Independent of `detected_outbound_voicemail`: either can be set without the other."
          },
          "recording_url": {
            "type": "string",
            "nullable": true,
            "description": "Link to the call recording. Absent when the call was not recorded, and for accounts sold under a white-label partner's brand: use `recording_download_url` there."
          },
          "recording_download_url": {
            "type": "string",
            "nullable": true,
            "description": "Signed link that downloads the recording with no login, valid for 48 hours. Returned only for lines of accounts created by a partner, never for a call on a HIPAA-enabled team, and only when the key's user can play the recording. For a fresh link, call `GET /v2/api/conversations/items/{id}/recording`."
          },
          "recording_download_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When `recording_download_url` stops working."
          },
          "recording_duration": {
            "type": "integer",
            "nullable": true,
            "description": "Length of the call recording in seconds: the talk time, excluding ringing. This is the duration shown in the Allo app for recorded calls. `null` when the call was not recorded."
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "extracted_data": {
            "type": "object",
            "nullable": true,
            "description": "Contact details Allo's AI picked up from the call transcript, under a `contact` object: `name`, `company`, `job_title`, `website`, `address` (strings, empty when not mentioned) and `emails` (array). Null for SMS items and for calls Allo has not analyzed.",
            "properties": {
              "contact": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "company": {
                    "type": "string"
                  },
                  "job_title": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  },
                  "address": {
                    "type": "string"
                  },
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "additionalProperties": true,
            "example": {
              "contact": {
                "name": "Marie Dupont",
                "company": "Vibrant Events",
                "job_title": "Office manager",
                "website": "vibrantevents.com",
                "address": "12 rue de la Paix, Paris",
                "emails": [
                  "marie@vibrantevents.com"
                ]
              }
            }
          },
          "data_collected": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "string"
            },
            "description": "Legacy field kept for compatibility. An empty object on current calls. Null for SMS items."
          },
          "transcript": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/TranscriptEntry"
            }
          },
          "content": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true,
            "enum": [
              "PENDING",
              "SENT",
              "DELIVERED",
              "FAILED"
            ]
          },
          "message_type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "SMS",
              "MMS",
              "WHATSAPP",
              "FAX"
            ]
          },
          "attachments": {
            "type": "array",
            "nullable": true,
            "description": "Photos and other files sent with the message, in the order they were sent. For a fax, the faxed PDF. An empty array for a message with no files, and `null` for a call.",
            "items": {
              "$ref": "#/components/schemas/MessageAttachment"
            }
          },
          "page_count": {
            "type": "integer",
            "nullable": true,
            "description": "Number of pages of a fax. `null` for calls, for messages that are not faxes, and for a fax whose page count is not known yet.",
            "example": 4
          }
        }
      },
      "MessageAttachment": {
        "type": "object",
        "properties": {
          "file_name": {
            "type": "string",
            "example": "IMG_0412.jpg"
          },
          "content_type": {
            "type": "string",
            "description": "MIME type of the file.",
            "example": "image/jpeg"
          },
          "file_size": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Size of the file in bytes.",
            "example": 245760
          },
          "download_url": {
            "type": "string",
            "nullable": true,
            "description": "Signed link that downloads the file with no login, valid for 30 minutes. `null` for a message on a HIPAA-enabled team. For a fresh link, fetch the item again."
          },
          "download_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When `download_url` stops working."
          }
        }
      },
      "ConversationSummary": {
        "type": "object",
        "properties": {
          "contact_number": {
            "type": "string",
            "example": "+14155551234"
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "last_activity": {
            "type": "string",
            "format": "date-time"
          },
          "last_item": {
            "$ref": "#/components/schemas/ConversationItem"
          },
          "pinned": {
            "type": "boolean",
            "description": "Whether the caller pinned this conversation.",
            "example": false
          },
          "allo_number": {
            "type": "string",
            "description": "Allo line of the conversation (E.164).",
            "example": "+14155550100",
            "nullable": true
          }
        },
        "required": [
          "pinned"
        ]
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "contact_number": {
            "type": "string",
            "example": "+14155551234"
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "last_activity": {
            "type": "string",
            "format": "date-time"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationItem"
            }
          }
        }
      },
      "ItemSearchRequest": {
        "type": "object",
        "properties": {
          "allo_number": {
            "type": "string"
          },
          "contact_number": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": [
              "INBOUND",
              "OUTBOUND"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "CALL",
              "SMS",
              "FAX",
              "ALL"
            ],
            "description": "`SMS` returns all messages, faxes included. `FAX` returns only faxes.",
            "default": "ALL"
          },
          "result": {
            "type": "string",
            "enum": [
              "ANSWERED",
              "VOICEMAIL",
              "TRANSFERRED"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unread": {
            "type": "boolean"
          },
          "unresponded": {
            "type": "boolean"
          },
          "search": {
            "type": "string",
            "description": "Keyword search (not natural language). Extract keywords from the user's question. Terms are AND'd with prefix matching — 'billing refund' matches items containing both words, 'bill' matches 'billing'. Searches across call transcripts, summaries, and SMS content."
          },
          "sort": {
            "type": "string",
            "enum": [
              "DATE_DESC",
              "DATE_ASC",
              "RELEVANCE"
            ],
            "default": "DATE_DESC"
          },
          "extend": {
            "type": "string"
          },
          "page": {
            "type": "integer",
            "default": 1
          },
          "size": {
            "type": "integer",
            "default": 20,
            "maximum": 100
          },
          "date": {
            "$ref": "#/components/schemas/AnalyticsDateRange",
            "description": "Date range to filter by"
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "usr-abc123"
          },
          "name": {
            "type": "string",
            "example": "Adrien"
          },
          "email": {
            "type": "string",
            "example": "adrien@company.com"
          },
          "role": {
            "type": "string",
            "enum": [
              "ADMIN",
              "MANAGER",
              "MEMBER"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "BLOCKED"
            ]
          },
          "image_url": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Tag": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "tag-abc123"
          },
          "name": {
            "type": "string",
            "example": "qualified"
          },
          "color": {
            "type": "string",
            "example": "#00AA00"
          }
        }
      },
      "CallSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Call ID this summary belongs to",
            "example": "cll-abc123"
          },
          "content": {
            "type": "string",
            "nullable": true,
            "description": "Markdown summary content"
          },
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "Optimistic-lock version. Increments on every successful update.",
            "example": 4
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2026-05-12T14:32:11"
          },
          "updated_by": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "example": "usr-abc123"
              },
              "name": {
                "type": "string",
                "nullable": true,
                "example": "Alex Kim"
              }
            }
          }
        }
      },
      "PhoneNumber": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string",
            "nullable": true,
            "description": "Phone number in E.164 format (null for sender IDs)",
            "example": "+14155550100"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display label",
            "example": "Sales US"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "ISO country code",
            "example": "US"
          },
          "type": {
            "type": "string",
            "enum": [
              "NUMBER",
              "SENDER_ID"
            ],
            "description": "Whether this is a phone number or a sender ID"
          },
          "capabilities": {
            "type": "array",
            "description": "Supported capabilities for this number.",
            "items": {
              "type": "string",
              "enum": [
                "VOICE",
                "SMS",
                "MMS"
              ]
            },
            "example": [
              "VOICE",
              "SMS",
              "MMS"
            ]
          },
          "users": {
            "type": "array",
            "description": "Team members with access to this number",
            "items": {
              "$ref": "#/components/schemas/UserRef"
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "request_id": {
                "type": "string"
              },
              "retry_after_seconds": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      },
      "MetricValue": {
        "type": "object",
        "properties": {
          "value": {
            "type": "number",
            "description": "Current period value"
          },
          "previous": {
            "type": "number",
            "nullable": true,
            "description": "Previous period value"
          },
          "change": {
            "type": "number",
            "nullable": true,
            "description": "Percentage change vs previous period (e.g. 0.15 = +15%)"
          }
        }
      },
      "UserBreakdown": {
        "type": "object",
        "properties": {
          "user": {
            "$ref": "#/components/schemas/UserRef"
          },
          "calls": {
            "$ref": "#/components/schemas/MetricValue"
          },
          "talk_time_seconds": {
            "$ref": "#/components/schemas/MetricValue"
          },
          "calls_over_1_min": {
            "$ref": "#/components/schemas/MetricValue"
          },
          "answer_rate": {
            "$ref": "#/components/schemas/MetricValue"
          }
        }
      },
      "FunnelStage": {
        "type": "object",
        "properties": {
          "count": {
            "$ref": "#/components/schemas/MetricValue"
          },
          "rate": {
            "type": "number",
            "nullable": true,
            "description": "Percentage of total dials (e.g. 0.29 = 29%)"
          }
        }
      },
      "HeatmapCell": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string",
            "enum": [
              "MONDAY",
              "TUESDAY",
              "WEDNESDAY",
              "THURSDAY",
              "FRIDAY",
              "SATURDAY",
              "SUNDAY"
            ]
          },
          "hour": {
            "type": "integer",
            "description": "Hour of day (0-23)"
          },
          "value": {
            "type": "integer"
          }
        }
      },
      "TimeSeriesPoint": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "value": {
            "type": "number"
          }
        }
      },
      "OutboundDrilldownItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Call ID",
            "example": "cll-abc123"
          },
          "user": {
            "$ref": "#/components/schemas/UserRef"
          },
          "allo_number": {
            "type": "string",
            "example": "+14155550100"
          },
          "allo_number_label": {
            "type": "string",
            "example": "Sales US"
          },
          "contact_number": {
            "type": "string",
            "example": "+14155551234"
          },
          "stage": {
            "type": "string",
            "enum": [
              "DIAL",
              "CONNECTED",
              "CONVERSATION",
              "CONVERSION"
            ]
          },
          "voicemail": {
            "type": "boolean"
          },
          "duration": {
            "type": "integer",
            "description": "Duration in seconds"
          },
          "date": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AnalyticsDateRange": {
        "type": "object",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date",
            "description": "Start date",
            "example": "2026-03-25"
          },
          "to": {
            "type": "string",
            "format": "date",
            "description": "End date",
            "example": "2026-04-21"
          }
        }
      },
      "DialingQueue": {
        "type": "object",
        "description": "A user's Power Dialer queue with its configuration and numbers.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique queue identifier (KSUID with `pdl` prefix)"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the queue"
          },
          "creator_id": {
            "type": "string",
            "description": "User ID of the queue creator — the user (or API key owner) that created the queue."
          },
          "assignee_id": {
            "type": "string",
            "nullable": true,
            "description": "User ID of the user expected to run the queue. `GET /current` returns the queue where this matches the authenticated user (or the user resolved from `user_id` / `email`). Defaults to the creator when none was specified at creation time."
          },
          "voicemail_handling": {
            "type": "string",
            "enum": [
              "SKIP",
              "NO_SKIP"
            ],
            "description": "How the Power Dialer reacts when the call lands in voicemail. `SKIP` advances to the next number; `NO_SKIP` keeps the user on the call."
          },
          "do_not_disturb": {
            "type": "string",
            "enum": [
              "ENABLED",
              "DISABLED"
            ],
            "description": "When `ENABLED`, incoming calls are silenced while the queue is being run."
          },
          "numbers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueNumber"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DialingQueueMeta": {
        "type": "object",
        "description": "Power Dialer queue metadata, without its numbers. Returned under the `queue` key of `GET /current`; the numbers themselves are the paginated `data`.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique queue identifier (KSUID with `pdl` prefix)"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the queue"
          },
          "creator_id": {
            "type": "string",
            "description": "User ID of the queue creator."
          },
          "assignee_id": {
            "type": "string",
            "nullable": true,
            "description": "User ID of the user expected to run the queue."
          },
          "voicemail_handling": {
            "type": "string",
            "enum": [
              "SKIP",
              "NO_SKIP"
            ],
            "description": "How the Power Dialer reacts when the call lands in voicemail."
          },
          "do_not_disturb": {
            "type": "string",
            "enum": [
              "ENABLED",
              "DISABLED"
            ],
            "description": "When `ENABLED`, incoming calls are silenced while the queue is being run."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "QueueNumber": {
        "type": "object",
        "description": "A phone number entry in a Power Dialer queue",
        "properties": {
          "number_to": {
            "type": "string",
            "description": "E.164 destination phone number"
          },
          "position": {
            "type": "integer",
            "description": "Order within the queue (0-based)"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "call_start_date": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the user started calling this entry. `null` if the entry is still unassigned."
          },
          "call_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the call placed for this entry (`cll-*`). `null` until a call is placed."
          },
          "routing_result": {
            "type": "string",
            "nullable": true,
            "enum": [
              "FAILED",
              "RECEIVED",
              "BLOCKED",
              "ANSWERED",
              "TRANSFERRED_BLAND",
              "TRANSFERRED_ELEVEN_LABS",
              "TRANSFERRED_EXTERNAL",
              "FAILED_EXTERNAL",
              "VOICEMAIL",
              "CLOSED"
            ],
            "description": "Final routing outcome of the call placed for this entry."
          },
          "sync_status": {
            "type": "string",
            "enum": [
              "NOT_SYNCED",
              "PROCESSING",
              "SYNCED"
            ],
            "description": "State of contact creation/sync for this entry."
          },
          "detected_outbound_voicemail": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the call was detected as having reached a voicemail box."
          },
          "not_reached_destination_reason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "BUSY",
              "CALLEE_TEMPORARILY_UNAVAILABLE",
              "RING_TIMEOUT",
              "NOT_IN_SERVICE",
              "DECLINED",
              "NETWORK_ERROR"
            ],
            "description": "Why the call did not reach the contact (only set when applicable)."
          },
          "voicemail_left": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the user left a voicemail on this entry."
          },
          "call_status": {
            "type": "string",
            "nullable": true,
            "enum": [
              "QUEUED",
              "SKIPPED",
              "VOICEMAIL",
              "CONNECTED",
              "TRANSFERRED",
              "NO_ANSWER",
              "BUSY",
              "WRONG_NUMBER"
            ],
            "description": "Status of this entry, derived from the call placed for it. `QUEUED`: no call yet, or the call is still in progress. `SKIPPED`: skipped in the Power Dialer with no call placed (if a call is placed for it later, the status follows that call). `VOICEMAIL`: the call reached a voicemail box. `CONNECTED`: the call was answered at route level (`routing_result` is `ANSWERED`), no voicemail was detected and no `not_reached_destination_reason` is set; this can over-report a real conversation. `TRANSFERRED`: the call was transferred. `BUSY`: the destination was busy. `WRONG_NUMBER`: the destination is not in service. `NO_ANSWER`: the call ended without an answer, including the other `not_reached_destination_reason` values and any other final route status (failed, blocked, closed, handled by call flow)."
          }
        }
      },
      "AppendQueueNumbersRequest": {
        "type": "object",
        "required": [
          "numbers"
        ],
        "properties": {
          "numbers": {
            "type": "array",
            "description": "Numbers to append to the queue. Each entry requires a phone number; contact metadata is optional.",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "number"
              ],
              "properties": {
                "number": {
                  "type": "string",
                  "description": "Phone number in any format — will be normalized to E.164"
                },
                "name": {
                  "type": "string",
                  "nullable": true,
                  "description": "First name (optional — used to create or match a contact)"
                },
                "last_name": {
                  "type": "string",
                  "nullable": true,
                  "description": "Last name"
                },
                "company": {
                  "type": "string",
                  "nullable": true,
                  "description": "Company name — matched by name within the team (case-insensitive). If no matching company exists, one is created automatically."
                },
                "website": {
                  "type": "string",
                  "nullable": true,
                  "description": "Website URL"
                },
                "job_title": {
                  "type": "string",
                  "nullable": true,
                  "description": "Job title"
                },
                "emails": {
                  "type": "array",
                  "nullable": true,
                  "items": {
                    "type": "string"
                  },
                  "description": "Email addresses"
                },
                "addresses": {
                  "type": "array",
                  "nullable": true,
                  "items": {
                    "type": "string"
                  },
                  "description": "Physical addresses"
                },
                "custom_attributes": {
                  "type": "object",
                  "nullable": true,
                  "additionalProperties": {
                    "type": "string",
                    "nullable": true
                  },
                  "description": "Values for the team's existing person custom fields, keyed by field `key` (see [GET /v2/api/crm/attributes](/en/v2/api-reference/crm/list-attributes)). Values are strings: `NUMBER` as a number, `DATE` as `YYYY-MM-DD`, an ISO date-time, or `03/04/2026`, `03-04-2026`, `03.04.2026` (4-digit year, read with `date_order`), `BOOLEAN` as `true`/`false`, `1`/`0`, `yes`/`no`, `y`/`n` or `oui`/`non` in any case, `DROPDOWN` as an option label or key. Blank values are ignored. Fields are never created: an unknown or deleted key is ignored (the number is still added with its known attributes) and reported in `ignored_custom_attributes` in the response, a value that does not fit the field type skips it with `INVALID_CUSTOM_ATTRIBUTE_VALUE`. On an existing contact, only empty fields are filled.",
                  "example": {
                    "lead_source": "Webinar",
                    "deal_size": "1200",
                    "next_meeting": "2026-11-03"
                  }
                }
              }
            }
          },
          "user_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional. ID of a teammate whose queue should receive the numbers. The teammate must belong to the same team as the API key owner. Wins over `email` when both are provided. Resolve teammate ids via [GET /v2/api/users](/en/v2/api-reference/users/list-users).",
            "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "description": "Optional. Email of a teammate whose queue should receive the numbers. Ignored when `user_id` is also supplied.",
            "example": "teammate@acme.com"
          },
          "date_order": {
            "type": "string",
            "nullable": true,
            "enum": [
              "DAY_FIRST",
              "MONTH_FIRST"
            ],
            "description": "Optional. How to read numeric `DATE` values in `custom_attributes` such as `03/04/2026`: `DAY_FIRST` (3 April) or `MONTH_FIRST` (4 March). Applies to every date field in the request. When absent, each date field is read in the order its values settle (a `13/04/2026` can only be day first); when none settle it, your phone number's country decides: month first for the US, day first everywhere else.",
            "example": "DAY_FIRST"
          }
        }
      },
      "AppendQueueNumbersResponse": {
        "type": "object",
        "properties": {
          "added": {
            "type": "array",
            "description": "Numbers that were successfully appended",
            "items": {
              "$ref": "#/components/schemas/QueueNumber"
            }
          },
          "skipped": {
            "type": "array",
            "description": "Numbers that were skipped (e.g. invalid format)",
            "items": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string",
                  "description": "The raw input number that was skipped"
                },
                "reason": {
                  "type": "string",
                  "enum": [
                    "INVALID_PHONE_NUMBER",
                    "UNKNOWN_CUSTOM_ATTRIBUTE",
                    "INVALID_CUSTOM_ATTRIBUTE_VALUE"
                  ],
                  "description": "Why the number was skipped. `UNKNOWN_CUSTOM_ATTRIBUTE` (deprecated, no longer returned): unknown `custom_attributes` keys are now ignored and listed in `ignored_custom_attributes`. `INVALID_CUSTOM_ATTRIBUTE_VALUE`: a `custom_attributes` value does not fit its field type, including an impossible date (`31/02/2026`), a 2-digit year or an unknown yes/no word."
                }
              }
            }
          },
          "ignored_custom_attributes": {
            "type": "array",
            "description": "Always present, empty when nothing was ignored. Added numbers whose `custom_attributes` had keys matching none of the team's active person custom fields. Those keys were dropped.",
            "items": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string",
                  "description": "The added number, in E.164 format",
                  "example": "+12125550010"
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The ignored `custom_attributes` keys",
                  "example": ["unknown_field"]
                }
              }
            }
          }
        }
      },
      "UpsertDialingQueueRequest": {
        "type": "object",
        "description": "Creates or updates the queue config. All fields are optional — only the fields you supply are touched. Pass `user_id` or `email` to act on a teammate's queue instead.",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "New queue name (1–255 characters)",
            "minLength": 1,
            "maxLength": 255
          },
          "voicemail_handling": {
            "type": "string",
            "nullable": true,
            "enum": [
              "SKIP",
              "NO_SKIP"
            ],
            "description": "How the Power Dialer reacts when the call hits voicemail."
          },
          "do_not_disturb": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ENABLED",
              "DISABLED"
            ],
            "description": "Silence inbound calls while running the queue."
          },
          "user_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional. ID of a teammate whose queue config should be updated. The teammate must belong to the same team as the API key owner. Wins over `email` when both are provided.",
            "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "description": "Optional. Email of a teammate whose queue config should be updated. Ignored when `user_id` is also supplied.",
            "example": "teammate@acme.com"
          }
        }
      },
      "ResetDialingQueueRequest": {
        "type": "object",
        "description": "Optional payload for resetting a queue. Send an empty body to reset your own queue without renaming.",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display name for the new queue (max 255 characters). Leave unset to create the queue without a name.",
            "maxLength": 255
          },
          "user_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional. ID of a teammate the new queue should be assigned to. The API key owner is recorded as `creator_id`. The teammate must belong to the same team as the API key owner. Wins over `email` when both are provided.",
            "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "description": "Optional. Email of a teammate the new queue should be assigned to. Ignored when `user_id` is also supplied.",
            "example": "teammate@acme.com"
          }
        }
      },
      "ClearQueueNumbersResponse": {
        "type": "object",
        "description": "Result of clearing numbers from a Power Dialer queue.",
        "properties": {
          "removed": {
            "type": "integer",
            "description": "Number of queue entries that were removed.",
            "example": 4
          }
        }
      },
      "AnalyticsBaseRequest": {
        "type": "object",
        "required": [
          "date"
        ],
        "properties": {
          "date": {
            "$ref": "#/components/schemas/AnalyticsDateRange"
          },
          "compare_date": {
            "$ref": "#/components/schemas/AnalyticsDateRange",
            "description": "Comparison period. Metrics will include change vs this period."
          },
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Filter by user IDs. Cannot be combined with allo_numbers."
          },
          "allo_numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Filter by Allo numbers (E.164). Cannot be combined with user_ids."
          }
        }
      },
      "OutboundAnalyticsRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AnalyticsBaseRequest"
          },
          {
            "type": "object",
            "properties": {
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Tag keys that define a conversion (e.g. ['meeting_booked', 'demo_scheduled'])"
              },
              "granularity": {
                "type": "string",
                "enum": [
                  "DAY",
                  "WEEK",
                  "MONTH"
                ],
                "default": "DAY",
                "description": "Time series granularity"
              },
              "extend": {
                "type": "string",
                "enum": [
                  "items"
                ],
                "description": "Include the list of outbound calls behind the funnel numbers. Requires `stage`."
              },
              "stage": {
                "type": "string",
                "enum": [
                  "DIAL",
                  "CONNECTED",
                  "CONVERSATION",
                  "CONVERSION"
                ],
                "description": "Filter drilldown items by funnel stage. Only used when `extend=items`."
              },
              "page": {
                "type": "integer",
                "default": 1,
                "description": "Page number for drilldown items. Only used when `extend=items`."
              },
              "size": {
                "type": "integer",
                "default": 20,
                "maximum": 100,
                "description": "Page size for drilldown items. Only used when `extend=items`."
              }
            }
          }
        ]
      },
      "CrmCompanyRef": {
        "type": "object",
        "nullable": true,
        "description": "Embedded company reference",
        "properties": {
          "id": {
            "type": "string",
            "description": "Company ID",
            "example": "com-xyz789"
          },
          "name": {
            "type": "string",
            "description": "Company name",
            "example": "Acme Corp"
          }
        }
      },
      "CrmPerson": {
        "type": "object",
        "description": "A person in the CRM",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique person identifier",
            "example": "per-abc123"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "First name",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name",
            "example": "Doe"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title",
            "example": "CEO"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Website URL",
            "example": "https://example.com"
          },
          "address": {
            "type": "string",
            "nullable": true,
            "description": "Postal address",
            "example": "123 Main St"
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Phone numbers in E.164 format",
            "example": [
              "+33612345678"
            ]
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Email addresses",
            "example": [
              "john@example.com"
            ]
          },
          "company": {
            "$ref": "#/components/schemas/CrmCompanyRef"
          },
          "interactions": {
            "type": "integer",
            "description": "Total number of interactions (calls + messages)",
            "example": 5
          },
          "last_activity_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the last activity",
            "example": "2026-04-28T10:30:00"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the person was created",
            "example": "2026-04-01T09:00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the person was last updated",
            "example": "2026-04-28T10:30:00"
          },
          "custom_attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Values of the person's custom attributes, keyed by attribute key. Always present, `{}` when there are none. Archived attributes and empty values are omitted. `NUMBER` values are decimals (`180` is returned as `180.0`), `DATE` values are `YYYY-MM-DD` and `DROPDOWN` values are the option key. Create the attributes first with `POST /v2/api/crm/attributes`.",
            "example": {
              "lead_source": "Webinar",
              "budget": 5000.0
            }
          }
        }
      },
      "CrmCompany": {
        "type": "object",
        "description": "A company in the CRM",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique company identifier",
            "example": "com-xyz789"
          },
          "name": {
            "type": "string",
            "description": "Company name",
            "example": "Acme Corp"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Company website URL",
            "example": "https://acme.com"
          },
          "industry": {
            "type": "string",
            "nullable": true,
            "description": "Industry sector",
            "example": "Technology"
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Phone numbers of the company, in E.164 format",
            "example": [
              "+33142000000"
            ]
          },
          "person_count": {
            "type": "integer",
            "description": "Number of people linked to this company",
            "example": 3
          },
          "interactions": {
            "type": "integer",
            "description": "Total number of interactions across all people in this company",
            "example": 12
          },
          "last_activity_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the last activity",
            "example": "2026-04-28T10:30:00"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the company was created",
            "example": "2026-04-01T09:00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the company was last updated",
            "example": "2026-04-28T10:30:00"
          },
          "custom_attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Values of the company's custom attributes, keyed by attribute key. Always present, `{}` when there are none. Archived attributes and empty values are omitted. `NUMBER` values are decimals (`180` is returned as `180.0`), `DATE` values are `YYYY-MM-DD` and `DROPDOWN` values are the option key. Create the attributes first with `POST /v2/api/crm/companies/attributes`.",
            "example": {
              "ping_pong_level": "advanced",
              "renewal_date": "2026-12-01"
            }
          }
        }
      },
      "CrmDeal": {
        "type": "object",
        "description": "A deal in the CRM",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique deal identifier",
            "example": "dea-def456"
          },
          "name": {
            "type": "string",
            "description": "Deal name",
            "example": "Enterprise Plan"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Current deal status",
            "example": "negotiation"
          },
          "amount": {
            "type": "number",
            "nullable": true,
            "description": "Deal monetary value",
            "example": 50000.0
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "description": "Three-letter ISO 4217 currency code",
            "example": "USD",
            "minLength": 3,
            "maxLength": 3
          },
          "closed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the deal was closed (ISO 8601)",
            "example": null
          },
          "company": {
            "$ref": "#/components/schemas/CrmCompanyRef"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the deal was created",
            "example": "2026-04-15T14:00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the deal was last updated",
            "example": "2026-04-28T10:30:00"
          }
        }
      },
      "CreatePersonRequest": {
        "type": "object",
        "description": "Request body for creating a person",
        "required": [
          "numbers"
        ],
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "First name",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name",
            "example": "Doe"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title",
            "example": "CEO"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Website URL",
            "example": "https://example.com"
          },
          "address": {
            "type": "string",
            "nullable": true,
            "description": "Postal address",
            "example": "123 Main St"
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Phone numbers in E.164 format. At least one number is required.",
            "minItems": 1,
            "example": [
              "+33612345678"
            ]
          },
          "emails": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Email addresses",
            "example": [
              "john@example.com"
            ]
          },
          "company_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the company to associate with",
            "example": "com-xyz789"
          },
          "allow_duplicate_number": {
            "type": "boolean",
            "description": "When true, allows creating a person even if the phone numbers are already assigned to another person. Defaults to false.",
            "default": false
          },
          "custom_attributes": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true,
            "description": "Values for the person's custom attributes, keyed by attribute key. `TEXT` takes a string, `NUMBER` a finite JSON number (numeric strings are rejected), `BOOLEAN` a JSON boolean, `DATE` a `YYYY-MM-DD` string or ISO datetime, and `DROPDOWN` an option key or label (case-insensitive). Send `null` to clear a value; keys you omit are left untouched, and `{}` or omitting the field changes nothing. An unknown or archived key, or a value of the wrong type, rejects the whole request with `CUSTOM_ATTRIBUTE_KEY_UNKNOWN` or `CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
            "example": {
              "lead_source": "Webinar",
              "budget": 5000
            }
          }
        }
      },
      "UpdatePersonRequest": {
        "type": "object",
        "description": "Request body for updating a person. Only provided fields will be updated.",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "First name"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Website URL"
          },
          "address": {
            "type": "string",
            "nullable": true,
            "description": "Postal address"
          },
          "numbers": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Phone numbers (replaces all existing numbers)"
          },
          "emails": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Email addresses (replaces all existing emails)"
          },
          "company_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the company to associate with"
          },
          "custom_attributes": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true,
            "description": "Values for the person's custom attributes, keyed by attribute key. `TEXT` takes a string, `NUMBER` a finite JSON number (numeric strings are rejected), `BOOLEAN` a JSON boolean, `DATE` a `YYYY-MM-DD` string or ISO datetime, and `DROPDOWN` an option key or label (case-insensitive). Send `null` to clear a value; keys you omit are left untouched, and `{}` or omitting the field changes nothing. An unknown or archived key, or a value of the wrong type, rejects the whole request with `CUSTOM_ATTRIBUTE_KEY_UNKNOWN` or `CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
            "example": {
              "lead_source": "Referral",
              "budget": null
            }
          }
        }
      },
      "SearchPeopleRequest": {
        "type": "object",
        "description": "Request body for searching people",
        "properties": {
          "filters": {
            "type": "object",
            "nullable": true,
            "description": "Named filters. All are combined with AND.",
            "properties": {
              "name": {
                "type": "string",
                "description": "Filter by first name (contains)"
              },
              "last_name": {
                "type": "string",
                "description": "Filter by last name (contains)"
              },
              "job_title": {
                "type": "string",
                "description": "Filter by job title (contains)"
              },
              "website": {
                "type": "string",
                "description": "Filter by website (contains)"
              },
              "company": {
                "type": "string",
                "description": "Filter by company name (contains)"
              },
              "phone_number": {
                "type": "string",
                "description": "Filter by phone number (exact match)"
              },
              "email": {
                "type": "string",
                "description": "Filter by email (contains)"
              },
              "deal_status": {
                "type": "string",
                "description": "Filter by deal status (exact match)"
              }
            }
          },
          "search": {
            "type": "string",
            "nullable": true,
            "description": "Free-text search across name, email, phone number, and company"
          },
          "sort": {
            "type": "string",
            "nullable": true,
            "enum": [
              "DATE_DESC",
              "DATE_ASC",
              "NAME_ASC",
              "NAME_DESC",
              "CREATED_DESC",
              "CREATED_ASC"
            ],
            "description": "Sort order (default: DATE_DESC)"
          },
          "page": {
            "type": "integer",
            "default": 1,
            "description": "Page number (1-indexed)"
          },
          "size": {
            "type": "integer",
            "default": 20,
            "maximum": 100,
            "description": "Results per page"
          }
        }
      },
      "CreateCompanyRequest": {
        "type": "object",
        "description": "Request body for creating a company",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Company name",
            "example": "Acme Corp"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Company website URL",
            "example": "https://acme.com"
          },
          "industry": {
            "type": "string",
            "nullable": true,
            "description": "Industry sector",
            "example": "Technology"
          },
          "numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Phone numbers of the company. Each number is normalized to E.164 and duplicates are merged. An invalid number rejects the request with `400 INVALID_REQUEST_BODY`, and the offending value is named in `errors`.",
            "example": [
              "+33142000000"
            ]
          },
          "custom_attributes": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true,
            "description": "Values for the company's custom attributes, keyed by attribute key. `TEXT` takes a string, `NUMBER` a finite JSON number (numeric strings are rejected), `BOOLEAN` a JSON boolean, `DATE` a `YYYY-MM-DD` string or ISO datetime, and `DROPDOWN` an option key or label (case-insensitive). Send `null` to clear a value; keys you omit are left untouched, and `{}` or omitting the field changes nothing. An unknown or archived key, or a value of the wrong type, rejects the whole request with `CUSTOM_ATTRIBUTE_KEY_UNKNOWN` or `CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
            "example": {
              "ping_pong_level": "Advanced",
              "renewal_date": "2026-12-01"
            }
          }
        }
      },
      "UpdateCompanyRequest": {
        "type": "object",
        "description": "Request body for updating a company. Only provided fields will be updated.",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Company name"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "Company website URL"
          },
          "industry": {
            "type": "string",
            "nullable": true,
            "description": "Industry sector"
          },
          "numbers": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Phone numbers of the company. A list replaces all existing numbers (numbers you leave out are removed), `[]` removes them all, and omitting the field or sending `null` leaves them untouched. Each number is normalized to E.164 and duplicates are merged. An invalid number rejects the request with `400 INVALID_REQUEST_BODY`, and the offending value is named in `errors`.",
            "example": [
              "+33142000000"
            ]
          },
          "custom_attributes": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true,
            "description": "Values for the company's custom attributes, keyed by attribute key. `TEXT` takes a string, `NUMBER` a finite JSON number (numeric strings are rejected), `BOOLEAN` a JSON boolean, `DATE` a `YYYY-MM-DD` string or ISO datetime, and `DROPDOWN` an option key or label (case-insensitive). Send `null` to clear a value; keys you omit are left untouched, and `{}` or omitting the field changes nothing. An unknown or archived key, or a value of the wrong type, rejects the whole request with `CUSTOM_ATTRIBUTE_KEY_UNKNOWN` or `CUSTOM_ATTRIBUTE_VALUE_INVALID`.",
            "example": {
              "ping_pong_level": "Advanced",
              "renewal_date": "2026-12-01"
            }
          }
        }
      },
      "SearchCompaniesRequest": {
        "type": "object",
        "description": "Request body for searching companies",
        "properties": {
          "filters": {
            "type": "object",
            "nullable": true,
            "description": "Named filters. All are combined with AND.",
            "properties": {
              "name": {
                "type": "string",
                "description": "Filter by company name (contains)"
              },
              "website": {
                "type": "string",
                "description": "Filter by website (contains)"
              },
              "industry": {
                "type": "string",
                "description": "Filter by industry (contains)"
              }
            }
          },
          "sort": {
            "type": "string",
            "nullable": true,
            "enum": [
              "DATE_DESC",
              "DATE_ASC",
              "NAME_ASC",
              "NAME_DESC",
              "CREATED_DESC",
              "CREATED_ASC"
            ],
            "description": "Sort order (default: DATE_DESC)"
          },
          "page": {
            "type": "integer",
            "default": 1,
            "description": "Page number (1-indexed)"
          },
          "size": {
            "type": "integer",
            "default": 20,
            "maximum": 100,
            "description": "Results per page"
          }
        }
      },
      "SearchDealsRequest": {
        "type": "object",
        "description": "Request body for searching deals",
        "properties": {
          "filters": {
            "type": "object",
            "nullable": true,
            "description": "Named filters. Combined with AND.",
            "properties": {
              "stage": {
                "type": "string",
                "description": "Filter by deal stage/status (exact match)"
              }
            }
          },
          "search": {
            "type": "string",
            "nullable": true,
            "description": "Free-text search across deal name and company"
          },
          "sort": {
            "type": "string",
            "nullable": true,
            "enum": [
              "DATE_DESC",
              "DATE_ASC",
              "NAME_ASC",
              "NAME_DESC",
              "CREATED_DESC",
              "CREATED_ASC"
            ],
            "description": "Sort order (default: DATE_DESC)"
          },
          "page": {
            "type": "integer",
            "default": 1,
            "description": "Page number (1-indexed)"
          },
          "size": {
            "type": "integer",
            "default": 20,
            "maximum": 100,
            "description": "Results per page"
          }
        }
      },
      "WebhookTopic": {
        "type": "string",
        "enum": [
          "call.received",
          "call.triggered",
          "call.answered",
          "call.completed",
          "tag.added",
          "tag.removed",
          "sms.received",
          "sms.sent",
          "contact.created",
          "contact.updated",
          "summary.updated"
        ],
        "description": "An event topic. See the Event Catalog for payloads.",
        "example": "call.received"
      },
      "WebhookApiResponse": {
        "type": "object",
        "description": "A webhook endpoint.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique webhook endpoint ID.",
            "example": "ep_2NfDKEm9sF8xK3pQr1Zt"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS URL that receives event deliveries."
          },
          "topics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookTopic"
            },
            "description": "Event topics this endpoint is subscribed to."
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Optional human-readable label."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the endpoint is active."
          },
          "signing_secret": {
            "type": "string",
            "nullable": true,
            "description": "Secret used to verify delivery signatures. Returned only when the webhook is created or fetched by ID."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the endpoint was created."
          }
        }
      },
      "CreateWebhookApiRequest": {
        "type": "object",
        "required": [
          "url",
          "topics"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS URL that will receive event deliveries."
          },
          "topics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookTopic"
            },
            "description": "Event topics to subscribe to (at least one)."
          },
          "description": {
            "type": "string",
            "description": "Optional human-readable label."
          }
        }
      },
      "UpdateWebhookApiRequest": {
        "type": "object",
        "description": "All fields optional. Only the fields you provide are changed.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "New HTTPS delivery URL."
          },
          "topics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookTopic"
            },
            "description": "Replacement set of event topics."
          },
          "description": {
            "type": "string",
            "description": "New label."
          },
          "enabled": {
            "type": "boolean",
            "description": "Enable or disable the endpoint."
          }
        }
      },
      "WebhookEventTypeApiResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "call.received"
          },
          "description": {
            "type": "string",
            "example": "Inbound call received"
          }
        }
      },
      "NoteUser": {
        "type": "object",
        "description": "Author of a note or comment.",
        "properties": {
          "id": {
            "type": "string",
            "example": "usr-def456"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "example": "John Smith"
          }
        }
      },
      "NoteMention": {
        "type": "object",
        "description": "A user mentioned in the content via `@[Name](usr-...)`.",
        "properties": {
          "user_id": {
            "type": "string",
            "example": "usr-abc123"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "example": "Jane Doe"
          },
          "deleted": {
            "type": "boolean",
            "description": "`true` if the mentioned user has since been removed from the team."
          }
        }
      },
      "ConversationNote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Note ID (`not-*`)",
            "example": "not-2NyMabc123"
          },
          "content": {
            "type": "string",
            "description": "Note text, with mentions inline as `@[Name](usr-...)`."
          },
          "contact_number": {
            "type": "string",
            "description": "The contact's phone number (E.164).",
            "example": "+14155551234"
          },
          "allo_number": {
            "type": "string",
            "nullable": true,
            "description": "The Allo line the conversation belongs to (E.164).",
            "example": "+14155550100"
          },
          "user": {
            "$ref": "#/components/schemas/NoteUser"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NoteMention"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ThreadComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Comment ID (`thc-*`)",
            "example": "thc-abc123"
          },
          "content": {
            "type": "string",
            "description": "Comment text, with mentions inline as `@[Name](usr-...)`."
          },
          "user": {
            "$ref": "#/components/schemas/NoteUser"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NoteMention"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Thread": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Thread ID (`cth-*`)",
            "example": "cth-abc123"
          },
          "entity_type": {
            "type": "string",
            "enum": [
              "CALL",
              "TEXT_MESSAGE",
              "CONVERSATION_NOTE"
            ],
            "description": "Type of the conversation item the thread is attached to."
          },
          "entity_id": {
            "type": "string",
            "description": "ID of the conversation item (`cll-*`, `msg-*`, or `not-*`).",
            "example": "cll-abc123"
          },
          "contact_number": {
            "type": "string",
            "description": "The contact's phone number (E.164).",
            "example": "+14155551234"
          },
          "resolved": {
            "type": "boolean"
          },
          "resolved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "resolved_by": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/NoteUser"
              }
            ]
          },
          "comment_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "comments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadComment"
            }
          }
        }
      },
      "ThreadSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Thread ID (`cth-*`)",
            "example": "cth-abc123"
          },
          "resolved": {
            "type": "boolean"
          },
          "resolved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "resolved_by": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/NoteUser"
              }
            ]
          },
          "comment_count": {
            "type": "integer"
          }
        }
      },
      "PersonNote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Note ID (`cno-*`)",
            "example": "cno-abc123"
          },
          "person_id": {
            "type": "string",
            "description": "Person ID (`per-*`)",
            "example": "per-abc123"
          },
          "content": {
            "type": "string",
            "description": "Note text, with mentions inline as `@[Name](usr-...)`."
          },
          "user": {
            "$ref": "#/components/schemas/NoteUser"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NoteMention"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AgentConfig": {
        "type": "object",
        "description": "The AI receptionist's own settings. Everything here except `id`, `status`, `is_default`, `created_at` and `updated_at` is writable with `PATCH /v2/api/numbers/{number}/agent`.",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "example": "agt-abc123"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "FORWARDING"
            ],
            "description": "`ACTIVE`: the receptionist answers incoming calls. `FORWARDING`: it does not, and calls go to your business phone. Read-only here, change it with `PUT /v2/api/numbers/{number}/agent/status`."
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "The name the receptionist gives itself on a call.",
            "example": "Maya"
          },
          "is_default": {
            "type": "boolean",
            "description": "True while the line still runs Allo's default receptionist, with no prompt, greeting, closing or knowledge of its own."
          },
          "business_name": {
            "type": "string",
            "nullable": true,
            "example": "Acme Plumbing"
          },
          "business_address": {
            "type": "string",
            "nullable": true,
            "example": "12 Main Street, Austin TX"
          },
          "business_phone": {
            "type": "string",
            "nullable": true,
            "description": "The business's own phone number, in E.164 format.",
            "example": "+14155551234"
          },
          "business_email": {
            "type": "string",
            "nullable": true,
            "example": "hello@acme.test"
          },
          "business_website": {
            "type": "string",
            "nullable": true,
            "example": "https://acme.test"
          },
          "business_industry": {
            "type": "string",
            "nullable": true,
            "example": "Plumbing"
          },
          "language": {
            "type": "string",
            "nullable": true,
            "enum": [
              "fr",
              "fr-CA",
              "en-US",
              "en-GB",
              "es",
              "de",
              "hr"
            ],
            "description": "The language the receptionist speaks. Pick a `voice_id` listed under the same language.",
            "example": "en-US"
          },
          "voice_id": {
            "type": "string",
            "nullable": true,
            "description": "Identifier of a voice from `GET /v2/api/voices`.",
            "example": "maya"
          },
          "greeting_message": {
            "type": "string",
            "nullable": true,
            "description": "What the receptionist says when it picks up.",
            "example": "Thanks for calling Acme Plumbing, how can I help?"
          },
          "closing_message": {
            "type": "string",
            "nullable": true,
            "description": "What the receptionist says before hanging up.",
            "example": "Thanks for calling, have a good day."
          },
          "tone_of_voice": {
            "type": "string",
            "enum": [
              "FRIENDLY",
              "PROFESSIONAL",
              "NEUTRAL",
              "ENTHUSIASTIC"
            ]
          },
          "answer_type": {
            "type": "string",
            "enum": [
              "CONCISE",
              "STANDARD",
              "DETAILED"
            ],
            "description": "How long the receptionist's answers run."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "AgentPromptField": {
        "type": "object",
        "description": "One piece of information the receptionist has to collect during the call.",
        "required": [
          "label",
          "question",
          "complete_when"
        ],
        "properties": {
          "label": {
            "type": "string",
            "example": "Email"
          },
          "question": {
            "type": "string",
            "example": "What is the best email to send the quote to?"
          },
          "complete_when": {
            "type": "string",
            "description": "How the receptionist knows it has the answer.",
            "example": "a valid email address is given"
          }
        }
      },
      "AgentPromptSection": {
        "type": "object",
        "description": "One section of the prompt. `required_fields` carries `fields` and no `content`; every other section carries `content` and no `fields`.",
        "properties": {
          "section": {
            "type": "string",
            "enum": [
              "objective",
              "personality",
              "behaviors",
              "prohibited",
              "required_fields",
              "objective_completion"
            ]
          },
          "title": {
            "type": "string",
            "description": "Human-readable title, derived server-side from `section`.",
            "example": "Objective"
          },
          "content": {
            "type": "string",
            "nullable": true,
            "example": "Book a visit with the caller."
          },
          "fields": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/AgentPromptField"
            }
          }
        }
      },
      "AgentPrompt": {
        "type": "object",
        "description": "The receptionist's prompt. Exactly one of the two keys is present: `sections` for a prompt written in the section format, `custom_prompt` for an older line whose prompt was written as freeform text. `custom_prompt` is the render of the sections, so it is never reported alongside them.",
        "properties": {
          "sections": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/AgentPromptSection"
            }
          },
          "custom_prompt": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AgentTransferRule": {
        "type": "object",
        "description": "One reason the receptionist hands the call over, and where it hands it to.",
        "properties": {
          "description": {
            "type": "string",
            "description": "The caller's reason, in the caller's words. This is what the receptionist matches what it hears against, so phrase it as a reason ('billing or invoice questions'), not as an instruction.",
            "example": "Billing or invoice questions"
          },
          "type": {
            "type": "string",
            "enum": [
              "EXTERNAL_NUMBER",
              "MEMBER",
              "INBOX"
            ],
            "description": "`EXTERNAL_NUMBER` transfers to any phone number, `MEMBER` to a teammate, `INBOX` to another Allo line."
          },
          "transfer_message": {
            "type": "string",
            "nullable": true,
            "description": "What the receptionist says before transferring.",
            "example": "Let me put you through to billing."
          },
          "target_number": {
            "type": "string",
            "nullable": true,
            "description": "Required for `EXTERNAL_NUMBER`. E.164 format.",
            "example": "+14155551234"
          },
          "target_member_id": {
            "type": "string",
            "nullable": true,
            "description": "Required for `MEMBER`. A user id from `GET /v2/api/users`."
          },
          "target_line_number": {
            "type": "string",
            "nullable": true,
            "description": "Required for `INBOX`. Another of your Allo numbers, in E.164 format."
          }
        }
      },
      "AgentTimeInterval": {
        "type": "object",
        "description": "One open period of a day, in seconds since midnight (0 to 86399). 9am to 5pm is 32400 to 61200.",
        "required": [
          "start_time",
          "end_time"
        ],
        "properties": {
          "start_time": {
            "type": "integer",
            "minimum": 0,
            "maximum": 86399,
            "example": 32400
          },
          "end_time": {
            "type": "integer",
            "minimum": 0,
            "maximum": 86399,
            "example": 61200
          }
        }
      },
      "AgentDaySchedule": {
        "type": "object",
        "required": [
          "day",
          "schedule"
        ],
        "properties": {
          "day": {
            "type": "string",
            "enum": [
              "MO",
              "TU",
              "WE",
              "TH",
              "FR",
              "SA",
              "SU"
            ]
          },
          "schedule": {
            "type": "array",
            "description": "The open periods of that day. An empty array closes the day.",
            "items": {
              "$ref": "#/components/schemas/AgentTimeInterval"
            }
          }
        }
      },
      "AgentBusinessHours": {
        "type": "object",
        "description": "When the business is open. A day left out of `schedule` is closed.",
        "properties": {
          "timezone": {
            "type": "string",
            "nullable": true,
            "description": "IANA timezone identifier.",
            "example": "America/New_York"
          },
          "schedule": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentDaySchedule"
            }
          }
        }
      },
      "SchedulingQuestion": {
        "type": "object",
        "description": "A question the calendar provider rejects a booking without, so the receptionist asks it during the call. Read-only: it is snapshotted when the event type is selected.",
        "properties": {
          "id": {
            "type": "string",
            "example": "notes"
          },
          "label": {
            "type": "string",
            "example": "Anything we should know before the visit?"
          }
        }
      },
      "SchedulingEventType": {
        "type": "object",
        "description": "An event type the receptionist may book. Send `id`, `slug`, `title` and `length_in_minutes` back as `GET /v2/api/calendars/{id}` reported them.",
        "required": [
          "id",
          "slug",
          "title"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The provider's own event-type identifier.",
            "example": "42"
          },
          "slug": {
            "type": "string",
            "example": "intro-call"
          },
          "title": {
            "type": "string",
            "example": "Intro call"
          },
          "length_in_minutes": {
            "type": "integer",
            "nullable": true,
            "example": 30
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Your own note on when the receptionist should book this one rather than another. This is what it routes on when several event types are bookable, so write it as the caller's reason.",
            "example": "Book this one when the caller wants a quote."
          },
          "required_questions": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/SchedulingQuestion"
            }
          }
        }
      },
      "CalendarOwner": {
        "type": "object",
        "description": "The teammate who connected the calendar.",
        "properties": {
          "user_id": {
            "type": "string"
          },
          "user_name": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "is_current_user": {
            "type": "boolean"
          }
        }
      },
      "AgentCalendar": {
        "type": "object",
        "description": "A calendar this receptionist can book on, with the event types selected for it.",
        "properties": {
          "calendar_connection_id": {
            "type": "string",
            "example": "exc-abc123"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "example": "Acme bookings"
          },
          "provider": {
            "type": "string",
            "enum": [
              "GOOGLE_CALENDAR",
              "CAL_COM",
              "CALENDLY",
              "OUTLOOK"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISCONNECTED"
            ]
          },
          "is_team_default": {
            "type": "boolean"
          },
          "owner": {
            "$ref": "#/components/schemas/CalendarOwner",
            "nullable": true
          },
          "event_types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SchedulingEventType"
            }
          }
        }
      },
      "AgentScheduling": {
        "type": "object",
        "properties": {
          "calendars": {
            "type": "array",
            "description": "The calendars this receptionist may book on. Empty when it has none, which is not the same as the workspace having none: list those with `GET /v2/api/calendars`.",
            "items": {
              "$ref": "#/components/schemas/AgentCalendar"
            }
          }
        }
      },
      "AgentWebsiteKnowledge": {
        "type": "object",
        "description": "A website of the team's knowledge library, crawled for the receptionist to answer from. The crawled text itself is not reported: it is what the receptionist reads, not something you configure.",
        "properties": {
          "id": {
            "type": "string",
            "example": "ksrc-abc123"
          },
          "url": {
            "type": "string",
            "example": "https://acme.test/pricing"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISABLED"
            ],
            "description": "`ACTIVE` when this line's receptionist answers from the website, `DISABLED` when this line does not use it."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "AgentFileKnowledge": {
        "type": "object",
        "description": "A document of the team's knowledge library, uploaded in the Allo app for the receptionist to answer from. Uploading is done in the app; this API lists and deletes.",
        "properties": {
          "id": {
            "type": "string",
            "example": "ksrc-def456"
          },
          "file_name": {
            "type": "string",
            "example": "pricing.pdf"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISABLED"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "AgentKnowledge": {
        "type": "object",
        "description": "What the receptionist knows about the business: facts, prices, policies, hours.",
        "properties": {
          "text": {
            "type": "string",
            "nullable": true,
            "deprecated": true,
            "description": "Deprecated. Free-text knowledge, up to 25000 characters, stored as the line's \"Business knowledge\" text source."
          },
          "websites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentWebsiteKnowledge"
            }
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentFileKnowledge"
            }
          }
        }
      },
      "AgentCapabilities": {
        "type": "object",
        "description": "What the receptionist is allowed to do on a call. All three are always reported.",
        "properties": {
          "SCHEDULING": {
            "type": "boolean",
            "description": "Book appointments on the calendars in `scheduling.calendars`."
          },
          "CALL_TRANSFER": {
            "type": "boolean",
            "description": "Transfer the call using the rules in `transfer_rules`."
          },
          "WARM_TRANSFER": {
            "type": "boolean",
            "description": "Announce the caller to the person taking the transfer before connecting them."
          }
        }
      },
      "AgentSnapshot": {
        "type": "object",
        "description": "The whole configuration of one line's AI receptionist.",
        "properties": {
          "agent": {
            "$ref": "#/components/schemas/AgentConfig"
          },
          "prompt": {
            "$ref": "#/components/schemas/AgentPrompt"
          },
          "capabilities": {
            "$ref": "#/components/schemas/AgentCapabilities"
          },
          "business_hours": {
            "$ref": "#/components/schemas/AgentBusinessHours"
          },
          "transfer_rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentTransferRule"
            }
          },
          "scheduling": {
            "$ref": "#/components/schemas/AgentScheduling"
          },
          "knowledge": {
            "$ref": "#/components/schemas/AgentKnowledge"
          }
        }
      },
      "UpdateAgentRequest": {
        "type": "object",
        "description": "Two merge rules apply. Single values are merged: omit one and it keeps its current value. The collections `capabilities`, `business_hours`, `transfer_rules` and `scheduling.calendars` are complete sets: send one and it replaces what was configured, omit it and it is left alone. An undeclared field is rejected with `400 UNKNOWN_FIELD` rather than ignored.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 64,
            "example": "Maya"
          },
          "business_name": {
            "type": "string",
            "maxLength": 64,
            "example": "Acme Plumbing"
          },
          "business_address": {
            "type": "string",
            "maxLength": 255
          },
          "business_phone": {
            "type": "string",
            "maxLength": 64,
            "description": "E.164 format.",
            "example": "+14155551234"
          },
          "business_email": {
            "type": "string",
            "maxLength": 64
          },
          "business_website": {
            "type": "string",
            "maxLength": 64
          },
          "business_industry": {
            "type": "string",
            "maxLength": 64
          },
          "language": {
            "type": "string",
            "enum": [
              "fr",
              "fr-CA",
              "en-US",
              "en-GB",
              "es",
              "de",
              "hr"
            ],
            "example": "en-US"
          },
          "voice_id": {
            "type": "string",
            "description": "An `id` from `GET /v2/api/voices`, listed under the receptionist's language.",
            "example": "maya"
          },
          "greeting_message": {
            "type": "string",
            "maxLength": 1000
          },
          "closing_message": {
            "type": "string",
            "maxLength": 1000
          },
          "tone_of_voice": {
            "type": "string",
            "enum": [
              "FRIENDLY",
              "PROFESSIONAL",
              "NEUTRAL",
              "ENTHUSIASTIC"
            ]
          },
          "answer_type": {
            "type": "string",
            "enum": [
              "CONCISE",
              "STANDARD",
              "DETAILED"
            ]
          },
          "capabilities": {
            "type": "object",
            "description": "The complete set of toggles. A capability left out of the map is turned off, so read the current ones first and send them all back.",
            "additionalProperties": {
              "type": "boolean"
            },
            "example": {
              "SCHEDULING": true,
              "CALL_TRANSFER": true,
              "WARM_TRANSFER": false
            }
          },
          "business_hours": {
            "type": "object",
            "description": "Replaces the whole week. `schedule` is required when this key is sent.",
            "required": [
              "schedule"
            ],
            "properties": {
              "timezone": {
                "type": "string",
                "description": "IANA timezone identifier.",
                "example": "America/New_York"
              },
              "schedule": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AgentDaySchedule"
                }
              }
            }
          },
          "transfer_rules": {
            "type": "array",
            "description": "Replaces the whole rule set. Send `[]` to remove every rule.",
            "items": {
              "$ref": "#/components/schemas/AgentTransferRule"
            }
          },
          "scheduling": {
            "type": "object",
            "properties": {
              "calendars": {
                "type": "object",
                "description": "The complete set of calendars the receptionist may book on, keyed by an `id` from `GET /v2/api/calendars`. A calendar it does not have yet is linked to it, one mapped to `[]` stays linked with no event type selected, and one left out loses access.",
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SchedulingEventType"
                  }
                }
              }
            }
          },
          "knowledge": {
            "type": "object",
            "description": "Only the free-text knowledge is writable here. Websites and files have their own endpoints.",
            "properties": {
              "text": {
                "type": "string",
                "deprecated": true,
                "description": "Deprecated: add websites instead. Stored as the line's \"Business knowledge\" text source in the team's knowledge library; a different text edits that source in place, an empty string turns it off for this line.",
                "maxLength": 25000,
                "example": "We serve the Austin metro area and open at 7am."
              }
            }
          }
        }
      },
      "SetAgentPromptRequest": {
        "type": "object",
        "description": "Replaces the whole prompt. `objective`, `personality` and `behaviors` are required; each section may appear once; a `content` section holds at most 3000 characters.",
        "required": [
          "sections"
        ],
        "properties": {
          "sections": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "section"
              ],
              "properties": {
                "section": {
                  "type": "string",
                  "enum": [
                    "objective",
                    "personality",
                    "behaviors",
                    "prohibited",
                    "required_fields",
                    "objective_completion"
                  ]
                },
                "content": {
                  "type": "string",
                  "maxLength": 3000,
                  "description": "Required for every section except `required_fields`."
                },
                "fields": {
                  "type": "array",
                  "description": "Required for `required_fields`, and rejected on every other section.",
                  "items": {
                    "$ref": "#/components/schemas/AgentPromptField"
                  }
                }
              }
            }
          }
        }
      },
      "SetAgentStatusRequest": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "FORWARDING"
            ],
            "description": "`ACTIVE` puts the receptionist on the line. `FORWARDING` takes it off and sends calls to your business phone."
          }
        }
      },
      "CalendarEventType": {
        "type": "object",
        "description": "An event type the provider currently offers on a calendar. This is the catalog you pick from when filling `scheduling.calendars`.",
        "properties": {
          "id": {
            "type": "string",
            "example": "42"
          },
          "slug": {
            "type": "string",
            "nullable": true,
            "example": "intro-call"
          },
          "title": {
            "type": "string",
            "example": "Intro call"
          },
          "length_in_minutes": {
            "type": "integer",
            "nullable": true,
            "example": 30
          },
          "provider_description": {
            "type": "string",
            "nullable": true,
            "description": "The blurb written in the calendar provider. Not the routing note the receptionist matches on: that one is the `description` you send in `scheduling.calendars`."
          },
          "required_questions": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/SchedulingQuestion"
            }
          }
        }
      },
      "Calendar": {
        "type": "object",
        "description": "A calendar connected to your workspace, whether or not a receptionist books on it.",
        "properties": {
          "id": {
            "type": "string",
            "description": "What `scheduling.calendars` on `PATCH /v2/api/numbers/{number}/agent` is keyed by.",
            "example": "exc-abc123"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "example": "Acme bookings"
          },
          "provider": {
            "type": "string",
            "enum": [
              "GOOGLE_CALENDAR",
              "CAL_COM",
              "CALENDLY",
              "OUTLOOK"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISCONNECTED"
            ]
          },
          "is_team_default": {
            "type": "boolean"
          },
          "owner": {
            "$ref": "#/components/schemas/CalendarOwner",
            "nullable": true
          },
          "available_event_types": {
            "type": "array",
            "nullable": true,
            "description": "Reported by `GET /v2/api/calendars/{id}` only, read live from the provider. Absent for a provider with no event-type concept, which is not the same answer as an empty list.",
            "items": {
              "$ref": "#/components/schemas/CalendarEventType"
            }
          }
        }
      },
      "Voice": {
        "type": "object",
        "description": "A voice the AI receptionist can speak with.",
        "properties": {
          "id": {
            "type": "string",
            "description": "What `voice_id` takes on `PATCH /v2/api/numbers/{number}/agent`.",
            "example": "maya"
          },
          "language": {
            "type": "string",
            "description": "The language this voice speaks. Match it to the receptionist's `language`.",
            "example": "en-US"
          },
          "avatar_url": {
            "type": "string"
          },
          "demo_url": {
            "type": "string",
            "description": "An audio sample, so you can listen before choosing."
          },
          "gender": {
            "type": "string",
            "enum": [
              "MALE",
              "FEMALE"
            ]
          }
        }
      },
      "CrmAttribute": {
        "type": "object",
        "description": "A custom field on people",
        "properties": {
          "key": {
            "type": "string",
            "description": "Unique key of the field within your team",
            "example": "budget"
          },
          "label": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the field",
            "example": "Budget"
          },
          "type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "BOOLEAN",
              "DROPDOWN"
            ],
            "description": "Value type",
            "example": "NUMBER"
          },
          "options": {
            "type": "array",
            "nullable": true,
            "description": "Allowed values. Only set for `DROPDOWN` fields.",
            "items": {
              "$ref": "#/components/schemas/CompanyAttributeOption"
            }
          },
          "source": {
            "type": "string",
            "description": "`allo` for fields created in Allo or with the API, otherwise the lowercase name of the integration that manages it, such as `hubspot`",
            "example": "allo"
          }
        }
      },
      "CreateCrmAttributeRequest": {
        "type": "object",
        "description": "Request body for creating a custom contact field",
        "required": [
          "label",
          "type"
        ],
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Display name of the field. The key is derived from it: lowercase, accents removed, runs of non-alphanumeric characters replaced by `_`, truncated to 64 characters. Must contain at least one letter or digit and must not resolve to a built-in field key such as `name`, `company` or `website`.",
            "example": "Lead Source"
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "BOOLEAN",
              "DROPDOWN"
            ],
            "description": "Value type of the field",
            "example": "TEXT"
          },
          "options": {
            "type": "array",
            "description": "Allowed values. Required, with at least one option, for `DROPDOWN`; rejected for other types.",
            "items": {
              "$ref": "#/components/schemas/CompanyAttributeOptionInput"
            }
          }
        }
      },
      "CreateCrmAttributeResult": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Key derived from the label",
            "example": "lead_source"
          },
          "label": {
            "type": "string",
            "description": "Stored label. When the field already existed, this is the label it was first created with.",
            "example": "Lead Source"
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "BOOLEAN",
              "DROPDOWN"
            ],
            "example": "TEXT"
          },
          "options": {
            "type": "array",
            "nullable": true,
            "description": "Allowed values. Only set for `DROPDOWN` fields.",
            "items": {
              "$ref": "#/components/schemas/CompanyAttributeOption"
            }
          },
          "already_existed": {
            "type": "boolean",
            "description": "`true` when a field with the same key and type already existed, or a deleted one was restored, and nothing new was created",
            "example": false
          }
        }
      },
      "UpdateCrmAttributeRequest": {
        "type": "object",
        "description": "All fields are optional",
        "properties": {
          "label": {
            "type": "string",
            "description": "New display name. The key does not change."
          },
          "description": {
            "type": "string",
            "description": "Free-text description of the field. A blank value clears it."
          },
          "options": {
            "type": "array",
            "description": "Replaces the full option list. `DROPDOWN` fields only. Send an option's current `key` to keep it when renaming its label.",
            "items": {
              "$ref": "#/components/schemas/CompanyAttributeOptionInput"
            }
          }
        }
      },
      "CompanyAttributeOption": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "enterprise"
          },
          "label": {
            "type": "string",
            "example": "Enterprise"
          }
        }
      },
      "CompanyAttribute": {
        "type": "object",
        "description": "A custom attribute on companies",
        "properties": {
          "key": {
            "type": "string",
            "description": "Unique key within your team",
            "example": "industry_segment"
          },
          "label": {
            "type": "string",
            "nullable": true,
            "description": "Display name",
            "example": "Industry segment"
          },
          "type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "BOOLEAN",
              "DROPDOWN"
            ],
            "example": "DROPDOWN"
          },
          "options": {
            "type": "array",
            "nullable": true,
            "description": "Allowed values. Only set for `DROPDOWN` attributes.",
            "items": {
              "$ref": "#/components/schemas/CompanyAttributeOption"
            }
          },
          "is_visible": {
            "type": "boolean",
            "description": "Whether the attribute is shown in the Allo apps"
          },
          "prompt": {
            "type": "string",
            "nullable": true,
            "description": "Instruction the AI CRM Manager follows to fill this attribute from calls. A blank value clears it.",
            "example": "Pick the segment that matches the company size mentioned on the call."
          },
          "should_prompt_override": {
            "type": "boolean",
            "description": "Whether the AI may overwrite a value that is already set",
            "nullable": true
          },
          "source": {
            "type": "string",
            "description": "`allo` for attributes created in Allo or with the API, otherwise the lowercase name of the integration that manages it, such as `hubspot`",
            "example": "allo"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateCompanyAttributeRequest": {
        "type": "object",
        "required": [
          "label",
          "type"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "Display name of the attribute. The attribute key is derived from it: lowercase, accents removed, runs of non-alphanumeric characters replaced by `_`, truncated to 64 characters. Labels that resolve to a reserved key are rejected.",
            "example": "Industry segment"
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "BOOLEAN",
              "DROPDOWN"
            ],
            "example": "DROPDOWN"
          },
          "options": {
            "type": "array",
            "description": "Allowed values. Required, with at least one option, for `DROPDOWN`; rejected for other types.",
            "items": {
              "$ref": "#/components/schemas/CompanyAttributeOptionInput"
            }
          },
          "prompt": {
            "type": "string",
            "nullable": true,
            "description": "Instruction the AI CRM Manager follows to fill this attribute from calls. A blank value clears it.",
            "example": "Pick the segment that matches the company size mentioned on the call."
          },
          "should_prompt_override": {
            "type": "boolean",
            "description": "Whether the AI may overwrite a value that is already set"
          }
        }
      },
      "CompanyAttributeOptionInput": {
        "type": "object",
        "required": [
          "label"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "Display name of the option",
            "example": "Enterprise"
          },
          "key": {
            "type": "string",
            "description": "Existing option key. Send it when editing an attribute to keep the option's key stable while its label changes. Keys that do not match an existing option are ignored and a key is derived from the label.",
            "example": "enterprise"
          }
        }
      },
      "UpdateCompanyAttributeRequest": {
        "type": "object",
        "description": "All fields are optional",
        "properties": {
          "label": {
            "type": "string",
            "description": "New display name"
          },
          "options": {
            "type": "array",
            "description": "Replaces the full option list. `DROPDOWN` attributes only. Send an option's current `key` to keep it when renaming its label.",
            "items": {
              "$ref": "#/components/schemas/CompanyAttributeOptionInput"
            }
          },
          "prompt": {
            "type": "string",
            "nullable": true,
            "description": "Instruction the AI CRM Manager follows to fill this attribute from calls. A blank value clears it.",
            "example": "Pick the segment that matches the company size mentioned on the call."
          },
          "should_prompt_override": {
            "type": "boolean",
            "description": "Whether the AI may overwrite a value that is already set"
          },
          "is_visible": {
            "type": "boolean",
            "description": "Show or hide the attribute in the Allo apps"
          }
        }
      },
      "PartnerSenderId": {
        "type": "object",
        "description": "An alphanumeric sender ID declared on an account you provisioned.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The sender ID's id (`vsi-*`).",
            "example": "vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61"
          },
          "account_id": {
            "type": "string",
            "description": "The account the sender ID is declared on.",
            "example": "usr-575966AF3661061265263C58882BC409D2A427B8"
          },
          "partner_client_ref": {
            "type": "string",
            "nullable": true,
            "description": "Your own reference, set when the account was created.",
            "example": "crm-12345"
          },
          "sender_id": {
            "type": "string",
            "description": "The name recipients see instead of a phone number.",
            "example": "PLOMBMARTIN"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "VALIDATED",
              "FAILED",
              "DISABLED"
            ],
            "description": "`PENDING`: waiting for Allo's review. `VALIDATED`: approved, the account can send SMS with it. `FAILED`: rejected, declare another name. `DISABLED`: deactivated by Allo after validation, sending with it is refused.",
            "example": "PENDING"
          },
          "example_content": {
            "type": "string",
            "nullable": true,
            "description": "The example message sent with the declaration.",
            "example": "Bonjour, votre intervention est confirmée demain à 9h. Plomberie Martin"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the sender ID was declared.",
            "example": "2026-11-16T10:05:00"
          }
        }
      },
      "CreatePartnerSenderIdRequest": {
        "type": "object",
        "required": [
          "sender_id"
        ],
        "properties": {
          "sender_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 11,
            "description": "1 to 11 letters or digits, with no spaces or symbols. It must not belong to another Allo account.",
            "example": "PLOMBMARTIN"
          },
          "example_content": {
            "type": "string",
            "nullable": true,
            "maxLength": 1000,
            "description": "Optional. An example of a message the account will send, shown to the Allo reviewer.",
            "example": "Bonjour, votre intervention est confirmée demain à 9h. Plomberie Martin"
          }
        }
      },
      "ApiPagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "example": 1
          },
          "size": {
            "type": "integer",
            "example": 20
          },
          "total_count": {
            "type": "integer",
            "format": "int64",
            "example": 1
          },
          "total_pages": {
            "type": "integer",
            "example": 1
          },
          "has_more": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "AssignDialingQueueRequest": {
        "type": "object",
        "description": "The team member the queue should be assigned to. Provide `user_id` or `email`; `user_id` wins when both are provided.",
        "properties": {
          "user_id": {
            "type": "string",
            "description": "Id of the new assignee. Resolve teammate ids via `GET /v2/api/users`.",
            "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email of the new assignee. Used only when `user_id` is absent.",
            "example": "rep@example.com"
          }
        }
      },
      "CrmViewFilter": {
        "type": "object",
        "required": [
          "field",
          "operator",
          "value"
        ],
        "description": "One condition of a view. All conditions of a view are combined with AND.",
        "properties": {
          "field": {
            "type": "string",
            "description": "A built-in person field (`name`, `company`, `job_title`, `emails`, `phone_numbers`, `website`, `addresses`, `created_at`, `updated_at`, `last_activity`, `activity_history`, `sms_content` (only when the team has SMS)) or the `key` of a custom field from `GET /v2/api/crm/attributes`. An unknown field returns 400 `INVALID_FILTER_FIELD`",
            "example": "company"
          },
          "operator": {
            "type": "string",
            "enum": [
              "IS",
              "IS_NOT",
              "CONTAINS",
              "NOT_CONTAINS",
              "EMPTY",
              "NOT_EMPTY",
              "STARTS_WITH",
              "ENDS_WITH",
              "BEFORE",
              "AFTER",
              "DATE_EQUALS",
              "GREATER_THAN",
              "GREATER_THAN_OR_EQUAL",
              "LESS_THAN",
              "LESS_THAN_OR_EQUAL",
              "HAS"
            ],
            "description": "Comparison operator. It must match the type of the field, otherwise the request returns 400 `INVALID_FILTER_OPERATOR`",
            "example": "CONTAINS"
          },
          "value": {
            "type": "string",
            "description": "Value to compare to. It must be readable for the type of the field, otherwise the request returns 400 `INVALID_FILTER_VALUE`: numeric for a number field, an ISO 8601 date such as `2026-01-31` or date-time such as `2026-01-31T00:00:00Z` for a date field. Ignored for `EMPTY` and `NOT_EMPTY`",
            "example": "Acme"
          }
        }
      },
      "CrmViewSort": {
        "type": "object",
        "required": [
          "field",
          "order"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "A sortable built-in person field (`name`, `company`, `job_title`, `website`, `created_at`, `updated_at`, `last_activity`) or the `key` of a sortable custom field from `GET /v2/api/crm/attributes`",
            "example": "created_at"
          },
          "order": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "example": "desc"
          }
        }
      },
      "CrmView": {
        "type": "object",
        "description": "A saved view: a named filter and sort over people. Views created in the Allo app and with the API are the same objects.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Public ID of the view",
            "example": "cvw_2abc"
          },
          "name": {
            "type": "string",
            "example": "Hot leads"
          },
          "filters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CrmViewFilter"
            }
          },
          "sort": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CrmViewSort"
            }
          },
          "owner_type": {
            "type": "string",
            "enum": [
              "USER",
              "TEAM"
            ],
            "description": "`USER` is private to the API key's user. `TEAM` is shared with the user's team.",
            "example": "USER"
          },
          "user_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the user who owns a `USER` view",
            "example": "usr_2abc"
          },
          "team_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the team a `TEAM` view belongs to"
          },
          "created_at": {
            "type": "string",
            "example": "2026-10-23T10:00:00"
          },
          "updated_at": {
            "type": "string",
            "example": "2026-10-23T10:00:00"
          }
        }
      },
      "CreateCrmViewRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "example": "Hot leads",
            "minLength": 1
          },
          "filters": {
            "type": "array",
            "description": "Conditions combined with AND. At most 50",
            "items": {
              "$ref": "#/components/schemas/CrmViewFilter"
            },
            "maxItems": 50
          },
          "sort": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "$ref": "#/components/schemas/CrmViewSort"
            },
            "description": "Up to 2 entries. Sortable built-in fields: `name`, `company`, `job_title`, `website`, `created_at`, `updated_at`, `last_activity`. A sortable custom field `key` from `GET /v2/api/crm/attributes` also works"
          },
          "owner_type": {
            "type": "string",
            "enum": [
              "USER",
              "TEAM"
            ],
            "description": "`USER` is private to the API key's user. `TEAM` is shared with the user's team; it returns 400 `USER_HAS_NO_TEAM` when the user has no team.",
            "example": "USER",
            "default": "USER"
          }
        }
      },
      "UpdateCrmViewRequest": {
        "type": "object",
        "description": "All fields are optional. An omitted field is unchanged. `filters: []` clears the filters.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "example": "Hot leads",
            "description": "New name. Must not be blank when sent",
            "pattern": "\\S"
          },
          "filters": {
            "type": "array",
            "description": "Conditions combined with AND. At most 50",
            "items": {
              "$ref": "#/components/schemas/CrmViewFilter"
            },
            "maxItems": 50
          },
          "sort": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "$ref": "#/components/schemas/CrmViewSort"
            },
            "description": "Up to 2 entries. Sortable built-in fields: `name`, `company`, `job_title`, `website`, `created_at`, `updated_at`, `last_activity`. A sortable custom field `key` from `GET /v2/api/crm/attributes` also works"
          },
          "owner_type": {
            "type": "string",
            "enum": [
              "USER",
              "TEAM"
            ],
            "description": "`USER` is private to the API key's user. `TEAM` is shared with the user's team; it returns 400 `USER_HAS_NO_TEAM` when the user has no team.",
            "example": "USER"
          }
        }
      },
      "InboxMenuBranchStep": {
        "type": "object",
        "properties": {
          "node_id": {
            "type": "string",
            "description": "ID of the phone-menu node in the line's published call flow.",
            "example": "node-3"
          },
          "digit": {
            "type": "string",
            "pattern": "^[0-9*#]$",
            "description": "Key pressed at that menu.",
            "example": "2"
          }
        },
        "required": [
          "node_id",
          "digit"
        ]
      },
      "InboxCondition": {
        "description": "Narrows a source to calls that went through part of the line's phone menu. A source holds at most 10 conditions, and an inbox at most 60 menu steps in all.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/InboxMenuOptionCondition"
          },
          {
            "$ref": "#/components/schemas/InboxMenuBranchCondition"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "MENU_OPTION": "#/components/schemas/InboxMenuOptionCondition",
            "MENU_BRANCH": "#/components/schemas/InboxMenuBranchCondition"
          }
        }
      },
      "InboxSource": {
        "type": "object",
        "properties": {
          "allo_number": {
            "type": "string",
            "description": "Allo line (E.164).",
            "example": "+33612345678"
          },
          "conditions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InboxCondition"
            },
            "description": "Empty means every conversation on the line.",
            "maxItems": 10
          }
        },
        "required": [
          "allo_number",
          "conditions"
        ]
      },
      "InboxFilters": {
        "type": "object",
        "description": "Saved filters, with the same meaning as the conversation list filters in the app. \"Unread only\" is not saved on an inbox: use the `unread` query parameter of List conversations.",
        "properties": {
          "types": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "INBOUND_CALL",
                "OUTBOUND_CALL",
                "TRANSFERRED",
                "INBOUND_TEXT_MESSAGE",
                "OUTBOUND_TEXT_MESSAGE",
                "VOICEMAIL",
                "AI_ASSISTANT"
              ]
            },
            "example": [
              "INBOUND_CALL"
            ]
          },
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Teammates (`usr-*`), up to 50.",
            "example": [],
            "maxItems": 50
          },
          "contact_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [],
            "maxItems": 50,
            "description": "Contacts, up to 50."
          },
          "contact_list_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [],
            "maxItems": 10,
            "description": "Contact lists, up to 10."
          },
          "tag_keys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "porting"
            ],
            "maxItems": 20,
            "description": "Call tag keys (AI or manual tags, from `GET /v2/api/tags`), up to 20. A conversation matches when any of its calls on the inbox's lines has one of these tags, not only the last call. Each key must be a tag of your workspace."
          }
        }
      },
      "Inbox": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "inb-abc123"
          },
          "name": {
            "type": "string",
            "example": "Sales"
          },
          "emoji": {
            "type": "string",
            "nullable": true,
            "example": "💼"
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InboxSource"
            }
          },
          "filters": {
            "$ref": "#/components/schemas/InboxFiltersResponse"
          },
          "notifications_muted": {
            "type": "boolean",
            "example": false
          },
          "favorited_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the owner starred the inbox, `null` when it is not a favorite. Favorites show first in the app's inbox switcher, oldest star first.",
            "example": null
          }
        },
        "required": [
          "id",
          "name",
          "emoji",
          "sources",
          "filters",
          "notifications_muted",
          "favorited_at"
        ]
      },
      "InboxSuggestion": {
        "type": "object",
        "description": "A ready-made source, ranked from the caller's recent activity.",
        "properties": {
          "allo_number": {
            "type": "string",
            "example": "+33612345678"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Suggested inbox name. Always `null` for a whole-line suggestion (`branch: null`).",
            "example": "Sales"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "example": "Website FR, option 2",
            "description": "Always `null` for a whole-line suggestion (`branch: null`)."
          },
          "branch": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/InboxMenuBranchStep"
            },
            "description": "Phone-menu path, or null for the whole line."
          },
          "answered": {
            "type": "integer",
            "description": "Calls the caller answered from this source recently."
          },
          "rung": {
            "type": "integer",
            "description": "Calls that rang the caller from this source recently."
          },
          "texted": {
            "type": "integer",
            "description": "Texts the caller exchanged on this source recently."
          },
          "score": {
            "type": "integer",
            "description": "Ranking score. Higher first."
          },
          "source": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InboxSource"
              }
            ],
            "description": "The suggestion as an inbox source, ready to put in `sources`."
          }
        },
        "required": [
          "allo_number",
          "name",
          "description",
          "branch",
          "answered",
          "rung",
          "texted",
          "score",
          "source"
        ]
      },
      "MenuOption": {
        "type": "object",
        "properties": {
          "node_id": {
            "type": "string",
            "description": "The menu node of the last step.",
            "example": "node-7"
          },
          "path": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InboxMenuBranchStep"
            },
            "description": "Menu choices from the first menu down to this option."
          },
          "digits": {
            "type": "string",
            "description": "The same path as keys, separated by `>`.",
            "example": "1>2"
          },
          "label": {
            "type": "string",
            "example": "Sales"
          },
          "condition": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InboxCondition"
              }
            ],
            "description": "A ready `MENU_BRANCH` condition for this option."
          }
        },
        "required": [
          "node_id",
          "path",
          "digits",
          "label",
          "condition"
        ]
      },
      "InboxMenuOptionCondition": {
        "type": "object",
        "description": "Matches keys of one phone menu.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "MENU_OPTION"
            ]
          },
          "node_id": {
            "type": "string",
            "description": "The menu node.",
            "example": "node-3"
          },
          "digits": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[0-9]$"
            },
            "description": "Keys that match, distinct. May be `[]` only when `include_no_choice` is `true`, to match calls that reached the menu without pressing a key.",
            "example": [
              "1"
            ]
          },
          "include_no_choice": {
            "type": "boolean",
            "description": "Also match calls that reached the menu without pressing a key.",
            "example": false
          }
        },
        "required": [
          "type",
          "node_id",
          "digits",
          "include_no_choice"
        ]
      },
      "InboxMenuBranchCondition": {
        "type": "object",
        "description": "Matches any of several paths through the line's phone menus. To combine several options of one line, put all their paths in `branches`.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "MENU_BRANCH"
            ]
          },
          "branches": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "description": "Each branch lists the menu choices from the first menu down to the option picked.",
            "items": {
              "type": "array",
              "minItems": 1,
              "maxItems": 6,
              "items": {
                "$ref": "#/components/schemas/InboxMenuBranchStep"
              }
            }
          },
          "include_no_choice": {
            "type": "boolean",
            "description": "Also match calls that reached the menu without pressing a key.",
            "example": false
          }
        },
        "required": [
          "type",
          "branches",
          "include_no_choice"
        ]
      },
      "InboxSourceInput": {
        "type": "object",
        "properties": {
          "allo_number": {
            "type": "string",
            "description": "Allo line (E.164). Each line appears once in `sources`.",
            "example": "+33612345678"
          },
          "conditions": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/InboxCondition"
            },
            "description": "Empty or absent means every conversation on the line."
          }
        },
        "required": [
          "allo_number"
        ]
      },
      "InboxFiltersResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/InboxFilters"
          }
        ],
        "required": [
          "types",
          "user_ids",
          "contact_ids",
          "contact_list_ids",
          "tag_keys"
        ],
        "description": "The saved filters, always returned with every key."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized - Invalid or missing API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "API_KEY_INVALID",
              "details": null
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - API key lacks required scope",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "API_KEY_INSUFFICIENT_SCOPE",
              "details": [
                {
                  "message": "required=CRM_READ",
                  "field": "scope"
                }
              ]
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests - Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "API_KEY_QUOTA_EXCEEDED",
              "details": [
                {
                  "message": "limit=1000;type=DAILY;reset_in=3600",
                  "field": "DAILY"
                }
              ]
            }
          }
        }
      },
      "ApiUnauthorized": {
        "description": "Invalid or missing API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "ApiNotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "ApiValidationError": {
        "description": "Invalid request parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "ApiConflict": {
        "description": "Conflict with existing resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "ApiRateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "ApiForbidden": {
        "description": "API key lacks the required scope or access to the resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "parameters": {
      "Page": {
        "name": "page",
        "in": "query",
        "description": "Page number (1-indexed)",
        "schema": {
          "type": "integer",
          "default": 1,
          "minimum": 1
        }
      },
      "Size": {
        "name": "size",
        "in": "query",
        "description": "Results per page",
        "schema": {
          "type": "integer",
          "default": 20,
          "minimum": 1,
          "maximum": 100
        }
      },
      "Extend": {
        "name": "extend",
        "in": "query",
        "description": "Comma-separated optional fields. Supported: `transcript`",
        "schema": {
          "type": "string",
          "example": "transcript"
        }
      }
    }
  }
}
