> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fortiseval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Request a translation
> Order document translations through the API and get notified when they're delivered
export const WebhookDeliveryDiagram = () => ;
export const TranslationLifecycleDiagram = () => ;
This guide shows how to send foreign-language documents for translation, approve
the price, and download the translated files. Webhooks tell your system when
each stage finishes.
## Before you begin
You need:
* An **Internal app** API key (`sk-...`) with the `files:write`,
`quotes:write`, `quotes:approve`, `orders:read`, `documents:read`, and
`webhooks:manage` scopes. See [Authentication](/authentication).
* **Net-terms invoicing** on your account to approve quotes through the API.
Contact [support](mailto:support@fortiseval.com) to turn it on.
* A webhook endpoint subscribed to `quote.*`, `order.*`, and `file.*`. See
[Webhooks](/guides/webhooks) to set one up.
Need an evaluation of foreign-language credentials? You don't need a separate
translation order. Create an [evaluation quote](/guides/credential-evaluations)
with `translation_preference: "translation_service"` and we translate the
documents as part of the evaluation.
Upload each file you want translated:
```bash theme={null}
curl https://api.fortiseval.com/v1/files \
-H "Authorization: Bearer sk-your-secret-key" \
-F "file=@/path/to/acta-de-nacimiento.pdf"
```
If the documents live on your own storage, ingest them by URL instead. We
download them in the background and send `file.ready` (or `file.failed`) for
each one:
```bash theme={null}
curl https://api.fortiseval.com/v1/files \
-H "Authorization: Bearer sk-your-secret-key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/documents/acta-de-nacimiento.pdf" }'
```
Wait until every file is `ready` before you create the quote. You can also skip
this step and pass the URLs in `document_urls`.
Set `quote_type` to `translation` and name the language of the source documents:
```bash theme={null}
curl https://api.fortiseval.com/v1/quotes \
-H "Authorization: Bearer sk-your-secret-key" \
-H "Content-Type: application/json" \
-d '{
"quote_type": "translation",
"source_language": "Spanish",
"target_language": "English",
"turnaround": "standard",
"document_ids": ["upload_Hc72pN...", "upload_Vb19qT..."],
"candidate": { "first_name": "Emma", "last_name": "Caballero" },
"reference": "CASE-2291",
"notes": "Birth certificate and marriage certificate for an I-130 filing."
}'
```
The quote is created in status `requested`:
```json theme={null}
{
"message": "Quote request created successfully.",
"data": {
"id": "quot_Lr5eGh...",
"status": "requested",
"quote_type": "translation",
"source_language": "spanish",
"target_language": "english",
"requested_turnaround": "standard",
"total_cents": 0,
"items": [],
"documents": [
{ "id": "doc_Pw3kZc...", "file_name": "acta-de-nacimiento.pdf", "document_role": "source" },
{ "id": "doc_Tn8yUf...", "file_name": "acta-de-matrimonio.pdf", "document_role": "source" }
]
}
}
```
Translation fields:
| Field | Required | Description |
| ----------------------------------------- | ----------------- | ---------------------------------------------------------------- |
| `quote_type` | Yes | `translation` |
| `source_language` | Yes | The language of the documents, such as `Spanish` or `Portuguese` |
| `target_language` | No | The language to translate into. Defaults to English |
| `document_ids` / `document_urls` | Yes, at least one | Up to 50 documents in total |
| `turnaround` | No | `standard`, `expedited`, `next_day`, or `same_day` (rush) |
| `candidate` | No | The person named in the documents |
| `reference`, `notes`, `cc_emails`, `team` | No | Same as for [every quote](/guides/quotes#creating-quotes) |
You can give a language as its English name (`Spanish`), or as an ISO 639-1
(`es`) or ISO 639-2 (`spa`) code. The quote returns it in a normalized form,
such as `spanish`. If we don't recognize a value, we keep it as you sent it and
our team confirms it when pricing the quote.
If your documents are in more than one language, create one quote per source
language.
Our team reviews each document and prices the quote. When it's priced, the quote moves to `awaiting_payment` and you receive `quote.ready`.
The `documents` on the quote carry what we found, including `page_count`,
`word_count`, and the detected `source_language`:
```json theme={null}
{
"type": "quote.ready",
"data": {
"object": {
"id": "quot_Lr5eGh...",
"status": "awaiting_payment",
"quote_type": "translation",
"total_cents": 9000,
"total": "90.00",
"items": [
{
"service_name": "Translation",
"quantity": 2,
"price": 4500,
"subtotal": 9000,
"currency": "usd"
}
]
}
}
}
```
```bash theme={null}
curl -X POST https://api.fortiseval.com/v1/quotes/quot_Lr5eGh.../approve \
-H "Authorization: Bearer sk-your-secret-key"
```
Approval creates the order (`ord_...`) and bills it to your open invoice. You
receive `quote.approved` and `order.created`.
You receive `order.in_progress` when a translator starts and `order.completed`
when the translations are delivered. Fetch the order and pick the documents
whose `document_role` is `translation`:
```bash theme={null}
curl https://api.fortiseval.com/v1/orders/ord_Qm4tHs... \
-H "Authorization: Bearer sk-your-secret-key"
```
```json theme={null}
{
"id": "ord_Qm4tHs...",
"status": "completed",
"documents": [
{ "id": "doc_Pw3kZc...", "file_name": "acta-de-nacimiento.pdf", "document_role": "source" },
{ "id": "doc_Xe6aRj...", "file_name": "acta-de-nacimiento_translated.pdf", "document_role": "translation" }
]
}
```
Then request a download URL for each translation. The URL is valid for one hour:
```bash theme={null}
curl https://api.fortiseval.com/v1/documents/doc_Xe6aRj.../download \
-H "Authorization: Bearer sk-your-secret-key"
```
## Handle the events
This handler follows a translation from upload to delivery. It records progress
on your case, then downloads each translation when the order completes. It uses
`verifyFortisSignature` from the [webhooks guide](/guides/webhooks#verifying-signatures).
```javascript Node.js theme={null}
import express from "express";
const app = express();
const API = "https://api.fortiseval.com/v1";
const headers = { Authorization: `Bearer ${process.env.FORTIS_API_KEY}` };
app.post("/webhooks/fortis", express.raw({ type: "application/json" }), async (req, res) => {
const payload = req.body.toString("utf8");
if (!verifyFortisSignature(payload, req.get("X-Fortis-Signature"), process.env.FORTIS_WHSEC)) {
return res.sendStatus(400);
}
res.sendStatus(200);
const event = JSON.parse(payload);
const object = event.data.object;
switch (event.type) {
case "file.failed":
await flagUpload(object.id, object.failure_message); // your code
break;
case "quote.ready":
await requestApproval(object.id, object.total); // your code, or approve right away
break;
case "order.in_progress":
await setCaseStatus(object.id, "Translating"); // your code
break;
case "order.completed": {
const order = await fetch(`${API}/orders/${object.id}`, { headers }).then((r) => r.json());
for (const doc of order.documents.filter((d) => d.document_role === "translation")) {
const { url, file_name } = await fetch(`${API}/documents/${doc.id}/download`, { headers })
.then((r) => r.json());
await saveTranslation(order.id, file_name, url); // your code
}
break;
}
}
});
```
```php PHP theme={null}
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
Route::post('/webhooks/fortis', function (Request $request) {
$payload = $request->getContent();
if (! verifyFortisSignature($payload, $request->header('X-Fortis-Signature', ''), config('services.fortis.whsec'))) {
abort(400);
}
$event = json_decode($payload, true);
$object = $event['data']['object'];
if ($event['type'] === 'order.completed') {
dispatch(function () use ($object) {
$api = Http::withToken(config('services.fortis.key'))->baseUrl('https://api.fortiseval.com/v1');
$translations = collect($api->get("orders/{$object['id']}")->json('documents'))
->where('document_role', 'translation');
foreach ($translations as $document) {
$download = $api->get("documents/{$document['id']}/download")->json();
// Store $download['url'] before it expires
}
});
}
return response()->noContent();
});
```
Deliveries can arrive out of order or more than once. Deduplicate on the
`X-Fortis-Delivery` header, and fetch the order when you need its current
state.
## How a webhook reaches you
Every event is signed. If your endpoint is down, we retry with backoff until it
answers:
See [Webhooks](/guides/webhooks) for the signature scheme, retry schedule, and
endpoint requirements.