The EZDocuAI API for developers

With the EZDocuAI API (v1) you connect your own system (CRM, ERP, ordering website) to EZDocuAI. Your system uploads the document, creates the translation or layout order, finds out when it's done and downloads the result, without signing in to the dashboard. They're the same orders and the same credit balance you use on the web.

Who can create keys

It doesn't depend on the plan: it depends on the API keys permission. The owner always has it and, by default, so do Managers. Reviewer and Member have it turned off; the owner can turn it on for each person in Team.

With read-only access you can't view, create or revoke keys. Each key works with the access of the person who created it and never does more than that person can. If that person is deactivated in the team, their key shows as Suspended.

Create a key

1. Go to Settings › API keys.
2. Click Create key.
3. Give it a Name so you can recognize it, for example ERP integration.
4. Choose the Environment: Staging for testing or Production for real work.
5. Tick the Services: Translation, Layout or both. With no services, the key can only read.
6. In Access by area, tick read or write. You can only grant the access you have; Orders and Webhooks require the “View and assign all documents” permission.
7. If you like, set a Daily page limit (empty = no limit; maximum 5000).
8. Click Create key, copy it with Copy and click I have saved it. The full key is only shown that one time.

You can have up to 20 active keys. Revoke shuts a key off instantly and can't be undone. Treat it like a password.

Staging and Production: where each key points

Both are created here, on www.ezdocu.ai, from Settings › API keys. You don't need another account.

Each key only works on its own URL. Start with Staging; once it works, switch the URL and the key: the routes are the same.

Where to find the documentation

In the side menu, API documentation. It has the Quickstart, the Translate a document, Layout without translation and Human review guides, Webhooks and signature verification and the reference for every route, with examples.

• In Environments you choose Staging or Production: the base URL, the examples and the downloads (Download Postman and Download OpenAPI) change accordingly.
• Try in Swagger calls the server of the site you're on: on www that's Production, and creating an order charges credits. For the Staging key, use Postman or your own code.

The basic flow

Every request carries the Authorization: Bearer <your key> header. Every POST, PATCH, PUT and DELETE also carries Idempotency-Key: if you repeat the request with the same one, two orders are never created and you're never charged twice.

1. Upload the file with POST /uploads (it gives you an upload URL), send it to that URL and confirm it with POST /uploads/{id}/complete. If it's already at a public https:// URL, send it in file_url when you create the order.
2. Create the order with POST /orders. In mode you put translate (translate) or layout (lay out in the same language). When translating, specify target_language, for example en-US. The document's language is detected automatically.
3. Wait for the result: with the order.completed webhook (recommended) or by checking GET /orders/{id} every 15 to 30 seconds.
4. Download: once the order is completed, the detail includes one link per file, valid for 1 hour.

Which files you receive

PDF, DOCX and HTML (one HTML per page and one with all of them), in whatever combination you request, plus the certificate and the original. The document's content never comes in the JSON response: only the links and the order data. When translating, the PDF's certificate and digital signature are included by default; you can remove them in the request.

Webhooks

They're created through the API (POST /webhooks), not in Settings. EZDocuAI sends a signed POST to your https:// URL with each event:

The signing secret (whsec_…) is shown only once. Your server must respond with 2xx in under 10 seconds; otherwise, EZDocuAI keeps retrying for a little over a day and a half.

Human review

With review_required: true the order stops at in_review and waits for your team, with no time limit. The reviewer opens it in Orders, clicks Continue Order, reviews it and clicks Finish Order. Then order.completed arrives. Whoever finishes it chooses the format, the certificate and the Human Verified seal: an order without review never carries that seal. Approval is done on the web, not through the API.

Credits and limits

• Same balance as the web: 1 credit per page, charged when the order is created.
• With no balance, POST /orders responds 402 INSUFFICIENT_CREDITS and nothing is created or charged.
• If a charged order fails or you cancel it, the credits aren't refunded automatically: write to support with the order number.
• Requesting DOCX, HTML, the certificate or review doesn't cost extra.
• 100 requests per minute per key (by default). Files up to 50 MB and 2000 pages, in PDF, JPG, PNG, TIFF, WebP, HEIC, DOCX or ODT.

Common errors

Usage dashboard

In the side menu, API opens API usage: your account's requests, orders, pages, errors, webhooks and limits, by period, by key and by member. People with the API keys permission can see it.

FAQ

Do I need a special plan to use the API? No. You need the API keys permission, which the owner and Managers have.

My developer gets 401 or 403 with the Staging key. What's wrong? It's almost always the URL: the Staging key (ezk_test_) only works on https://staging.ezdocu.ai/api/v1, and the Production key (ezk_live_) only on https://www.ezdocu.ai/api/v1. If the Staging key is new, wait a minute before using it.

Do tests with the Staging key use credits? No: the orders are simulated. Only the Production key charges credits.

Can I get the translation as text in JSON? No. The API delivers files: PDF, DOCX or HTML.