Request a translation

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.
Net-terms invoicing on your account to approve quotes through the API. Contact support to turn it on.
A webhook endpoint subscribed to quote.*, order.*, and file.*. See Webhooks to set one up.

Need an evaluation of foreign-language credentials? You don’t need a separate translation order. Create an evaluation quote with translation_preference: "translation_service" and we translate the documents as part of the evaluation.

Send the documents

Upload each file you want translated:

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:

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.

Create a translation quote

Set quote_type to translation and name the language of the source documents:

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:

{
  "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

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.

Review the price

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:

{
  "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"
        }
      ]
    }
  }
}

Approve the quote

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.

Collect the translations

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:

curl https://api.fortiseval.com/v1/orders/ord_Qm4tHs... \
  -H "Authorization: Bearer sk-your-secret-key"

{
  "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:

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.

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;
    }
  }
});

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 for the signature scheme, retry schedule, and endpoint requirements.

Getting Started

Guides

Before you begin

Handle the events

How a webhook reaches you

​Before you begin

​Handle the events

​How a webhook reaches you

Before you begin

Handle the events

How a webhook reaches you