Questions and answers

Short answers, grouped by topic. Each one links to the page that says the rest. Looking for something else? The search box at the top of the guide’s menu finds it across every page and these answers; signed in, the one on the Help page of the console searches the console’s help too. Italian words work as well (iva, firma, modello).

Getting started

How do I make my first call?

Take the starter key from your welcome email and the id of the Hello World template from the console, and send them to POST /api/v1/compose/documents/generate. The answer is the PDF. Read more

How do I sign a document?

Compose it, then create and send an envelope with POST /api/v1/sign/envelopes?send=true, naming the signer and where the signature goes. Or do both in one call with POST /api/v1/flow. Read more

Can the data tick a checkbox in a Word template?

Yes: give the checkbox a name (the bookmark of a legacy checkbox, or the Tag of a checkbox content control) and send "consenso": true to tick it, false to clear it. Leave the key out and the box stays as the template has it. Read more

Is there a ready example in my language?

Yes: cURL, Python and JavaScript for composing, signing and the one-call flow, each with its test variant, ready to copy. Read more

Why is the font in my PDF different from my Word file?

The PDF uses free fonts, so a Word font we cannot install is replaced. Arial, Times New Roman, Courier New, Calibri and Cambria have a twin with the same widths; others (Aptos, Verdana, Georgia) change a little or a lot. The template's page says which of its fonts are replaced. Read more

How do I find my way around the console?

The search is on the Help page; press / or Ctrl-K from any page to get there. A table sorts when you click its header, once up and once down. Settings are grouped by theme with an index at the top (Branding has its own entry in the menu); a form puts each label on the left when there is room. Read more

Can an AI agent write the integration?

Point Claude Code, Codex or Cursor at /llms-full.txt. The prompt it gets never contains your API key. Read more

API keys

How do I get an API key?

In the console: API keys, then Issue a key. Give it a name, tick what it may do and choose how long it lasts; it is shown once, so copy it then. Keys are issued only by you, in your console - never by us. Read more

Which scope does my key need?

documents:compose to compose, signatures:ses to sign, flow:* for the flow, and isTest on top for a test call. A refusal names what was missing in details.missingScopes. Read more

I lost a key. Can you read it back?

No: a key is stored only as a hash, so nobody can read it back. Revoke it and issue a new one on the API keys page. Read more

Testing

How do I make a test call?

Add "isTest": true to settings. Same request, same answer; the PDF carries a red TEST band on every page and has no legal value. Read more

Do test calls use credit?

No. They spend a shared pool of 20 test items a day (unless agreed otherwise), which refills at 00:00 UTC. Every test answer says what is left in output.credits.testRemaining. Read more

Are test calls counted with real ones?

Never. The console, GET /api/v1/usage and the export count production and show test calls apart. Read more

Can a test call ask for a seal or an SMS code?

No. Anything paid at a third party is refused with FEATURE_NOT_AVAILABLE_IN_TEST_MODE before anything is reserved or sent. Read more

Credit and billing

What does a document cost?

2 credits at the standard rate, and a credit is 10 cents: EUR 0.20. A signature request is 10 credits, so a flow (compose and sign in one call) is 12; an SMS code, a seal and a timestamp have rates of their own. Yours are on the console dashboard. Read more

What happens when credit runs out?

The call is refused with QUOTA_EXCEEDED, and nothing is produced or charged. Buy more under Billing, Buy credit. Read more

How do I see what a call cost?

output.credits.items lists it line by line - unit, quantity, credits and whether credit or your plan paid - and the lines add up to output.credits.used. left is your balance after it. Read more

Is there a yearly plan?

EarlyBird, when Billing offers it: EUR 899 a year for 1,200 signatures, 2,400 SMS codes and 5,000 documents, used before your credit; seal and timestamp stay in credit. The counters start again at each renewal. Read more

Can I change or cancel my plan?

Cancel at any time under Billing: it runs to its end, then prepaid credit. Upgrade at any time, paying the price difference, same end date. Moving down or to another plan: in its last thirty days. Until five days before the end you can still change your mind. Read more

Do you keep my card?

No. The card number and its code are typed in Revolut's own form and never reach us. For a plan we keep a Revolut token, the last four digits and the expiry. At a payment you use the saved card or add a new one; for a plan, a new card replaces the saved one. Read more

How do I delete my saved card?

Billing, Plan, Card, Delete card (coordinators). It is deleted at Revolut and the plan stops renewing: it ends on the date we email you, then prepaid credit, with the credit you hold. A top-up will need a card again. In the last thirty days you can turn it back on with a new card. Read more

How much credit can I buy at once?

One purchase is at most EUR 1,000.00, VAT excluded; a larger one is refused with PURCHASE_AMOUNT_TOO_LARGE before any payment. Make several purchases, or contact us for a larger amount. Read more

Which VAT do I pay?

22% in Italy; 0% in any other country (reverse charge in the EU, business or private). If we set another regime for your organisation, that one. Your billing page shows it, read-only. Read more

A different VAT regime applies to us. What do I do?

Tick My VAT treatment is different on the Billing page and say what applies and where it is written. Until we have checked it, purchases are charged at your account's rate; if it holds, we set the regime and customer care may add credit for what was charged. Read more

Am I charged for a call that failed?

No. Only what was delivered is charged: a document, a sent envelope, an SMS the gateway accepted. A refused or failed call gives back what it had reserved. Read more

Do I get a seal or timestamp back if the envelope is cancelled or the seal fails?

Yes. An envelope pays them with the signature at the send. If it is cancelled, expires or is declined, or they cannot be applied when the last signer finishes (also when the provider's answer is lost), they go back at once to the credit they came from, and your audit trail says so. The signature is not given back. Read more

Signing

Which signature level do I get?

A simple electronic signature (SES), with the evidence kept. AES and QES are coming soon, and are refused with SIGNATURE_LEVEL_UNAVAILABLE until then. Read more

How do I know a document was signed?

Read output.status when you need it, or give a callback URL and take the signed webhook when it happens. Read more

How do I place the signature?

Write {{ signature.A }} in the template where signer A signs, like any other field, and send that signer with no fields. The alternative is fields with page, x and y as fractions of the page from the top-left; they win when given. Read more

Can your callbacks authenticate at my system?

Yes: add a callback environment in the console (Bearer token, API key or OAuth2 client credentials) and send "env" with the paths in callbackUrl. Every callback still carries our HMAC signature. Read more

Can the mails my signers get carry my logo and colours?

Yes: Branding, in the left menu (coordinators). A logo, header, button and footer colours and a footer text; never your own HTML. The code mail stays ours, and a branded mail drops our own sign-off line but keeps the report link. Read more

Can I write the text of the mails my signers get?

Yes: Branding, then Emails. Each mail opens with our own text; edit it in Italian and in English with placeholders such as the signer's name and the link, preview it, send yourself a test and restore the default at any time. Plain text only, checked before saving. The signing pages have a few lines of your own too. Read more

A signer lost the link. What now?

Resend to that signer: POST /api/v1/sign/envelopes/{id}/recipients/{id}/resend, or the Resend button in the console. No new request and no new charge; they get the invitation again with a fresh link, and the old one stops working. Automatic reminders do the same on a timer. Read more

A signer says the link has expired. What now?

The page they see says why: the request expired, was revoked, or they were replaced. While the request is open, resend to them for a fresh link; an expired request cannot be reopened, so send a new one. Signers are told when a request expires or is revoked. Read more

Can I replace a signer?

Yes, from the console or with POST /api/v1/sign/envelopes/{id}/recipients/{id}/replace: the new person takes the fields and the place in the order, the old link stops working. On a draft it just corrects name, email and phone. For an SMS signer give the new mobile. Read more

How do I put a word in bold in the signing message?

Write it between double asterisks: **clause 4**. A line break is a new line and an empty line a new paragraph; links are clickable. In a document, bold comes from the template itself. Read more

Errors

What does an error mean?

Every failure has a stable code and a four-digit number in output.error. Branch on the code, never on the message; the table says when each one happens and whether to retry. Read more

Should I retry a failed call?

Only when the table says it is retryable, after the seconds in Retry-After. Send an Idempotency-Key, so a retry never charges twice. Read more

What happens during maintenance?

Every call is answered MAINTENANCE_MODE (503, Retry-After) and nothing is done or charged; retry later. Just before, a new bulk job is refused while the running ones finish, and answers carry X-Maintenance-Pending. Read more

Limits

What are my limits?

Requests per minute, sizes, pages, test calls per day and how long links and files last: in the console under Reference, Limits, or in GET /api/v1/usage. Read more

I got a 429. What do I do?

RATE_LIMIT_EXCEEDED: too many requests this minute, so wait the seconds in Retry-After. TEST_QUOTA_EXCEEDED is a 429 too: today's test pool is spent; and so is QUOTA_EXCEEDED, your credit. Branch on the code, not the status. Read more

What is the largest request I can send?

25 MB. A larger body is refused with PAYLOAD_TOO_LARGE (1803, HTTP 413) and nothing is received or charged. No limit is above it: a template is at most 25 MB too, and the limits of your organisation for the payload, an uploaded file or a bulk file are under Reference, Limits. Read more

How long do you keep my documents?

A generated document 12 months (a test one 7 days), what you sent as long, an uploaded file 30 days, signature evidence 10 years. A dataless call keeps nothing at all. Read more

Which time zone are the times in?

The API and webhooks: always UTC. The console, the mails, the certificate, the line under each signature and the exports: your organisation's locale, its zone and date format, which we set for you; write to us to change it. Read more