---
title: "Reference: routes, permissions and limits"
description: "Every route with the permission it needs and how a retry is made safe; the scopes; the limits."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.invox.page/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference: routes, permissions and limits

Generated from the registry this API serves from, at the moment you asked. The shapes of requests and answers are in the contract: `GET /v1/openapi.json`.

## Routes

| Route | Needs | Retry | What it does |
| --- | --- | --- | --- |
| `GET /health` | no credential | read | Liveness and the deployed version; with deep=1, whether the database has the schema this version expects |
| `GET /v1` | no credential | read | Start here: how to authenticate, where the contract is, and the rules |
| `GET /v1/errors` | no credential | read | The catalog of every error code |
| `GET /v1/errors/{code}` | no credential | read | One error code: what it means and what to do |
| `GET /v1/openapi.json` | no credential | read | The contract of this API (OpenAPI 3.1), generated from the code that serves it |
| `GET /v1/docs` | no credential | read | The guides of this API: the index |
| `GET /v1/docs/{page}` | no credential | read | One guide, as Markdown |
| `GET /v1/me` | any credential | read | Who am I: the actor, the organization, the environment, the permissions and the provider |
| `GET /v1/organizations` | a person's token | read | The organizations of the person, each with its live and its test id |
| `POST /v1/organizations` | a person's token | `Idempotency-Key` | Create an organization and its test twin, with the RUC of the company |
| `GET /v1/organization` | `organization:read` | read | The organization this credential acts on |
| `PATCH /v1/organization` | `organization:write` | safe as it is | Rename the organization (both halves of the pair) |
| `POST /v1/organization/archive` | `organization:write` | safe as it is | Archive the organization (both halves of the pair) |
| `GET /v1/members` | `members:read` | read | The members of the organization |
| `PUT /v1/members/{user_id}` | `members:write` | idempotent | Change the role of a member |
| `DELETE /v1/members/{user_id}` | `members:write` | idempotent | Remove a member, or leave the organization |
| `POST /v1/invitations` | `members:write` | `Idempotency-Key` | Invite a person by email, with a role |
| `GET /v1/invitations` | `members:read` | read | The invitations of the organization, newest first |
| `POST /v1/invitations/accept` | a person's token | safe as it is | Accept an invitation, as the person signed in |
| `POST /v1/invitations/inspect` | a person's token | safe as it is | See an invitation before accepting it, as the person signed in |
| `DELETE /v1/invitations/{id}` | `members:write` | idempotent | Revoke a pending invitation |
| `POST /v1/invitations/{id}/resend` | `members:write` | `Idempotency-Key` | Send a pending invitation again, with a new code |
| `GET /v1/service_accounts` | `service_accounts:read` | read | The service accounts of the organization |
| `POST /v1/service_accounts` | `service_accounts:write` | `Idempotency-Key` | Create a service account |
| `GET /v1/service_accounts/{id}` | `service_accounts:read` | read | One service account |
| `PATCH /v1/service_accounts/{id}` | `service_accounts:write` | safe as it is | Change the name or the scopes of a service account |
| `POST /v1/service_accounts/{id}/disable` | `service_accounts:write` | safe as it is | Disable a service account: all its keys stop working |
| `GET /v1/service_accounts/{id}/keys` | `service_accounts:read` | read | The keys of a service account (never their secrets) |
| `POST /v1/service_accounts/{id}/keys` | `service_accounts:write` | `Idempotency-Key` | Create a key. Its secret is in this answer and nowhere else, ever |
| `DELETE /v1/service_accounts/{id}/keys/{key_id}` | `service_accounts:write` | idempotent | Revoke a key: it stops working at the next request |
| `GET /v1/issuer` | `issuers:read` | read | The issuer of the organization (the RUC that issues) |
| `PUT /v1/issuer` | `issuers:write` | idempotent | Set the fiscal data of the issuer |
| `PATCH /v1/issuer` | `issuers:write` | safe as it is | Change some fields of the issuer, without overwriting what someone else saved |
| `GET /v1/series` | `series:read` | read | The series of the organization, with the last number each one took |
| `POST /v1/series` | `series:write` | `Idempotency-Key` | Create a series |
| `PATCH /v1/series/{id}` | `series:write` | safe as it is | Deactivate, reactivate or move the next number of a series forward |
| `GET /v1/events` | `events:read` | read | What happened in the organization, in order (optionally waiting for the next event) |
| `GET /v1/customers` | `customers:read` | read | The customers of the organization, most recently invoiced first, by cursor |
| `GET /v1/customers/{id}` | `customers:read` | read | One customer |
| `GET /v1/establishments` | `issuers:read` | read | The establishments of the issuer, with their SUNAT annex codes |
| `POST /v1/establishments` | `issuers:write` | `Idempotency-Key` | Register an establishment of the issuer |
| `PATCH /v1/establishments/{code}` | `issuers:write` | safe as it is | Change an establishment |
| `GET /v1/brand` | `templates:read` | read | The brand of the organization |
| `PUT /v1/brand` | `templates:write` | idempotent | Replace the brand of the organization |
| `PATCH /v1/brand` | `templates:write` | safe as it is | Change some entries of the brand, without overwriting what someone else saved |
| `GET /v1/assets` | `templates:read` | read | The image library of the organization |
| `PUT /v1/assets/{name}` | `templates:write` | idempotent | Upload an image to the library, under a name |
| `DELETE /v1/assets/{name}` | `templates:write` | idempotent | Remove an image from the library |
| `GET /v1/fonts` | no credential | read | The fonts a template or the brand may use |
| `GET /v1/print_data/schema` | no credential | read | The JSON Schema of the print data and of a template's manifest, and the template functions |
| `GET /v1/print_data/samples` | no credential | read | The official samples every template is validated with |
| `GET /v1/templates` | `templates:read` | read | The templates of the organization and the shared ones |
| `POST /v1/templates` | `templates:write` | `Idempotency-Key` | Create a template |
| `GET /v1/templates/{id}` | `templates:read` | read | One template, with its draft and its versions |
| `PUT /v1/templates/{id}/draft` | `templates:write` | idempotent | Save the draft of a template |
| `POST /v1/templates/{id}/archive` | `templates:write` | safe as it is | Archive a template |
| `POST /v1/templates/{id}/promote` | `templates:promote` | safe as it is | Choose the version LIVE documents print with |
| `POST /v1/templates/{id}/preview_links` | `templates:write` | `Idempotency-Key` | A secret link to see (or edit) the template without a session |
| `GET /v1/templates/{id}/preview_links` | `templates:read` | read | The preview links of a template |
| `DELETE /v1/templates/{id}/preview_links/{link_id}` | `templates:write` | idempotent | Revoke a preview link |
| `POST /v1/templates/{id}/validate` | `templates:write` | safe as it is | Run every check of the template on its draft (II-D197) |
| `POST /v1/templates/{id}/publish` | `templates:write` | `Idempotency-Key` | Publish the draft as a new version (TEST documents use it at once) |
| `POST /v1/templates/{id}/render` | `templates:read` | safe as it is | Look at a template: its draft, a version or a shared one, as HTML, PNG or PDF (II-D213) |
| `POST /v1/templates/{id}/preview_tokens` | `templates:read` | safe as it is | A short-lived token for the live preview of a template in a page (II-D221) |
| `POST /v1/template_gallery/preview_links` | `templates:write` | `Idempotency-Key` | A secret link to the gallery: your templates and the shared ones, without a session |
| `GET /v1/template_gallery/preview_links` | `templates:read` | read | The links to the gallery |
| `DELETE /v1/template_gallery/preview_links/{link_id}` | `templates:write` | idempotent | Revoke a link to the gallery |
| `GET /v1/template_previews/{secret}` | no credential | read | What a preview link opens: its template, its draft and what the link allows |
| `PUT /v1/template_previews/{secret}/draft` | no credential | idempotent | Save the draft through a preview link (scope edit or publish) |
| `POST /v1/template_previews/{secret}/validate` | no credential | safe as it is | Validate the draft through a preview link (scope edit or publish) |
| `POST /v1/template_previews/{secret}/publish` | no credential | `Idempotency-Key` | Publish the draft through a preview link (scope publish only) |
| `POST /v1/template_previews/{secret}/render` | no credential | safe as it is | Render what a preview link opens (any scope): the paper of the page |
| `GET /v1/template_rooms/{credential}` | no credential | read | The live preview room of a template: a WebSocket told of every save |
| `GET /v1/provider` | `issuers:read` | read | Who answers when this organization issues, per connection, and the state of each provider account |
| `GET /v1/readiness` | `organization:read` | read | What is still missing to issue for real, and who must do each thing |
| `POST /v1/issuer/activate_production` | `issuers:write` | safe as it is | Activate the live organization for production (staff of the service only) |
| `GET /v1/staff/held` | a person's token | read | What is held because the provider gave an answer the service cannot interpret, in every organization, by signature (staff only) |
| `POST /v1/staff/held/release` | a person's token | `Idempotency-Key` | Release held invoices and voids, by signature or by ids, in every organization (staff only) |
| `POST /v1/staff/held/close/preview` | a person's token | safe as it is | See what closing held invoices and voids as failed would do, after asking their provider (staff only) |
| `POST /v1/staff/held/close` | a person's token | `Idempotency-Key` | Close held invoices and voids as failed, with the token of their preview (staff only) |
| `POST /v1/production_access` | `production:request` | `Idempotency-Key` | Ask to enter the production access list |
| `GET /v1/production_access` | `organization:read` | read | The latest access request of the organization and its state |
| `POST /v1/production_access/withdraw` | `production:request` | safe as it is | Withdraw the open access request |
| `POST /v1/production_activation` | `production:request` | `Idempotency-Key` | Send the activation request with the two SUNAT screenshots |
| `GET /v1/production_activation` | `organization:read` | read | The activation request: its state, the note of the staff and the review of each screenshot |
| `PUT /v1/production_activation/files/{kind}` | `production:request` | idempotent | Replace one screenshot while the staff asks for changes |
| `POST /v1/production_activation/resubmit` | `production:request` | safe as it is | Send the activation request again after the requested changes |
| `POST /v1/production_activation/withdraw` | `production:request` | safe as it is | Withdraw the activation request in progress |
| `GET /v1/production_activation/files/{id}/content` | `organization:read` | read | The bytes of a screenshot of this organization |
| `GET /v1/staff/production_access` | a person's token | read | The open access requests of every organization (staff only) |
| `POST /v1/staff/production_access/{id}/accept` | a person's token | safe as it is | Accept an organization on the production access list (staff only) |
| `POST /v1/staff/production_access/{id}/reject` | a person's token | safe as it is | Reject an access request, with a note (staff only) |
| `POST /v1/staff/production_access/{id}/revoke` | a person's token | safe as it is | Revoke the access of an organization, with a note (staff only) |
| `GET /v1/staff/production_activations` | a person's token | read | The activation requests in progress of every organization (staff only) |
| `GET /v1/staff/production_activations/{id}` | a person's token | read | An activation request with everything to review it (staff only) |
| `GET /v1/staff/production_activations/{id}/files/{file_id}/content` | a person's token | read | The bytes of a screenshot of an activation request (staff only) |
| `POST /v1/staff/production_activations/{id}/files/{file_id}/review` | a person's token | safe as it is | Mark a screenshot valid or invalid (staff only) |
| `POST /v1/staff/production_activations/{id}/request_changes` | a person's token | safe as it is | Ask the organization to change its activation request, with a note (staff only) |
| `POST /v1/staff/production_activations/{id}/approve` | a person's token | safe as it is | Approve an activation request: the enrolment with the provider starts (staff only) |
| `POST /v1/staff/production_activations/{id}/reject` | a person's token | safe as it is | Reject an activation request, with a note (staff only) |
| `GET /v1/invoices/export` | `invoices:read` | read | The invoices of a period as a CSV file |
| `GET /v1/test/provider` | `issuers:read` | read | The condition the simulated provider account is in |
| `PUT /v1/test/provider` | `issuers:write` | idempotent | Put the simulated provider account in a condition, or lift it |
| `POST /v1/test/provider/connect_sandbox` | `issuers:write` | safe as it is | Connect this test organization to the provider's sandbox (staff of the service only) |
| `POST /v1/test/invoices/{id}/advance` | `invoices:emit` | safe as it is | Run now the next scheduled step of a test invoice that is waiting |
| `POST /v1/invoices` | `invoices:emit` | `Idempotency-Key` | Issue an invoice (factura or boleta) |
| `POST /v1/invoices/preview` | `invoices:emit` | safe as it is | See what would be issued, without issuing it |
| `GET /v1/invoices` | `invoices:read` | read | Search the invoices of the organization, newest first, by cursor |
| `GET /v1/invoices/{id}` | `invoices:read` | read | One invoice, optionally waiting for its outcome |
| `GET /v1/test/scenarios` | `invoices:read` | read | What the simulated provider can be told to answer |
| `POST /v1/test/invoices/{id}/resolve` | `invoices:emit` | safe as it is | Decide the outcome of a test invoice that waits for one |
| `GET /v1/test/void_scenarios` | `invoices:read` | read | What the simulated provider can be told to answer to a void |
| `POST /v1/invoices/{id}/void/preview` | `invoices:void` | safe as it is | See what voiding an invoice would do, and get the token that allows it |
| `POST /v1/invoices/{id}/void` | `invoices:void` | `Idempotency-Key` | Void an accepted invoice |
| `GET /v1/invoices/{id}/void` | `invoices:read` | read | The latest void of an invoice |
| `POST /v1/invoices/{id}/mark_externally_reversed` | `invoices:void` | `Idempotency-Key` | Record that an accepted invoice was reversed by hand at the provider |
| `POST /v1/test/invoices/{id}/void/resolve` | `invoices:void` | safe as it is | Decide the outcome of a test void that waits for one |
| `POST /v1/test/invoices/{id}/void/advance` | `invoices:void` | safe as it is | Run now the next scheduled step of a test void that is waiting |
| `GET /v1/invoices/{id}/correction` | `invoices:correct` | read | See what correcting a failed or rejected invoice would issue, and get the token that allows it |
| `POST /v1/invoices/{id}/correction` | `invoices:correct` | `Idempotency-Key` | Correct a failed or rejected invoice |
| `GET /v1/invoices/{id}/files` | `invoices:read` | read | The files of an invoice, each with its state |
| `GET /v1/invoices/{id}/files/{kind}` | `invoices:read` | read | The content of one file of an invoice |
| `POST /v1/invoices/{id}/files/pdf/regenerate` | `invoices:emit` | safe as it is | Render the PDF of an invoice again |
| `POST /v1/invoices/{id}/files/{kind}/refetch` | `invoices:emit` | safe as it is | Ask the provider again for a file that failed |
| `POST /v1/invoices/{id}/share_links` | `invoices:emit` | `Idempotency-Key` | A link to share one file of an invoice, revocable |
| `GET /v1/invoices/{id}/share_links` | `invoices:read` | read | The share links of an invoice, with how many times each was opened |
| `DELETE /v1/invoices/{id}/share_links/{link_id}` | `invoices:emit` | idempotent | Revoke a share link: it stops opening at once |
| `POST /v1/invoices/{id}/renders` | `invoices:emit` | `Idempotency-Key` | The invoice printed with another template, as PDF or PNG |
| `GET /v1/invoices/{id}/renders` | `invoices:read` | read | The renders on request of an invoice |
| `GET /v1/invoices/{id}/renders/{render_id}` | `invoices:read` | read | One render on request |
| `GET /v1/invoices/{id}/renders/{render_id}/content` | `invoices:read` | read | The file of a render on request |
| `GET /v1/invoices/{id}/emails` | `invoices:read` | read | The emails of an invoice: what was sent, what was not and why |
| `POST /v1/invoices/{id}/emails` | `invoices:emit` | `Idempotency-Key` | Send the invoice by email again |
| `GET /v1/webhook_endpoints` | `webhooks:read` | read | The webhook destinations of the organization (never their secrets) |
| `POST /v1/webhook_endpoints` | `webhooks:write` | `Idempotency-Key` | Create a webhook destination. Its signing secret is in this answer and nowhere else, ever |
| `GET /v1/webhook_endpoints/{id}` | `webhooks:read` | read | One webhook destination (never its secret) |
| `PATCH /v1/webhook_endpoints/{id}` | `webhooks:write` | safe as it is | Change the URL, the description or the event types of a destination, or disable and enable it |
| `DELETE /v1/webhook_endpoints/{id}` | `webhooks:write` | idempotent | Delete a destination: nothing more is delivered to it |
| `POST /v1/webhook_endpoints/{id}/rotate_secret` | `webhooks:write` | `Idempotency-Key` | Rotate the signing secret. The new one is in this answer and nowhere else, ever |
| `POST /v1/webhook_endpoints/{id}/test` | `webhooks:write` | safe as it is | Send a signed sample event to the destination now, and get what it answered |
| `GET /v1/webhook_endpoints/{id}/deliveries` | `webhooks:read` | read | The delivery log of a destination, newest first |
| `GET /v1/event_types` | no credential | read | The catalog of event types, with an example of what a destination receives for each |
| `GET /v1/events/{id}` | `events:read` | read | One event |
| `GET /v1/events/{id}/deliveries` | `webhooks:read` | read | Where an event went: its delivery to each destination, resends included |
| `POST /v1/events/{id}/resend` | `webhooks:write` | `Idempotency-Key` | Send an event again, to one destination or to every subscribed one |
| `POST /v1/test/events` | `webhooks:write` | `Idempotency-Key` | Fabricate an event about a test invoice, to exercise a receiver |
| `GET /f/{organization_id}/{invoice_id}/{file}` | no credential | read | Download a file by its signed link |
| `GET /s/{code}` | no credential | read | Download a file by its share link |
| `GET /paper/{credential}` | no credential | read | The paper of a preview: the sanitized HTML of a sample, for an iframe (II-D221) |
| `POST /paper/{credential}` | no credential | safe as it is | The paper of a preview with your own edits of the sample data (UX D2) |

## Scopes

A scope is `resource:action`; `write` does not include `read`. `organization:read`, `organization:write`, `members:read`, `members:write`, `service_accounts:read`, `service_accounts:write`, `issuers:read`, `issuers:write`, `series:read`, `series:write`, `invoices:read`, `invoices:emit`, `invoices:void`, `invoices:correct`, `customers:read`, `events:read`, `webhooks:read`, `webhooks:write`, `production:request`, `templates:read`, `templates:write`, `templates:promote`.

## Limits

| Limit | Value |
| --- | --- |
| Requests per IP | 600 every 60 s |
| Emissions per organization | 120 every 60 s (measured, not enforced yet) |
| Waiting calls per credential | 30 every 60 s |
| Renders and validations through a preview link, per IP and per link | 30 every 60 s |
| Papers through a preview link, per IP and per link | 120 every 60 s |
| Longest wait of one call | 60 s |
| Organizations a person may own | 10 |
| Keys per service account | 10 |
| Webhook destinations per organization | 20 |
| Invoices in one export | 50000 |
| Days an invitation lasts | 7 |
| Oldest `issue_date` of a factura, in days | 3 |
| Oldest `issue_date` of a boleta, in days | 7 |

Invox · Electronic invoicing for Peru (SUNAT), built to be operated by agents.

Source: https://docs.invox.page/reference/index.mdx
