--- name: telavox-papi description: Operational context for building against the Telavox Partner API (PAPI). version: 2026.05 license: see https://developer.telavox.com --- # Telavox PAPI — agent skill > Drop this file into any LLM context (Claude Skills, OpenAI custom GPT, > local LLM, anywhere that ingests Markdown). It gives the model > operational context for the Telavox Partner API: identity, base > URL, auth, conventions, safety contract, and pointers to the live > spec / best practices / changelog so the model stays current without > re-reading this file. ## 1. Identity The **Telavox Partner API (PAPI)** is the REST surface Telavox partners use to build white-label and resold integrations across multiple end-customers. Tokens are issued to a dedicated API user inside a *Partner* account — never to a human login — and carry partner-level scope across every customer under that partnership. PAPI is distinct from CAPI (the Customer API): - **CAPI** is per-customer; tokens belong to a person inside one customer organisation. - **PAPI** is per-partnership; tokens belong to an API user that can act across the customers a partner administers. When in doubt: if the integration crosses the customer boundary, it's PAPI. Otherwise it's CAPI. ## 2. Base URL ``` https://partner.telavox.se/partner2/api/papi ``` Stable — no host migration planned. All paths in the OpenAPI reference are relative to this base. ## 3. Authentication Bearer JWT bound to a dedicated API user inside a Partner account. **Minting a token (one-time admin setup):** 1. Sign in to Partner with administrator credentials. 2. Go to **Administration → Users/Groups**. 3. Create a new group (name e.g. "Token Group"), grant it the permission **"Can create their own Partner JWT tokens"**. 4. Go to **Administration → Users/Groups → API-tokens** and create an API user — fill in description + contact email. 5. Assign the API user to both the Admin group and the token group. 6. Copy the JWT immediately. It is shown once and cannot be retrieved again. **Using the token:** ``` Authorization: Bearer ``` **Bearer quirk you must respect.** PAPI's backend strips exactly the literal string `"Bearer "` (with one trailing space) from the Authorization header. Any other auth scheme, missing prefix, or too-short value results in HTTP 500. Always include the literal `Bearer ` prefix. ## 4. Conventions - REST over HTTPS, JSON request and response bodies, UTF-8 encoded. - Bearer JWT auth on every request (see §3). - A PAPI token sees **all customers under the partnership**. Many endpoints take a `{customer}` path parameter — that customer must be one administered by your partnership, otherwise expect 403. - Most list endpoints support filtering by query string (`?invoice-place=`, `?country=`, etc.). Pagination is endpoint- specific — read the spec for the operation you're calling. - Mutating endpoints (POST/PUT/PATCH/DELETE) should be treated as non-idempotent unless the spec says otherwise. If a write request times out, **do not blindly retry** — the request may have applied on the server; surface the ambiguity to the human user. - Phone numbers in payloads use Nordic E.164 / national format (`0701234567`, `+46701234567`). When generating examples, use Nordic numbers, not US/UAE. ## 5. Live references (always current) Treat these URLs as the authoritative state. Re-read at the start of any non-trivial integration session — the OpenAPI spec, best practices, and announcements all change independently of this skill. | What | URL | |---|---| | OpenAPI spec (canonical, machine-readable) | | | Interactive reference (HTML) | | | Best practices (single-fetch, agent-friendly) | | | Spec changelog (machine-generated diff over time) | | | Announcements (machine-readable) | | ## 6. Safety / agent contract You are operating on behalf of a human user against a live production system that bills customers, provisions phone numbers, and stores PII. The following rules are non-negotiable. **Tokens** - Tokens come from the user. Never store, never log, never echo them back to the user verbatim or paste them into chat content. When you must reference a token in your reasoning, refer to it by symbolic placeholder (``). - If a token appears to be exposed in a code sample, redact it before quoting back. **Read vs write** - GET requests are autonomous-safe — make them freely when exploring or answering questions. - POST / PUT / PATCH / DELETE require **explicit user confirmation with a preview of the request body and the customer scope it affects** before sending. A PAPI mutation typically affects one customer's tenancy — surface which customer in the confirmation prompt (e.g. *"This will create branding for customer CUST-42 — confirm?"*). - Never invent endpoints. If the spec doesn't have it, surface that to the user rather than guessing. **Errors and retries** - Honour any `Retry-After` response header literally. Don't retry faster than instructed. - 4xx responses: do not retry. Surface the error body to the user. - 5xx responses: retry with exponential backoff + jitter, capped at 3 attempts. If still failing, surface to the user. - See for the current canonical policy. **Identification** - Set a descriptive `User-Agent` on every request, identifying the integration and a contact for operational issues. Example: `AcmeProvisioning/1.4 (ops@acme.example)`. Generic or missing User-Agent strings may be throttled or blocked. - See . ## 7. Example workflows Both workflows below have been validated against the live OpenAPI spec at ; the cited paths exist. Body shapes are illustrative — fetch the spec for exact request schemas before sending. ### 7.1 Provision a new end-customer A partner is signing up a new SMB and needs to spin up their Telavox tenancy. ``` # 1. Create the customer POST /v1/customers Authorization: Bearer Content-Type: application/json # body: customer name, country, currency, contact info # 2. Find applicable assortment for the customer's country/currency GET /v1/customers/{customer}/assortment/{country}/{currency}/user-licenses Authorization: Bearer # 3. Apply the partner's white-label branding GET /v1/brandings # capture branding-key from the response POST /v1/customers/{customer}/branding-usage Content-Type: application/json # body: { brandingKey } # 4. Provision the first admin via the admin-portal endpoint POST /v1/customers/{customer}/admin-portal Content-Type: application/json # body: admin email, name # 5. Confirm the final state GET /v1/customers/{customer} # capture IDs to persist on the partner side ``` **Things to watch:** - Partial failures are real: customer created in step 1, branding fails in step 3 → orphan customer with no branding. Either rollback (`DELETE /v1/customers/{customer}`) or retry the failed step; surface the choice to the user. - Country / currency combinations are not arbitrary — fetch the available assortment for that pair before assuming product availability. ### 7.2 Bulk migrate customers from another platform A partner is acquiring a competitor and needs to onboard ~200 customers in a window. ``` # 0. Precondition: partner has CSV from old platform with # {customer-name, country, currency, admin-email, plan} per row. # 1. Resolve the partner's branding once (used as input to every row) GET /v1/brandings # 2. For each row, throttled to small batch (≤ 5 concurrent — see # best-practices/traffic): POST /v1/customers # body: customer details POST /v1/customers/{customer}/branding-usage # body: { brandingKey } POST /v1/customers/{customer}/admin-portal # body: admin email + name GET /v1/customers/{customer}/assortment/{country}/{currency}/user-licenses # capture for the order step POST /v1/customers/{customer}/orders # body: licenses to provision, billing destination # 3. Verify all customers landed GET /v1/customers/all/details # cross-check count against the input CSV ``` **Things to watch:** - Checkpoint between rows so the migration can resume mid-run if the loop dies. Persist `(input-row-id → telavox-customer-id)` to disk after each successful row. - Respect concurrency limits (see best-practices/traffic). Don't fire 200 customers in parallel. - Per-customer rollback is the safest unit. If billing fails after assortment is set up, decide per-row whether to delete or retry — don't apply a single decision globally. ## 8. What you can't do here PAPI is partner-scoped administration. It does **not** cover: - **End-user actions for a specific user** (dial, hangup, send SMS, fetch personal call history). Those are CAPI surface (`/v1/extensions/users/me/*` etc.). A partner cannot impersonate end-users through PAPI. - **Webhook subscription for real-time call events.** Not a REST surface on PAPI — talk to Telavox support for the streaming options if you need this. - **Billing operations outside the documented `/orders` surface.** Invoicing-system integration is a separate concern; PAPI exposes order-creation but not collections / dunning / refund flows. - **Per-customer detailed permission editing.** Use the customer's own CAPI surface (with that customer's admin token) for user-level permission changes. If the user asks for any of the above, surface the limitation rather than improvising — and check `/announcements.json` for deprecation notices that may signal upcoming changes here. ## 9. Versioning This skill is versioned by calendar (`2026.05`). It is stale when: - The PAPI OpenAPI spec ships a breaking change. The spec changelog at shows breaking entries with a red badge. - Telavox issues a deprecation announcement affecting PAPI. The announcements feed at is the machine-readable source. At the start of any non-trivial PAPI integration session, the agent should fetch the spec changelog with `?since=` to learn what has changed, and the announcements feed to learn what's planned.