{
  "openapi": "3.1.0",
  "info": {
    "title": "PhoneLink API",
    "version": "1.0.0",
    "summary": "Manage companies, sites, Yealink devices, templates and webhooks on PhoneLink.io.",
    "description": "The PhoneLink API, version 1.0.0. Operations marked **Planned** are designed but not available yet; everything else is implemented and tested.\n\n## How PhoneLink is organized\n\n- **Account**: one PhoneLink customer. An API key belongs to exactly one account and can never see another account's data.\n- **Company**: a business whose phones the account manages. An account can have many companies.\n- **Site**: a location inside a company. Every device belongs to one site.\n- **Device**: one Yealink phone, DECT base, conference phone or Wi-Fi handset, identified by its MAC address.\n- **SIP platform**: a phone system that lines register to, described once per account: realm rules, registrar, outbound proxy, transport, timers, NAT, encryption and codecs. Lines point at a SIP platform and supply only their own user name and password.\n- **Template**: a named set of Yealink configuration settings. Templates layer on top of each other (see Templates).\n\n## Typical integration flow\n\n1. Create a company with `POST /companies` and at least one site with `POST /companies/{company}/sites`.\n2. Describe your phone system once with `POST /sip-platforms`, and set `sip_platform` (and `sip_realm`, if each company has its own) on the company.\n2a. Create or pick a template with `POST /templates`.\n3. Add each phone with `POST /devices` (or many at once with `POST /devices/bulk`), giving its MAC address, company, site, template and SIP lines.\n4. PhoneLink registers the MAC with Yealink's Redirection and Provisioning Service (RPS) when `register_rps` is true. Check `rps.state` on the device to see the result.\n5. The phone is plugged in, is redirected by Yealink to PhoneLink, and downloads its configuration. PhoneLink sends a `device.first_boot` webhook.\n6. Change settings later with `PATCH /devices/{mac}` or by editing a template. Phones pick up changes at their next scheduled check-in, or sooner if you call `POST /devices/{mac}/resync`.\n\n## Authentication\n\nSend your API key as a bearer token on every request:\n\n`Authorization: Bearer pl_live_...`\n\nKeys are created and revoked in the customer panel under API and webhooks; they cannot be managed through the API. A key is either read-only or read-and-write.\n\n## MAC addresses\n\nAny common format is accepted on input (`805EC03A119F`, `80:5E:C0:3A:11:9F`, `80-5e-c0-3a-11-9f`). Responses always use upper-case hex separated by colons. In URL paths use the 12 hex digits with no separators or with colons.\n\nA MAC address can belong to only one account on PhoneLink. Adding a MAC that another account already holds returns `409` with code `mac_already_claimed`.\n\n## Pagination\n\nList endpoints return `{ \"data\": [...], \"next_cursor\": \"...\" }`. Pass `next_cursor` back as the `cursor` query parameter to get the next page. `next_cursor` is `null` on the last page. `limit` defaults to 50 and may be at most 200.\n\n## Idempotency\n\n`POST` requests accept an `Idempotency-Key` header. Repeating a request with the same key within 24 hours returns the original response instead of creating a duplicate.\n\n## Errors\n\nErrors use standard HTTP status codes and a JSON body: `{ \"error\": { \"code\": \"...\", \"message\": \"...\", \"details\": {} } }`. `code` is a stable machine-readable string; `message` is for people.\n\n## Rate limits\n\nRequests over the limit return `429` with a `Retry-After` header giving the number of seconds to wait. The limit values are not decided yet.\n\n## Webhooks\n\nRegister an HTTPS endpoint with `POST /webhooks` and choose the event types you want. Each delivery is a `POST` with a JSON body (see the Webhooks section) and an `X-PhoneLink-Signature` header containing an HMAC-SHA256 of the raw body, keyed with the endpoint's signing secret. Respond with any `2xx` status within 10 seconds. Failed deliveries are retried five times over about nine hours.\n\n## How a line's registration settings are resolved\n\nFor each line PhoneLink takes the SIP platform named on the line, or else the company's `sip_platform`, or else the account's default platform. The realm comes from the line, the company or the platform, according to the platform's `realm_mode`. Any field set in the line's `registration` object then overrides the platform for that line only. A line with no platform at all must give `registration.registrars` itself.\n\nExample, Kazoo: the platform has `realm_mode: company`, no registrar host (so phones register to the realm) and two `outbound_proxies`. The company has `sip_realm: lakeside.sip.example.com`. The line has `username: 101` and a password. The phone registers as `101@lakeside.sip.example.com` and sends its traffic to the proxy.\n\n## Knowing whether a phone is working\n\nPhoneLink reports three separate things, because they fail independently:\n\n- **Online** (`status`, `last_seen_at`): the phone is powered and can reach PhoneLink. Phones check in on a short fixed interval (`check_in_interval_seconds`), and each check-in is a heartbeat. A phone that misses three intervals in a row becomes `offline`. No SIP server is involved.\n- **In sync** (`config_in_sync`, `config_version`, `applied_config_version`): the phone has fetched the configuration that is current now. `GET /devices/{mac}/provisioning-log` lists every request the phone made and what it was given.\n- **Registered** (`registration_state` on each line): the phone itself tells PhoneLink when a line registers, fails to register or unregisters. This is the phone's own report, not a probe of your phone system.\n\nFor deeper troubleshooting, `POST /devices/{mac}/log-captures` asks the phone to send its own system log to PhoneLink for a limited time.\n\n## Call quality and device health\n\nWhen call quality reporting is switched on, each phone sends PhoneLink a voice quality report at the end of every call (RFC 6035). `GET /devices/{mac}/calls` lists them, and `GET /quality` aggregates them by day, company, site or device. PhoneLink rates each call from its listening MOS: `good` at 4.0 or higher, `fair` from 3.5, `poor` below 3.5. Phone numbers and SIP addresses in the reports are not kept.\n\n`GET /devices/{mac}/health` summarizes the last 30 days from signals PhoneLink already has: check-ins, restarts, registration reports, configuration state and call quality. It does not include memory use, Wi-Fi signal strength or handset battery, which phones do not report through these channels.\n\n## The provisioning domain\n\nEvery phone fetches its configuration from `042524.com`, whether it was sent there by Yealink RPS, by DHCP option 66 or by someone typing it into the phone. The domain is the same for all accounts. A phone that connects before it has been added to an account is refused and recorded, and is served normally as soon as it is added.",
    "contact": {
      "name": "PhoneLink",
      "url": "https://phonelink.io"
    }
  },
  "servers": [
    {
      "url": "https://login.phonelink.io/v1",
      "description": "Production. The API is served from the customer panel's address until it has its own."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Sign-in",
      "description": "Registration and sessions for people using the panels. Integrations use API keys instead."
    },
    {
      "name": "Account",
      "description": "The account the API key belongs to."
    },
    {
      "name": "Team",
      "description": "The people who can sign in to an account. Roles: `owner` (the person who signed up; cannot be changed or removed), `admin` (everything, including the team and API keys), `member` (companies, phones, templates and webhooks), `viewer` (read only). Team management needs a signed-in owner or admin; an API key cannot do it."
    },
    {
      "name": "Companies",
      "description": "Businesses whose phones you manage."
    },
    {
      "name": "Sites",
      "description": "Locations inside a company."
    },
    {
      "name": "Devices",
      "description": "Phones, DECT bases, conference phones and Wi-Fi handsets."
    },
    {
      "name": "SIP platforms",
      "description": "Phone systems that lines register to. Changing a platform marks every device that uses it for resync."
    },
    {
      "name": "Handsets",
      "description": "DECT handsets paired to a DECT base device."
    },
    {
      "name": "Templates",
      "description": "Reusable configuration. Settings are applied in this order, later layers overriding earlier ones: account default template, model template, company template, site template, the device's own template, then the device's `overrides`."
    },
    {
      "name": "Catalog",
      "description": "Supported Yealink models and available firmware."
    },
    {
      "name": "Webhooks",
      "description": "Endpoints that receive event notifications."
    },
    {
      "name": "Events",
      "description": "The activity log for the account."
    },
    {
      "name": "Logs",
      "description": "The provisioning request log, and on-demand capture of a phone's own system log."
    },
    {
      "name": "Quality and health",
      "description": "Per-call voice quality reports sent by the phones, aggregates of them, and a per-device health summary."
    },
    {
      "name": "Images",
      "description": "Wallpapers and logos. An upload is resized once for every color phone screen size."
    },
    {
      "name": "Platform admin",
      "description": "For PhoneLink staff only."
    }
  ],
  "paths": {
    "/account": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getAccount",
        "summary": "Get the current account",
        "description": "Returns the account that owns the API key, with its device limit and current usage. Use it to confirm a key works.",
        "responses": {
          "200": {
            "description": "The account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "listCompanies",
        "summary": "List companies",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "q",
            "in": "query",
            "description": "Match companies whose name contains this text.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of companies.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Companies"
        ],
        "operationId": "createCompany",
        "summary": "Create a company",
        "description": "Creates a company. If `slug` is omitted it is generated from the name. A first site can be created in the same call with `sites`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyCreate"
              },
              "example": {
                "name": "Lakeside Dental",
                "slug": "lakeside-dental",
                "template": "dental-front-office",
                "sites": [
                  {
                    "name": "Front office",
                    "timezone": "America/New_York"
                  }
                ],
                "sip_platform": "harbor-voice-kazoo",
                "sip_realm": "lakeside.sip.example.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The company was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{company}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Company"
        }
      ],
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getCompany",
        "summary": "Get a company",
        "responses": {
          "200": {
            "description": "The company.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Companies"
        ],
        "operationId": "updateCompany",
        "summary": "Update a company",
        "description": "Send only the fields you want to change. Changing `template` marks every device in the company for resync.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated company.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "tags": [
          "Companies"
        ],
        "operationId": "deleteCompany",
        "summary": "Delete a company",
        "description": "Deletes the company and its sites. Fails with `409` and code `company_has_devices` while any device still belongs to it, unless `force=true`, which also deletes those devices and releases their MAC addresses from Yealink RPS.",
        "parameters": [
          {
            "name": "force",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/companies/{company}/sites": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Company"
        }
      ],
      "get": {
        "tags": [
          "Sites"
        ],
        "operationId": "listSites",
        "summary": "List a company's sites",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of sites.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Sites"
        ],
        "operationId": "createSite",
        "summary": "Create a site",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteCreate"
              },
              "example": {
                "name": "Annex",
                "timezone": "America/New_York"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The site was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Site"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/companies/{company}/sites/{site}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Company"
        },
        {
          "$ref": "#/components/parameters/Site"
        }
      ],
      "get": {
        "tags": [
          "Sites"
        ],
        "operationId": "getSite",
        "summary": "Get a site",
        "responses": {
          "200": {
            "description": "The site.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Site"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Sites"
        ],
        "operationId": "updateSite",
        "summary": "Update a site",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated site.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Site"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "tags": [
          "Sites"
        ],
        "operationId": "deleteSite",
        "summary": "Delete a site",
        "description": "Fails with `409` and code `site_has_devices` while any device still belongs to the site.",
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/devices": {
      "get": {
        "tags": [
          "Devices"
        ],
        "operationId": "listDevices",
        "summary": "List devices",
        "description": "Lists devices across the whole account. Combine filters to narrow the result.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "company",
            "in": "query",
            "description": "Company slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site",
            "in": "query",
            "description": "Site slug. Requires `company`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/DeviceStatus"
            }
          },
          {
            "name": "model",
            "in": "query",
            "description": "Model identifier, for example `SIP-T54W`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "template",
            "in": "query",
            "description": "Template slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Match MAC address, label or extension.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of devices.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Devices"
        ],
        "operationId": "createDevice",
        "summary": "Add a device",
        "description": "Adds one device. When `register_rps` is true (the default) PhoneLink registers the MAC with Yealink RPS so the phone finds PhoneLink on first boot; the result appears in `rps`. For phones set up by hand, enter `042524.com` as the provisioning server on the phone, or hand it out with DHCP option 66. It is the same for every device.\n\n`model` may be omitted; it is then detected the first time the phone checks in.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceCreate"
              },
              "example": {
                "mac": "80:5E:C0:3A:11:9F",
                "company": "lakeside-dental",
                "site": "front-office",
                "model": "SIP-T54W",
                "label": "Reception",
                "template": "dental-front-office",
                "lines": [
                  {
                    "position": 1,
                    "sip_platform": "harbor-voice-kazoo",
                    "username": "101",
                    "password": "REPLACE_ME",
                    "display_name": "Reception",
                    "label": "101"
                  }
                ],
                "register_rps": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The device was added.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/devices/bulk": {
      "post": {
        "tags": [
          "Devices"
        ],
        "operationId": "createDevicesBulk",
        "summary": "Add many devices",
        "description": "Adds up to 500 devices in one call. Each item is validated and created independently, so some can succeed while others fail. The response lists the outcome for every item in the order sent.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "devices"
                ],
                "properties": {
                  "devices": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 500,
                    "items": {
                      "$ref": "#/components/schemas/DeviceCreate"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-item results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/devices/{mac}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Devices"
        ],
        "operationId": "getDevice",
        "summary": "Get a device",
        "responses": {
          "200": {
            "description": "The device.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Devices"
        ],
        "operationId": "updateDevice",
        "summary": "Update a device",
        "description": "Send only the fields you want to change. `lines` and `overrides` replace the stored value entirely when present. Moving a device to another company or site is done by changing `company` and `site`. Any change marks the device for resync.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated device.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "tags": [
          "Devices"
        ],
        "operationId": "deleteDevice",
        "summary": "Remove a device",
        "description": "Removes the device, stops serving it configuration and releases its MAC address from Yealink RPS so it can be used elsewhere. The phone keeps its last configuration until it is factory reset.",
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/devices/{mac}/resync": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "post": {
        "tags": [
          "Devices"
        ],
        "operationId": "resyncDevice",
        "summary": "Planned: Ask a device to fetch its configuration",
        "description": "Queues a resync. PhoneLink is not in the phone's call path, so the request is delivered the next time the phone checks in; it is not instant. The response says when that is expected.",
        "responses": {
          "202": {
            "description": "Queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionQueued"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-status": "planned"
      }
    },
    "/devices/{mac}/reboot": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "post": {
        "tags": [
          "Devices"
        ],
        "operationId": "rebootDevice",
        "summary": "Planned: Ask a device to reboot",
        "description": "Queues a reboot, delivered the next time the phone checks in.",
        "responses": {
          "202": {
            "description": "Queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionQueued"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-status": "planned"
      }
    },
    "/devices/{mac}/config": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Devices"
        ],
        "operationId": "getDeviceConfig",
        "summary": "Preview a device's rendered configuration",
        "description": "Returns the final settings the device would receive right now, after all template layers and overrides are applied, and which layer each setting came from. Passwords are masked. Use it to debug why a phone has a particular setting.",
        "responses": {
          "200": {
            "description": "The rendered configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RenderedConfig"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/devices/{mac}/handsets": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Handsets"
        ],
        "operationId": "listHandsets",
        "summary": "List the handsets on a DECT base",
        "description": "Only for a single-cell DECT base (W60B, W70B). Other models return `422` with code `not_a_dect_base`; multi-cell systems return `multicell_not_supported`.",
        "responses": {
          "200": {
            "description": "The handsets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Handset"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "post": {
        "tags": [
          "Handsets"
        ],
        "operationId": "createHandset",
        "summary": "Add a handset to a DECT base",
        "description": "Gives a handset slot a name and the line it rings on and dials out with. Sending a `slot` that is already used replaces that handset. The handset itself is paired at the base; `ipui` is kept for your records.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HandsetCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The handset was added.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Handset"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/devices/{mac}/handsets/{slot}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        },
        {
          "name": "slot",
          "in": "path",
          "required": true,
          "description": "Handset slot number on the base, starting at 1.",
          "schema": {
            "type": "integer",
            "minimum": 1
          }
        }
      ],
      "delete": {
        "tags": [
          "Handsets"
        ],
        "operationId": "deleteHandset",
        "summary": "Remove a handset from a DECT base",
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/templates": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "listTemplates",
        "summary": "List templates",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of templates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Templates"
        ],
        "operationId": "createTemplate",
        "summary": "Create a template",
        "description": "`settings` maps Yealink configuration parameter names to values, exactly as they appear in a Yealink `.cfg` file. Values may contain variables in dollar-brace form, such as `${device.label}`, `${company.name}`, `${site.timezone}` and `${line.1.username}`, which are filled in per device when the configuration is rendered.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplateCreate"
              },
              "example": {
                "name": "Dental front office",
                "slug": "dental-front-office",
                "applies_to_models": [],
                "settings": {
                  "local_time.time_zone_name": "${site.timezone}",
                  "features.call_waiting.enable": "1",
                  "phone_setting.backlight_time": "60"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The template was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Template"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/templates/{template}": {
      "parameters": [
        {
          "name": "template",
          "in": "path",
          "required": true,
          "description": "Template slug.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "getTemplate",
        "summary": "Get a template",
        "responses": {
          "200": {
            "description": "The template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Template"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Templates"
        ],
        "operationId": "updateTemplate",
        "summary": "Update a template",
        "description": "`settings` replaces the stored settings entirely when present. Every device that uses the template is marked for resync; the response reports how many.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplateUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Template"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "tags": [
          "Templates"
        ],
        "operationId": "deleteTemplate",
        "summary": "Delete a template",
        "description": "Fails with `409` and code `template_in_use` while any company, site or device still references it.",
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listModels",
        "summary": "List supported Yealink models",
        "description": "Returns every model PhoneLink can provision, with the capabilities the panels and templates rely on. Use the `id` values as `model` when adding devices.",
        "parameters": [
          {
            "name": "family",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ModelFamily"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The supported models.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/key-types": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listKeyTypes",
        "summary": "List line key types",
        "description": "Returns every function a line key can be given, such as BLF, speed dial or call park. Each entry says what `value` and `extension` mean for that key and whether it is tied to a kind of SIP platform. Adding or updating a device with a key its line's platform cannot use returns `422`.",
        "responses": {
          "200": {
            "description": "The key types.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/KeyType"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/firmware": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listFirmware",
        "summary": "List available firmware",
        "description": "The firmware versions PhoneLink staff have made available. Pin one for a group of phones by setting `firmware_version` on a template: each phone on that template whose model the version covers is told to install it at its next check-in. The most specific template that names a version wins.",
        "parameters": [
          {
            "name": "model",
            "in": "query",
            "description": "Only firmware that applies to this model.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The available firmware.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Firmware"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhooks",
        "summary": "List webhook endpoints",
        "responses": {
          "200": {
            "description": "The endpoints.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "createWebhook",
        "summary": "Add a webhook endpoint",
        "description": "The response includes `signing_secret` once. Store it; it is not returned again. The address must be https and reachable from the internet. An account can have 10 endpoints.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCreate"
              },
              "example": {
                "url": "https://example.com/hooks/phonelink",
                "events": [
                  "device.first_boot",
                  "device.offline",
                  "device.online"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The endpoint was added.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookWithSecret"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/webhooks/{webhook_id}": {
      "parameters": [
        {
          "name": "webhook_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhook",
        "summary": "Get a webhook endpoint",
        "responses": {
          "200": {
            "description": "The endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "updateWebhook",
        "summary": "Update a webhook endpoint",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/EventType"
                    }
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        },
        "description": "Setting `enabled` to true also restarts an endpoint PhoneLink had stopped sending to."
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhook",
        "summary": "Remove a webhook endpoint",
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "listEvents",
        "summary": "List account activity",
        "description": "Returns the activity log, newest first: device check-ins that changed state, configuration changes and who made them. The same events are sent to webhooks.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          {
            "name": "company",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mac",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "description": "Only events at or after this time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/sip-platforms": {
      "get": {
        "tags": [
          "SIP platforms"
        ],
        "operationId": "listSipPlatforms",
        "summary": "List SIP platforms",
        "responses": {
          "200": {
            "description": "The account's SIP platforms.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SipPlatform"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "SIP platforms"
        ],
        "operationId": "createSipPlatform",
        "summary": "Add a SIP platform",
        "description": "`type` selects a preset that fills in defaults for any field you leave out; `generic` applies none. The first platform created becomes the account default.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SipPlatformWrite"
              },
              "example": {
                "name": "Harbor Voice Kazoo",
                "type": "kazoo",
                "is_default": true,
                "realm_mode": "company",
                "registrars": [],
                "transport": "udp",
                "outbound_proxies": [
                  {
                    "host": "proxy-east.example.com",
                    "port": 5060
                  },
                  {
                    "host": "proxy-west.example.com",
                    "port": 5060
                  }
                ],
                "register_expires": 300,
                "nat": {
                  "keepalive": "default",
                  "keepalive_interval": 30
                },
                "security": {
                  "srtp": "disabled"
                },
                "media": {
                  "codecs": [
                    "opus",
                    "g722",
                    "pcmu",
                    "pcma"
                  ],
                  "dtmf": "rfc2833"
                },
                "features": {
                  "voicemail_number": "*97"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The platform was added.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SipPlatform"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/sip-platforms/{platform}": {
      "parameters": [
        {
          "name": "platform",
          "in": "path",
          "required": true,
          "description": "SIP platform slug.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "SIP platforms"
        ],
        "operationId": "getSipPlatform",
        "summary": "Get a SIP platform",
        "responses": {
          "200": {
            "description": "The platform.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SipPlatform"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "SIP platforms"
        ],
        "operationId": "updateSipPlatform",
        "summary": "Update a SIP platform",
        "description": "Send only the fields you want to change. Arrays and nested objects replace the stored value when present. Every device with a line on this platform is marked for resync, and phones re-register when they next fetch their configuration.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SipPlatformWrite"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated platform.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SipPlatform"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "tags": [
          "SIP platforms"
        ],
        "operationId": "deleteSipPlatform",
        "summary": "Delete a SIP platform",
        "description": "Fails with `409` and code `sip_platform_in_use` while any company or line still references it.",
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/devices/{mac}/provisioning-log": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Logs"
        ],
        "operationId": "getDeviceProvisioningLog",
        "summary": "List a device's provisioning requests",
        "description": "Every request the phone made to PhoneLink, newest first, and what it was given. Use it to confirm a change reached the phone. Routine check-ins that needed no change are returned as `not_modified`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "result",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only requests with this result. `refused` matches every refused result."
          },
          {
            "name": "changes_only",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Only requests that delivered a new version."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of requests.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProvisioningRequest"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/provisioning-log": {
      "get": {
        "tags": [
          "Logs"
        ],
        "operationId": "listProvisioningLog",
        "summary": "List provisioning requests across the account",
        "description": "The same log for every device, for spotting failures across a company or a whole account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "result",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only requests with this result. `refused` matches every refused result."
          },
          {
            "name": "changes_only",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Only requests that delivered a new version."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "company",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mac",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of requests.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProvisioningRequest"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/devices/{mac}/log-captures": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Logs"
        ],
        "operationId": "listLogCaptures",
        "summary": "List a device's log captures",
        "responses": {
          "200": {
            "description": "The captures.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LogCapture"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Logs"
        ],
        "operationId": "startLogCapture",
        "summary": "Capture a phone's own log",
        "description": "Asks the phone to send its own log to PhoneLink for a limited time. The instruction reaches the phone at its next check-in, so the capture starts as `pending`; the phone then uploads about once a minute. Only one capture can run per device. Captures are kept for 7 days.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "level": {
                    "type": "string",
                    "enum": [
                      "normal",
                      "sip"
                    ],
                    "default": "normal"
                  },
                  "duration_minutes": {
                    "type": "integer",
                    "enum": [
                      30,
                      120,
                      1440
                    ],
                    "default": 30
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The capture was requested.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogCapture"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/devices/{mac}/log-captures/{capture_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        },
        {
          "name": "capture_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Logs"
        ],
        "operationId": "getLogCapture",
        "summary": "Get a log capture",
        "responses": {
          "200": {
            "description": "The capture.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogCapture"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Logs"
        ],
        "operationId": "cancelLogCapture",
        "summary": "Stop a capture and delete its log",
        "responses": {
          "204": {
            "description": "Stopped and deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/devices/{mac}/calls": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Quality and health"
        ],
        "operationId": "listDeviceCalls",
        "summary": "List a device's call quality reports",
        "description": "One entry per call, newest first.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "rating",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "good",
                "fair",
                "poor"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of reports.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CallQuality"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/quality": {
      "get": {
        "tags": [
          "Quality and health"
        ],
        "operationId": "getQualitySummary",
        "summary": "Aggregate call quality",
        "description": "Totals and averages over a period, grouped the way you choose. Grouping by `site` or `media_host` shows whether poor calls cluster at one location or one media server.",
        "parameters": [
          {
            "name": "group_by",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "company",
                "site",
                "device",
                "media_host"
              ]
            }
          },
          {
            "name": "company",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mac",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The buckets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QualityBucket"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/devices/{mac}/health": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Quality and health"
        ],
        "operationId": "getDeviceHealth",
        "summary": "Get a device's health summary",
        "parameters": [
          {
            "name": "period_days",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                7,
                30,
                90
              ],
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The summary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceHealth"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/auth/register": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "register",
        "summary": "Create an account",
        "responses": {
          "201": {
            "description": "A confirmation email was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "description": "Open to anyone. Sends an email with a link to confirm the address. The account can manage 500 devices free.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account_name": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 10
                  },
                  "customer_type": {
                    "type": "string",
                    "enum": [
                      "smb",
                      "enterprise",
                      "msp",
                      "telco"
                    ],
                    "description": "What kind of organization the account is. `smb` and `enterprise` run their own phones; `msp` manages phones for its customers; `telco` sells phone service."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country code.",
                    "examples": [
                      "US"
                    ]
                  },
                  "phone": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  },
                  "expected_devices": {
                    "type": "string",
                    "enum": [
                      "1-50",
                      "51-500",
                      "501-5000",
                      "5000+"
                    ],
                    "description": "Roughly how many phones the account expects to manage."
                  },
                  "phone_system": {
                    "type": "string",
                    "description": "What the phones will register to, for example Kazoo."
                  }
                },
                "required": [
                  "account_name",
                  "name",
                  "email",
                  "password",
                  "customer_type"
                ]
              }
            }
          }
        },
        "security": []
      }
    },
    "/auth/verify": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "verifyEmail",
        "summary": "Confirm an email address",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Send as a bearer token."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "token",
                    "expires_at"
                  ]
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        },
        "description": "Takes the token from the emailed link and starts a session.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "security": []
      }
    },
    "/auth/login": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "login",
        "summary": "Sign in",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Send as a bearer token."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "token",
                    "expires_at"
                  ]
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  }
                },
                "required": [
                  "email",
                  "password"
                ]
              }
            }
          }
        },
        "security": []
      }
    },
    "/auth/forgot": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "forgotPassword",
        "summary": "Request a password reset email",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "description": "Always answers the same way, whether or not the address has an account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "security": []
      }
    },
    "/auth/reset": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "resetPassword",
        "summary": "Set a new password",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Send as a bearer token."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "token",
                    "expires_at"
                  ]
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        },
        "description": "Takes the token from the emailed link, ends every existing session and starts a new one.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 10
                  }
                },
                "required": [
                  "token",
                  "password"
                ]
              }
            }
          }
        },
        "security": []
      }
    },
    "/auth/logout": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "logout",
        "summary": "End the current session",
        "responses": {
          "204": {
            "description": "Signed out."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api-keys": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "listApiKeys",
        "summary": "List API keys",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "prefix": {
                            "type": "string",
                            "description": "The first characters of the key, for recognizing it."
                          },
                          "scope": {
                            "type": "string",
                            "enum": [
                              "read_only",
                              "read_write"
                            ]
                          },
                          "last_used_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "description": "Needs a signed-in user; an API key cannot manage keys."
      },
      "post": {
        "tags": [
          "Account"
        ],
        "operationId": "createApiKey",
        "summary": "Create an API key",
        "responses": {
          "201": {
            "description": "The key was created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "prefix": {
                          "type": "string",
                          "description": "The first characters of the key, for recognizing it."
                        },
                        "scope": {
                          "type": "string",
                          "enum": [
                            "read_only",
                            "read_write"
                          ]
                        },
                        "last_used_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "key"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        },
        "description": "The full key is in the response once and is never shown again. Needs a signed-in owner or admin.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "scope": {
                    "type": "string",
                    "enum": [
                      "read_only",
                      "read_write"
                    ],
                    "default": "read_write"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      }
    },
    "/api-keys/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "tags": [
          "Account"
        ],
        "operationId": "revokeApiKey",
        "summary": "Revoke an API key",
        "responses": {
          "204": {
            "description": "Revoked."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/assets": {
      "get": {
        "tags": [
          "Images"
        ],
        "operationId": "listImages",
        "summary": "List images",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Image"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Images"
        ],
        "operationId": "uploadImage",
        "summary": "Upload an image",
        "description": "PNG, JPEG or WebP, up to 10 MB. PhoneLink produces one JPEG per color screen size. `cover` fills the screen and crops what overflows; `contain` shows the whole image on the background color, which suits logos. Transparent areas become the background color. Send the text fields before the file.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "wallpaper",
                      "logo"
                    ],
                    "default": "wallpaper"
                  },
                  "fit": {
                    "type": "string",
                    "enum": [
                      "cover",
                      "contain"
                    ]
                  },
                  "background": {
                    "type": "string",
                    "default": "#000000"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The image was stored and resized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Image"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/assets/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "tags": [
          "Images"
        ],
        "operationId": "deleteImage",
        "summary": "Delete an image",
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "description": "Companies and devices using it fall back to no wallpaper."
      }
    },
    "/assets/{id}/file/{variant}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "variant",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "example": "480x272"
        }
      ],
      "get": {
        "tags": [
          "Images"
        ],
        "operationId": "getImageFile",
        "summary": "Download one resized image",
        "responses": {
          "200": {
            "description": "The image.",
            "content": {
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/devices/{mac}/screen": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "get": {
        "tags": [
          "Devices"
        ],
        "operationId": "getDeviceScreen",
        "summary": "Describe a device's idle screen",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "available": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string"
                    },
                    "width": {
                      "type": "integer"
                    },
                    "height": {
                      "type": "integer"
                    },
                    "color": {
                      "type": "boolean"
                    },
                    "touch": {
                      "type": "boolean"
                    },
                    "size_verified": {
                      "type": "boolean",
                      "description": "False when the screen size has not been checked against Yealink's datasheet."
                    },
                    "wallpaper_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "clock": {
                      "type": "object",
                      "properties": {
                        "timezone": {
                          "type": "string"
                        },
                        "time_format": {
                          "type": "string",
                          "enum": [
                            "12h",
                            "24h"
                          ]
                        }
                      }
                    },
                    "title": {
                      "type": "string"
                    },
                    "keys_left": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "position": {
                            "type": "integer"
                          },
                          "type": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "keys_right": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "position": {
                            "type": "integer"
                          },
                          "type": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "softkeys": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "description": "What the phone's idle screen shows, for drawing a preview: resolution, wallpaper, clock and line keys. An approximation built from the device's settings, not a capture of the real screen."
      }
    },
    "/admin/overview": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "operationId": "adminOverview",
        "summary": "Platform totals and replica activity",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "integer"
                    },
                    "companies": {
                      "type": "integer"
                    },
                    "devices": {
                      "type": "integer"
                    },
                    "online": {
                      "type": "integer"
                    },
                    "waiting_first_boot": {
                      "type": "integer"
                    },
                    "unclaimed": {
                      "type": "integer"
                    },
                    "refused_requests_24h": {
                      "type": "integer"
                    },
                    "provisioning_nodes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "node": {
                            "type": "string"
                          },
                          "requests": {
                            "type": "integer"
                          },
                          "last_request_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/admin/accounts": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "operationId": "adminListAccounts",
        "summary": "List customer accounts",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "active",
                              "suspended"
                            ]
                          },
                          "device_limit": {
                            "type": "integer"
                          },
                          "company_count": {
                            "type": "integer"
                          },
                          "device_count": {
                            "type": "integer"
                          },
                          "owner_email": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/admin/accounts/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "tags": [
          "Platform admin"
        ],
        "operationId": "adminUpdateAccount",
        "summary": "Change an account's device limit or status",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "active",
                        "suspended"
                      ]
                    },
                    "device_limit": {
                      "type": "integer"
                    },
                    "company_count": {
                      "type": "integer"
                    },
                    "device_count": {
                      "type": "integer"
                    },
                    "owner_email": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        },
        "description": "Raising the device limit is how an account moves past the free tier until billing exists. Suspending an account signs its users out and refuses its phones.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "device_limit": {
                    "type": "integer"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "suspended"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/admin/unclaimed-devices": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "operationId": "adminListUnclaimed",
        "summary": "List phones no account has claimed",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "mac": {
                            "type": "string"
                          },
                          "first_seen_at": {
                            "type": "string"
                          },
                          "last_seen_at": {
                            "type": "string"
                          },
                          "attempts": {
                            "type": "integer"
                          },
                          "model": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "firmware_version": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "ip_address": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "description": "Phones that asked the provisioning domain for configuration before anyone added them."
      }
    },
    "/devices/{mac}/register-rps": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        }
      ],
      "post": {
        "tags": [
          "Devices"
        ],
        "operationId": "registerDeviceWithRps",
        "summary": "Register a device with Yealink RPS",
        "description": "Tries again for a device that Yealink rejected, or that was added with `register_rps` false or before RPS was switched on. Returns the new RPS state.",
        "responses": {
          "200": {
            "description": "The outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RpsState"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/admin/firmware": {
      "post": {
        "tags": [
          "Platform admin"
        ],
        "operationId": "adminAddFirmware",
        "summary": "Make a firmware version available",
        "description": "Records a version, the models it is for and the address phones download it from. PhoneLink stores the address, not the file.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "version",
                  "models",
                  "url"
                ],
                "properties": {
                  "version": {
                    "type": "string",
                    "examples": [
                      "96.86.0.75"
                    ]
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "released_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date"
                  },
                  "recommended": {
                    "type": "boolean"
                  },
                  "notes": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The version was added.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Firmware"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/admin/firmware/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "tags": [
          "Platform admin"
        ],
        "operationId": "adminRemoveFirmware",
        "summary": "Remove a firmware version",
        "description": "Phones pinned to it are left on whatever they are running.",
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/devices/{mac}/log-captures/{capture_id}/download": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Mac"
        },
        {
          "name": "capture_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Logs"
        ],
        "operationId": "downloadLogCapture",
        "summary": "Download a captured log",
        "description": "Everything the phone has sent so far, as plain text, in the order it arrived.",
        "responses": {
          "200": {
            "description": "The log.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/team": {
      "get": {
        "tags": [
          "Team"
        ],
        "operationId": "getTeam",
        "summary": "List the team and waiting invitations",
        "responses": {
          "200": {
            "description": "The team.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "members": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TeamMember"
                      }
                    },
                    "invitations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invitation"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/team/invitations": {
      "post": {
        "tags": [
          "Team"
        ],
        "operationId": "inviteTeammate",
        "summary": "Invite someone by email",
        "description": "Sends an email with a link that works for 7 days. Inviting an address that already has a waiting invitation sends a fresh link and cancels the old one. An address that already has a PhoneLink account cannot be invited.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "role"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "member",
                      "viewer"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The invitation was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invitation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/team/invitations/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "tags": [
          "Team"
        ],
        "operationId": "withdrawInvitation",
        "summary": "Withdraw an invitation",
        "responses": {
          "204": {
            "description": "Withdrawn. The emailed link stops working."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/team/members/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "tags": [
          "Team"
        ],
        "operationId": "changeTeammateRole",
        "summary": "Change someone's role",
        "description": "The owner's role cannot be changed, and nobody can change their own.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "member",
                      "viewer"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated member.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamMember"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "delete": {
        "tags": [
          "Team"
        ],
        "operationId": "removeTeammate",
        "summary": "Remove someone from the team",
        "description": "They are signed out everywhere at once. The owner cannot be removed, and nobody can remove themselves.",
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/auth/invitation": {
      "get": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "getInvitation",
        "summary": "Look at an invitation",
        "description": "What the emailed link is for, so the page can say which account the person is joining.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The invitation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account_name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The invitation has expired or was withdrawn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/auth/accept-invitation": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "acceptInvitation",
        "summary": "Accept an invitation",
        "description": "Creates the person's sign-in and starts a session. An invitation works once.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token",
                  "name",
                  "password"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Send as a bearer token."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "token",
                    "expires_at"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The invitation has expired, was withdrawn or was already used.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "webhooks": {
    "event": {
      "post": {
        "summary": "Event notification",
        "description": "Sent to every enabled endpoint subscribed to the event's `type`. Verify `X-PhoneLink-Signature` before trusting the body. The same event can be delivered more than once; use `id` to ignore repeats.",
        "parameters": [
          {
            "name": "X-PhoneLink-Signature",
            "in": "header",
            "required": true,
            "description": "Hex HMAC-SHA256 of the raw request body, keyed with the endpoint's signing secret.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              },
              "example": {
                "id": "evt_01JCK2",
                "type": "device.first_boot",
                "created_at": "2026-11-14T04:31:07Z",
                "company": "lakeside-dental",
                "site": "front-office",
                "mac": "80:5E:C0:3A:11:9F",
                "actor": null,
                "data": {
                  "model": "SIP-T54W",
                  "firmware_version": "96.86.0.70",
                  "ip_address": "203.0.113.24"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx response acknowledges the delivery."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key created in the customer panel, sent as `Authorization: Bearer pl_live_...`."
      }
    },
    "parameters": {
      "Company": {
        "name": "company",
        "in": "path",
        "required": true,
        "description": "Company slug, for example `lakeside-dental`.",
        "schema": {
          "type": "string"
        }
      },
      "Site": {
        "name": "site",
        "in": "path",
        "required": true,
        "description": "Site slug, unique within its company.",
        "schema": {
          "type": "string"
        }
      },
      "Mac": {
        "name": "mac",
        "in": "path",
        "required": true,
        "description": "Device MAC address: 12 hex digits, with or without colons.",
        "schema": {
          "type": "string",
          "pattern": "^([0-9A-Fa-f]{12}|([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2})$"
        },
        "example": "805EC03A119F"
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "The `next_cursor` value from the previous page.",
        "schema": {
          "type": "string"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "Items per page.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "description": "A unique value you generate, so a retried request does not create a duplicate.",
        "schema": {
          "type": "string",
          "maxLength": 255
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The API key is missing, malformed or revoked.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The key is read-only, or the account has reached its device limit (`device_limit_reached`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such resource in this account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with existing data, for example a slug that is taken or a MAC address already claimed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "mac_already_claimed",
                "message": "This MAC address is already registered on PhoneLink.",
                "details": {
                  "mac": "80:5E:C0:3A:11:9F"
                }
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "One or more fields are invalid. `details.fields` names each problem.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. Wait the number of seconds in `Retry-After`.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait before retrying."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable code.",
                "examples": [
                  "mac_already_claimed",
                  "device_limit_reached",
                  "validation_failed",
                  "not_found"
                ]
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "Account": {
        "type": "object",
        "required": [
          "id",
          "name",
          "device_limit",
          "device_count"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "examples": [
              "Harbor Voice"
            ]
          },
          "device_limit": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Maximum devices allowed, or null for no limit."
          },
          "device_count": {
            "type": "integer"
          },
          "company_count": {
            "type": "integer"
          },
          "provisioning_url": {
            "type": "string"
          },
          "check_in_interval_seconds": {
            "type": "integer"
          },
          "user": {
            "type": [
              "object",
              "null"
            ],
            "description": "The signed-in user, or null for an API key."
          },
          "customer_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "smb",
              "enterprise",
              "msp",
              "telco",
              null
            ]
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Company": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "created_at"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "Unique within the account. Used in URLs.",
            "examples": [
              "lakeside-dental"
            ]
          },
          "name": {
            "type": "string"
          },
          "template": {
            "type": [
              "string",
              "null"
            ],
            "description": "Slug of the template applied to every device in the company."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your own identifier for this company, for example the tenant ID in your phone system."
          },
          "site_count": {
            "type": "integer",
            "readOnly": true
          },
          "device_count": {
            "type": "integer",
            "readOnly": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "sip_platform": {
            "type": [
              "string",
              "null"
            ],
            "description": "Slug of the SIP platform this company's lines use unless a line names another."
          },
          "sip_realm": {
            "type": [
              "string",
              "null"
            ],
            "description": "This company's realm, used when the platform's `realm_mode` is `company`.",
            "examples": [
              "lakeside.sip.example.com"
            ]
          },
          "wallpaper": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of an image shown on every color-screen phone in the company."
          },
          "online_count": {
            "type": "integer",
            "readOnly": true
          },
          "waiting_count": {
            "type": "integer",
            "readOnly": true
          }
        }
      },
      "CompanyCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          },
          "template": {
            "type": "string"
          },
          "external_id": {
            "type": "string"
          },
          "sites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SiteCreate"
            }
          },
          "sip_platform": {
            "type": [
              "string",
              "null"
            ],
            "description": "Slug of the SIP platform this company's lines use unless a line names another."
          },
          "sip_realm": {
            "type": [
              "string",
              "null"
            ],
            "description": "This company's realm, used when the platform's `realm_mode` is `company`.",
            "examples": [
              "lakeside.sip.example.com"
            ]
          },
          "wallpaper": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of an image shown on every color-screen phone in the company."
          }
        }
      },
      "CompanyUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "sip_platform": {
            "type": [
              "string",
              "null"
            ],
            "description": "Slug of the SIP platform this company's lines use unless a line names another."
          },
          "sip_realm": {
            "type": [
              "string",
              "null"
            ],
            "description": "This company's realm, used when the platform's `realm_mode` is `company`.",
            "examples": [
              "lakeside.sip.example.com"
            ]
          },
          "wallpaper": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of an image shown on every color-screen phone in the company."
          }
        }
      },
      "CompanyList": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Company"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Site": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "company"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "examples": [
              "front-office"
            ]
          },
          "name": {
            "type": "string"
          },
          "company": {
            "type": "string",
            "readOnly": true
          },
          "timezone": {
            "type": "string",
            "description": "IANA time zone name, used for the phones' clocks.",
            "examples": [
              "America/New_York"
            ]
          },
          "template": {
            "type": [
              "string",
              "null"
            ],
            "description": "Slug of the template applied to every device at the site."
          },
          "device_count": {
            "type": "integer",
            "readOnly": true
          },
          "time_format": {
            "type": "string",
            "enum": [
              "12h",
              "24h"
            ],
            "default": "12h"
          }
        }
      },
      "SiteCreate": {
        "type": "object",
        "required": [
          "name",
          "timezone"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          },
          "timezone": {
            "type": "string"
          },
          "template": {
            "type": "string"
          },
          "time_format": {
            "type": "string",
            "enum": [
              "12h",
              "24h"
            ],
            "default": "12h"
          }
        }
      },
      "SiteUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          },
          "time_format": {
            "type": "string",
            "enum": [
              "12h",
              "24h"
            ],
            "default": "12h"
          }
        }
      },
      "SiteList": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Site"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "DeviceStatus": {
        "type": "string",
        "enum": [
          "waiting_first_boot",
          "online",
          "offline",
          "suspended"
        ],
        "description": "`waiting_first_boot`: added but never seen. `online`: checked in within its last three check-in intervals. `offline`: missed three check-ins in a row. `suspended`: PhoneLink has stopped serving it configuration, for example because of a MAC ownership conflict. This is about reaching PhoneLink; line registration is reported separately on each line."
      },
      "Line": {
        "type": "object",
        "required": [
          "position",
          "username"
        ],
        "properties": {
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "Account number on the phone, starting at 1. The maximum depends on the model; see `max_lines` in `GET /models`."
          },
          "enabled": {
            "type": "boolean",
            "default": true
          },
          "sip_platform": {
            "type": [
              "string",
              "null"
            ],
            "description": "Slug of the SIP platform. Null uses the company's, then the account default."
          },
          "realm": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required when the platform's `realm_mode` is `line`; otherwise leave null to inherit."
          },
          "username": {
            "type": "string",
            "description": "SIP user name: the user part of the address the phone registers."
          },
          "auth_username": {
            "type": [
              "string",
              "null"
            ],
            "description": "Authentication ID for digest authentication, when it differs from `username`."
          },
          "password": {
            "type": "string",
            "writeOnly": true,
            "description": "SIP password. Stored encrypted and never returned."
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Caller name sent with calls."
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Text shown next to the line key."
          },
          "registration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SipRegistration"
              }
            ],
            "description": "Overrides of the platform's settings for this line only. Required, with at least `registrars`, when the line has no platform."
          },
          "registration_state": {
            "type": "string",
            "readOnly": true,
            "enum": [
              "unknown",
              "registered",
              "failed",
              "unregistered"
            ],
            "description": "As last reported by the phone. `unknown` until the phone has reported, or for models that cannot report."
          },
          "registration_reported_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true
          },
          "has_password": {
            "type": "boolean",
            "readOnly": true
          }
        }
      },
      "RpsState": {
        "type": "object",
        "required": [
          "state"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "not_requested",
              "not_supported",
              "not_configured",
              "registered",
              "rejected"
            ],
            "description": "`not_configured` means PhoneLink's RPS integration is not switched on; set the phone up by entering the provisioning domain. `not_supported` means Yealink no longer offers RPS for this model. `rejected` usually means the MAC is registered in another RPS account."
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Detail from Yealink when the state is `rejected`."
          }
        }
      },
      "Device": {
        "type": "object",
        "required": [
          "mac",
          "company",
          "site",
          "status",
          "rps",
          "provisioning_url",
          "created_at"
        ],
        "properties": {
          "mac": {
            "type": "string",
            "examples": [
              "80:5E:C0:3A:11:9F"
            ]
          },
          "company": {
            "type": "string"
          },
          "site": {
            "type": "string"
          },
          "model": {
            "type": [
              "string",
              "null"
            ],
            "description": "Model identifier from `GET /models`. Null until detected when it was not given.",
            "examples": [
              "SIP-T54W"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "A name for the device in the panel, for example who uses it."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "overrides": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Yealink configuration parameters applied last, for this device only."
          },
          "status": {
            "$ref": "#/components/schemas/DeviceStatus"
          },
          "rps": {
            "$ref": "#/components/schemas/RpsState"
          },
          "provisioning_url": {
            "type": "string",
            "format": "uri",
            "readOnly": true,
            "description": "The provisioning server to enter on a phone that is set up by hand. It is the same for every device, `https://042524.com/`: PhoneLink identifies the phone from its MAC address and factory certificate, so no per-company or per-device address is needed.",
            "examples": [
              "https://042524.com/"
            ]
          },
          "firmware_version": {
            "type": [
              "string",
              "null"
            ],
            "readOnly": true,
            "description": "As last reported by the phone."
          },
          "ip_address": {
            "type": [
              "string",
              "null"
            ],
            "readOnly": true,
            "description": "Public address the phone last checked in from."
          },
          "last_seen_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true
          },
          "first_seen_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "check_in_interval_seconds": {
            "type": "integer",
            "readOnly": true,
            "description": "How often this phone is told to check in."
          },
          "config_version": {
            "type": [
              "string",
              "null"
            ],
            "readOnly": true,
            "description": "Short hash of the configuration that is current for this device."
          },
          "applied_config_version": {
            "type": [
              "string",
              "null"
            ],
            "readOnly": true,
            "description": "Short hash of the configuration the phone last fetched."
          },
          "config_in_sync": {
            "type": "boolean",
            "readOnly": true,
            "description": "True when the two versions match."
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ],
            "description": "An IANA time zone that overrides the site's for this one device. Null uses the site's.",
            "examples": [
              "America/Phoenix"
            ]
          },
          "line_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineKey"
            }
          },
          "wallpaper": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of an image to use as this device's wallpaper. Null uses the company's."
          },
          "effective_timezone": {
            "type": "string",
            "readOnly": true,
            "description": "The zone the phone's clock actually uses."
          },
          "already_seen_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Returned when a device is added: when the phone last tried to connect before it was added, if it did."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "company_sip_platform": {
            "type": [
              "string",
              "null"
            ],
            "description": "The slug of the company's SIP platform. Lines without their own platform use it."
          },
          "expansion_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExpansionKey"
            },
            "description": "Keys on expansion modules (sidecars). Each takes the same types as a line key."
          },
          "programmable_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineKey"
            },
            "description": "The soft keys and fixed-function keys a phone lets you reassign, by Yealink's programmable key number (1 to 18). Which numbers exist, and which types each accepts, depends on the model."
          },
          "handsets": {
            "type": "array",
            "readOnly": true,
            "items": {
              "$ref": "#/components/schemas/Handset"
            },
            "description": "For a DECT base. Change them through the handsets endpoints."
          }
        }
      },
      "DeviceCreate": {
        "type": "object",
        "required": [
          "mac",
          "company",
          "site"
        ],
        "properties": {
          "mac": {
            "type": "string"
          },
          "company": {
            "type": "string"
          },
          "site": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "external_id": {
            "type": "string"
          },
          "template": {
            "type": "string"
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "overrides": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "register_rps": {
            "type": "boolean",
            "default": true
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ],
            "description": "An IANA time zone that overrides the site's for this one device. Null uses the site's.",
            "examples": [
              "America/Phoenix"
            ]
          },
          "line_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineKey"
            }
          },
          "wallpaper": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of an image to use as this device's wallpaper. Null uses the company's."
          },
          "expansion_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExpansionKey"
            },
            "description": "Keys on expansion modules (sidecars). Each takes the same types as a line key."
          },
          "programmable_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineKey"
            },
            "description": "The soft keys and fixed-function keys a phone lets you reassign, by Yealink's programmable key number (1 to 18). Which numbers exist, and which types each accepts, depends on the model."
          }
        }
      },
      "DeviceUpdate": {
        "type": "object",
        "properties": {
          "company": {
            "type": "string"
          },
          "site": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "overrides": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "register_rps": {
            "type": "boolean"
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ],
            "description": "An IANA time zone that overrides the site's for this one device. Null uses the site's.",
            "examples": [
              "America/Phoenix"
            ]
          },
          "line_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineKey"
            }
          },
          "wallpaper": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of an image to use as this device's wallpaper. Null uses the company's."
          },
          "expansion_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExpansionKey"
            },
            "description": "Keys on expansion modules (sidecars). Each takes the same types as a line key."
          },
          "programmable_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineKey"
            },
            "description": "The soft keys and fixed-function keys a phone lets you reassign, by Yealink's programmable key number (1 to 18). Which numbers exist, and which types each accepts, depends on the model."
          }
        }
      },
      "DeviceList": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Device"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "BulkResult": {
        "type": "object",
        "required": [
          "created",
          "failed",
          "results"
        ],
        "properties": {
          "created": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "mac",
                "ok"
              ],
              "properties": {
                "mac": {
                  "type": "string"
                },
                "ok": {
                  "type": "boolean"
                },
                "device": {
                  "$ref": "#/components/schemas/Device"
                },
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ActionQueued": {
        "type": "object",
        "required": [
          "queued"
        ],
        "properties": {
          "queued": {
            "type": "boolean"
          },
          "expected_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the phone is next expected to check in."
          }
        }
      },
      "RenderedConfig": {
        "type": "object",
        "required": [
          "mac",
          "settings"
        ],
        "properties": {
          "mac": {
            "type": "string"
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "settings": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "key",
                "value",
                "source"
              ],
              "properties": {
                "key": {
                  "type": "string",
                  "examples": [
                    "account.1.user_name"
                  ]
                },
                "value": {
                  "type": "string"
                },
                "source": {
                  "type": "string",
                  "description": "The layer that set the value.",
                  "examples": [
                    "template:dental-front-office",
                    "site:front-office",
                    "device:overrides",
                    "device:lines"
                  ]
                }
              }
            }
          }
        }
      },
      "Handset": {
        "type": "object",
        "required": [
          "slot",
          "line"
        ],
        "properties": {
          "slot": {
            "type": "integer",
            "minimum": 1
          },
          "ipui": {
            "type": [
              "string",
              "null"
            ],
            "description": "The handset's DECT identity, printed in its settings menu. Recorded for reference."
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "line": {
            "type": "integer",
            "description": "The `position` of the base's line this handset uses."
          }
        }
      },
      "HandsetCreate": {
        "type": "object",
        "required": [
          "line"
        ],
        "properties": {
          "slot": {
            "type": "integer",
            "minimum": 1,
            "description": "Omit to use the next free slot."
          },
          "ipui": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "line": {
            "type": "integer"
          }
        }
      },
      "Template": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "settings"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_account_default": {
            "type": "boolean",
            "description": "When true the template applies to every device in the account as the first layer."
          },
          "applies_to_models": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "When not empty, the template is a model template and applies only to these models."
          },
          "firmware_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pin devices that use this template to a firmware version from `GET /firmware`. Null leaves firmware unmanaged."
          },
          "settings": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Yealink configuration parameter names mapped to values."
          },
          "device_count": {
            "type": "integer",
            "readOnly": true,
            "description": "Devices this template currently applies to."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "TemplateCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          },
          "description": {
            "type": "string"
          },
          "is_account_default": {
            "type": "boolean",
            "default": false
          },
          "applies_to_models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "firmware_version": {
            "type": "string"
          },
          "settings": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "TemplateUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_account_default": {
            "type": "boolean"
          },
          "applies_to_models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "firmware_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "settings": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "TemplateList": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Template"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ModelFamily": {
        "type": "string",
        "enum": [
          "t3",
          "t4",
          "t5",
          "t7",
          "t8",
          "dect",
          "conference",
          "wifi"
        ]
      },
      "Model": {
        "type": "object",
        "required": [
          "id",
          "family",
          "kind",
          "rps"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The identifier the phone reports, used as `model` on devices.",
            "examples": [
              "SIP-T54W"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "T54W"
            ]
          },
          "family": {
            "$ref": "#/components/schemas/ModelFamily"
          },
          "kind": {
            "type": "string",
            "enum": [
              "desk_phone",
              "dect_base",
              "dect_multicell",
              "conference_phone",
              "wifi_handset"
            ]
          },
          "rps": {
            "type": "string",
            "enum": [
              "supported",
              "pin_required",
              "not_supported"
            ],
            "description": "Whether the model can be set up zero-touch through Yealink RPS."
          },
          "max_lines": {
            "type": "integer"
          },
          "line_keys": {
            "type": "integer",
            "description": "Physical or on-screen programmable line keys."
          },
          "wifi": {
            "type": "boolean"
          },
          "bluetooth": {
            "type": "boolean"
          },
          "max_handsets": {
            "type": [
              "integer",
              "null"
            ],
            "description": "For DECT bases, how many handsets can be paired."
          },
          "lifecycle": {
            "type": "string",
            "enum": [
              "current",
              "legacy"
            ],
            "description": "`legacy` models are no longer sold by Yealink but can still be provisioned."
          },
          "screen": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              },
              "color": {
                "type": "boolean"
              },
              "touch": {
                "type": "boolean"
              },
              "size_verified": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "Firmware": {
        "type": "object",
        "required": [
          "version",
          "models"
        ],
        "properties": {
          "version": {
            "type": "string",
            "examples": [
              "96.86.0.70"
            ]
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "released_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "recommended": {
            "type": "boolean",
            "description": "The version PhoneLink currently recommends for these models."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Where phones download the file. Shown to PhoneLink staff only."
          }
        }
      },
      "EventType": {
        "type": "string",
        "enum": [
          "device.created",
          "device.updated",
          "device.deleted",
          "device.first_boot",
          "device.online",
          "device.offline",
          "device.restarted",
          "device.line_registered",
          "device.line_register_failed",
          "device.line_unregistered",
          "device.log_capture_finished",
          "firmware.upgraded",
          "quality.poor_call"
        ]
      },
      "Event": {
        "type": "object",
        "required": [
          "id",
          "type",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "$ref": "#/components/schemas/EventType"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "company": {
            "type": [
              "string",
              "null"
            ]
          },
          "mac": {
            "type": [
              "string",
              "null"
            ]
          },
          "actor": {
            "type": [
              "object",
              "null"
            ],
            "description": "Who caused the event, or null when the phone or PhoneLink did.",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "user",
                  "api_key"
                ]
              },
              "name": {
                "type": "string"
              }
            }
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Details that depend on the event type."
          }
        }
      },
      "EventList": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Webhook": {
        "type": "object",
        "required": [
          "id",
          "url",
          "events",
          "enabled"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "delivery_status": {
            "type": "string",
            "enum": [
              "delivering",
              "retrying",
              "disabled"
            ],
            "readOnly": true,
            "description": "`retrying` after a failed delivery. `disabled` once deliveries have failed for 72 hours; set `enabled` to true to start again."
          },
          "last_delivery_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "WebhookCreate": {
        "type": "object",
        "required": [
          "url",
          "events"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Must be HTTPS."
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "enabled": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "WebhookWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Webhook"
          },
          {
            "type": "object",
            "required": [
              "signing_secret"
            ],
            "properties": {
              "signing_secret": {
                "type": "string",
                "description": "Shown once, at creation."
              }
            }
          }
        ]
      },
      "SipHost": {
        "type": "object",
        "required": [
          "host"
        ],
        "properties": {
          "host": {
            "type": "string",
            "description": "Host name or IP address."
          },
          "port": {
            "type": "integer",
            "default": 5060,
            "description": "Use 0 to resolve the port from a DNS SRV record."
          }
        }
      },
      "SipRegistration": {
        "type": "object",
        "description": "Registration settings. On a SIP platform these are the defaults; on a line they override the platform for that line.",
        "properties": {
          "realm_mode": {
            "type": "string",
            "enum": [
              "platform",
              "company",
              "line"
            ],
            "description": "Where the realm (SIP domain) comes from. `platform`: the `realm` on this object, the same for everyone. `company`: each company's `sip_realm`, which is how multi-tenant systems such as Kazoo work. `line`: given on each line."
          },
          "realm": {
            "type": [
              "string",
              "null"
            ],
            "description": "The SIP domain phones register as. Used when `realm_mode` is `platform`."
          },
          "registrars": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "$ref": "#/components/schemas/SipHost"
            },
            "description": "Where REGISTER is addressed. Empty means the realm itself. A second entry is a backup registrar."
          },
          "registrar_mode": {
            "type": "string",
            "enum": [
              "failover",
              "concurrent"
            ],
            "default": "failover",
            "description": "With two registrars: use the second only when the first fails, or register to both at once."
          },
          "transport": {
            "type": "string",
            "enum": [
              "udp",
              "tcp",
              "tls",
              "dns_naptr"
            ],
            "default": "udp",
            "description": "`dns_naptr` lets DNS NAPTR records choose the transport."
          },
          "outbound_proxies": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "$ref": "#/components/schemas/SipHost"
            },
            "description": "When not empty, all SIP traffic is sent to the proxy while the phone still registers as the realm. A second entry is a backup proxy."
          },
          "proxy_failback": {
            "type": "string",
            "enum": [
              "after_interval",
              "on_register",
              "never"
            ],
            "default": "after_interval",
            "description": "When a phone on the backup proxy returns to the main one."
          },
          "proxy_failback_interval": {
            "type": "integer",
            "default": 3600,
            "description": "Seconds, when `proxy_failback` is `after_interval`."
          },
          "register_expires": {
            "type": "integer",
            "default": 3600,
            "description": "Registration lifetime the phone requests, in seconds."
          },
          "register_retry_interval": {
            "type": "integer",
            "default": 30,
            "description": "Seconds between attempts after a failed registration."
          },
          "unregister_on_reboot": {
            "type": "boolean",
            "default": false
          },
          "nat": {
            "type": "object",
            "properties": {
              "keepalive": {
                "type": "string",
                "enum": [
                  "none",
                  "default",
                  "options",
                  "notify"
                ],
                "default": "default",
                "description": "What the phone sends to keep its NAT binding open."
              },
              "keepalive_interval": {
                "type": "integer",
                "default": 30,
                "description": "Seconds."
              },
              "rport": {
                "type": "boolean",
                "default": true
              },
              "stun_server": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "`host:port`, or null when STUN is not used."
              }
            }
          },
          "security": {
            "type": "object",
            "properties": {
              "srtp": {
                "type": "string",
                "enum": [
                  "disabled",
                  "optional",
                  "required"
                ],
                "default": "disabled"
              },
              "tls_verify_certificate": {
                "type": "boolean",
                "default": false,
                "description": "With TLS, accept only server certificates from a trusted authority."
              },
              "trusted_ca_certificate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A PEM certificate to install on phones as an additional trusted authority."
              }
            }
          },
          "media": {
            "type": "object",
            "properties": {
              "codecs": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "opus",
                    "g722",
                    "pcmu",
                    "pcma",
                    "g729",
                    "g726_32",
                    "ilbc"
                  ]
                },
                "description": "In order of preference."
              },
              "dtmf": {
                "type": "string",
                "enum": [
                  "rfc2833",
                  "sip_info",
                  "inband",
                  "auto"
                ],
                "default": "rfc2833"
              },
              "ptime": {
                "type": "integer",
                "default": 20
              }
            }
          },
          "features": {
            "type": "object",
            "properties": {
              "voicemail_number": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "subscribe_mwi": {
                "type": "boolean",
                "default": false,
                "description": "Subscribe for message-waiting notifications instead of waiting for unsolicited ones."
              },
              "shared_line": {
                "type": "string",
                "enum": [
                  "none",
                  "sca",
                  "bla"
                ],
                "default": "none",
                "description": "Shared line appearance style, for platforms such as BroadWorks."
              },
              "feature_key_sync": {
                "type": "boolean",
                "default": false,
                "description": "Keep do-not-disturb and call forwarding in step with the platform."
              },
              "blf_list_uri": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "session_timer": {
                "type": "boolean",
                "default": false
              }
            }
          },
          "extra_settings": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Additional Yealink `account.N.*` parameters, written with `N` in place of the account number, for anything not covered above."
          }
        }
      },
      "SipPlatformWrite": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
              },
              "type": {
                "type": "string",
                "enum": [
                  "generic",
                  "kazoo",
                  "netsapiens",
                  "broadworks",
                  "freeswitch",
                  "asterisk_freepbx",
                  "3cx",
                  "vodia",
                  "portsip",
                  "metaswitch"
                ],
                "default": "generic"
              },
              "is_default": {
                "type": "boolean",
                "description": "Used for lines and companies that name no platform. Setting it true clears it on the previous default."
              }
            }
          },
          {
            "$ref": "#/components/schemas/SipRegistration"
          }
        ]
      },
      "SipPlatform": {
        "allOf": [
          {
            "type": "object",
            "required": [
              "slug",
              "name",
              "type"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
              },
              "type": {
                "type": "string",
                "enum": [
                  "generic",
                  "kazoo",
                  "netsapiens",
                  "broadworks",
                  "freeswitch",
                  "asterisk_freepbx",
                  "3cx",
                  "vodia",
                  "portsip",
                  "metaswitch"
                ],
                "default": "generic"
              },
              "is_default": {
                "type": "boolean",
                "description": "Used for lines and companies that name no platform. Setting it true clears it on the previous default."
              },
              "company_count": {
                "type": "integer",
                "readOnly": true
              },
              "device_count": {
                "type": "integer",
                "readOnly": true
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "readOnly": true
              }
            }
          },
          {
            "$ref": "#/components/schemas/SipRegistration"
          }
        ]
      },
      "ProvisioningRequest": {
        "type": "object",
        "required": [
          "id",
          "at",
          "mac",
          "file",
          "result"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "mac": {
            "type": "string"
          },
          "file": {
            "type": "string",
            "description": "The file the phone asked for.",
            "examples": [
              "805ec03a119f.cfg"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "device_config",
              "common_config",
              "firmware",
              "asset",
              "heartbeat"
            ]
          },
          "result": {
            "type": "string",
            "enum": [
              "served",
              "not_modified",
              "refused_no_certificate",
              "refused_certificate_mismatch",
              "refused_suspended",
              "not_found",
              "error"
            ],
            "description": "`served`: the file was sent. `not_modified`: the phone already had the current version. The `refused_` results mean nothing was sent."
          },
          "http_status": {
            "type": "integer"
          },
          "config_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "Version served, for configuration files."
          },
          "previous_config_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "changes": {
            "type": "array",
            "description": "For a newly served version, the settings that differ from the previous one. Password values are never included.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "from": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "model": {
            "type": [
              "string",
              "null"
            ],
            "description": "As reported in the request."
          },
          "firmware_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "ip_address": {
            "type": "string"
          },
          "node": {
            "type": "string",
            "description": "The PhoneLink provisioning node that answered.",
            "examples": [
              "prov-east-1"
            ]
          },
          "bytes_sent": {
            "type": "integer"
          }
        }
      },
      "LogCapture": {
        "type": "object",
        "required": [
          "id",
          "state",
          "level",
          "duration_minutes"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "pending",
              "capturing",
              "finished",
              "cancelled",
              "never_started"
            ],
            "description": "`pending` until the phone next checks in and receives the instruction."
          },
          "level": {
            "type": "string",
            "enum": [
              "normal",
              "sip"
            ],
            "description": "`sip` also records SIP messages, which include the numbers people dial."
          },
          "duration_minutes": {
            "type": "integer",
            "enum": [
              30,
              120,
              1440
            ]
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "ends_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "line_count": {
            "type": "integer"
          },
          "download_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path of the download, once the phone has sent something."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the captured log is deleted."
          },
          "requested_at": {
            "type": "string",
            "format": "date-time"
          },
          "bytes": {
            "type": "integer"
          }
        }
      },
      "CallQuality": {
        "type": "object",
        "required": [
          "id",
          "mac",
          "ended_at",
          "rating"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "mac": {
            "type": "string"
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "ended_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_seconds": {
            "type": "integer"
          },
          "codec": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "opus"
            ]
          },
          "rating": {
            "type": "string",
            "enum": [
              "good",
              "fair",
              "poor"
            ]
          },
          "mos_lq": {
            "type": [
              "number",
              "null"
            ],
            "description": "Listening quality score, 1.0 to 5.0."
          },
          "mos_cq": {
            "type": [
              "number",
              "null"
            ],
            "description": "Conversational quality score, which also accounts for delay."
          },
          "packet_loss_percent": {
            "type": [
              "number",
              "null"
            ]
          },
          "burst_loss_percent": {
            "type": [
              "number",
              "null"
            ],
            "description": "Loss that arrived in bursts, which is more audible than scattered loss."
          },
          "jitter_ms": {
            "type": [
              "number",
              "null"
            ]
          },
          "jitter_max_ms": {
            "type": [
              "number",
              "null"
            ]
          },
          "round_trip_ms": {
            "type": [
              "number",
              "null"
            ]
          },
          "discarded_percent": {
            "type": [
              "number",
              "null"
            ],
            "description": "Packets that arrived too late to play."
          },
          "remote_media_host": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where the audio came from, typically your media server."
          }
        }
      },
      "QualityBucket": {
        "type": "object",
        "required": [
          "key",
          "calls"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The day (`2026-11-13`), or the company, site, device or media host, according to `group_by`."
          },
          "calls": {
            "type": "integer"
          },
          "average_mos_lq": {
            "type": [
              "number",
              "null"
            ]
          },
          "good": {
            "type": "integer"
          },
          "fair": {
            "type": "integer"
          },
          "poor": {
            "type": "integer"
          },
          "average_packet_loss_percent": {
            "type": [
              "number",
              "null"
            ]
          },
          "average_jitter_ms": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "DeviceHealth": {
        "type": "object",
        "required": [
          "mac",
          "period_days"
        ],
        "properties": {
          "mac": {
            "type": "string"
          },
          "period_days": {
            "type": "integer",
            "examples": [
              30
            ]
          },
          "uptime_percent": {
            "type": [
              "number",
              "null"
            ],
            "description": "Share of the period the phone was reachable, from the offline and online events PhoneLink raised. Null for a phone that has never checked in."
          },
          "offline_periods": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "from": {
                  "type": "string",
                  "format": "date-time"
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              }
            }
          },
          "restarts": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "last_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          },
          "registration": {
            "type": "object",
            "properties": {
              "failures": {
                "type": "integer"
              },
              "last_failure_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          },
          "firmware": {
            "type": "object",
            "properties": {
              "version": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "config_in_sync": {
            "type": "boolean"
          },
          "ip_address_changes": {
            "type": "integer"
          },
          "refused_requests": {
            "type": "integer",
            "description": "Requests for this device's files that PhoneLink refused."
          },
          "quality": {
            "type": "object",
            "properties": {
              "calls": {
                "type": "integer"
              },
              "average_mos_lq": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "poor_calls": {
                "type": "integer"
              }
            }
          },
          "attention": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Codes for anything that needs a look.",
            "examples": [
              [
                "offline",
                "poor_calls"
              ]
            ]
          }
        }
      },
      "Image": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "wallpaper",
              "logo"
            ]
          },
          "name": {
            "type": "string"
          },
          "fit": {
            "type": "string",
            "enum": [
              "cover",
              "contain"
            ]
          },
          "background": {
            "type": "string",
            "examples": [
              "#201E1D"
            ]
          },
          "width": {
            "type": "integer",
            "description": "Of the original."
          },
          "height": {
            "type": "integer"
          },
          "bytes": {
            "type": "integer"
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The sizes prepared, such as `480x272`."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LineKey": {
        "type": "object",
        "properties": {
          "position": {
            "type": "integer",
            "minimum": 1
          },
          "type": {
            "type": "string",
            "enum": [
              "empty",
              "line",
              "blf",
              "blf_list",
              "speed_dial",
              "call_park",
              "retrieve_park",
              "directed_pickup",
              "group_pickup",
              "intercom",
              "voicemail",
              "dtmf",
              "prefix",
              "transfer",
              "forward",
              "dnd",
              "hold",
              "conference",
              "call_return",
              "record",
              "multicast_paging",
              "paging_list",
              "directory",
              "local_group",
              "ldap",
              "url",
              "phone_lock",
              "sms",
              "xml_browser",
              "xml_group",
              "url_record",
              "hot_desking",
              "acd",
              "private_hold",
              "group_listening",
              "zero_touch",
              "custom",
              "meet_me_conference",
              "hoteling",
              "acd_trace",
              "disposition_code",
              "emergency",
              "network_favorite",
              "uc_favorite",
              "buddies",
              "my_status"
            ],
            "description": "The key's function. `GET /key-types` describes each one: what `value` and `extension` mean for it and whether it is tied to a kind of SIP platform."
          },
          "value": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the key acts on. Its meaning depends on the type: the extension a BLF key watches, the number a speed dial calls, a park slot. Required for some types."
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "line": {
            "type": "integer",
            "description": "Which line the key uses. Defaults to 1. Key types tied to a kind of SIP platform need this line to be on such a platform."
          },
          "extension": {
            "type": [
              "string",
              "null"
            ],
            "description": "A second value some types take: the pickup code of a BLF key, the channel of a multicast paging key."
          }
        },
        "required": [
          "position",
          "type"
        ]
      },
      "KeyType": {
        "type": "object",
        "required": [
          "id",
          "name",
          "group",
          "uses_line"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Use as `type` in a line key."
          },
          "name": {
            "type": "string"
          },
          "group": {
            "type": "string",
            "enum": [
              "general",
              "platform",
              "broadworks"
            ],
            "description": "`general` keys work on any phone system. `platform` keys need a feature set up on the phone system or in a template. `broadworks` keys are accepted only when the key's line is on a BroadWorks SIP platform."
          },
          "uses_line": {
            "type": "boolean",
            "description": "Whether the key acts on one of the phone's lines."
          },
          "value": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "label": {
                "type": "string"
              },
              "required": {
                "type": "boolean"
              },
              "example": {
                "type": "string"
              }
            },
            "required": [
              "label",
              "required"
            ],
            "description": "What `value` means for this key, or null when it takes none."
          },
          "extension": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "label": {
                "type": "string"
              },
              "required": {
                "type": "boolean"
              },
              "example": {
                "type": "string"
              }
            },
            "required": [
              "label",
              "required"
            ],
            "description": "What `extension` means for this key, or null when it takes none."
          },
          "sip_platform_types": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "SIP platform types the key's line must be on, or null when any will do."
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ExpansionKey": {
        "allOf": [
          {
            "$ref": "#/components/schemas/LineKey"
          },
          {
            "type": "object",
            "required": [
              "module"
            ],
            "properties": {
              "module": {
                "type": "integer",
                "minimum": 1,
                "maximum": 3,
                "description": "Which expansion module, counting from the one nearest the phone."
              }
            }
          }
        ]
      },
      "TeamMember": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "you": {
            "type": "boolean",
            "description": "True for the person making the request."
          }
        }
      },
      "Invitation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "member",
              "viewer"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "expired": {
            "type": "boolean"
          },
          "invited_by": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}
