RapidTranslate API

Introduction

The RapidTranslate API lets your application submit documents for certified translation, retrieve up‑to‑date status and pricing, and receive the finished files — without your team touching our checkout. It is designed for businesses that place translation orders on behalf of their own customers.

All requests are made to https://staging.rapidtranslate.org/api/v1 over HTTPS. Requests and responses are JSON, except order creation, which uploads files as multipart/form-data. All amounts are returned as integer cents in USD, and all timestamps are UTC ISO‑8601.

Authentication

Authenticate every request with your secret API key as a bearer token, and ask for a JSON response. Both headers are required:

Authorization: Bearer YOUR_API_KEY
Accept: application/json

Generate and rotate keys in your dashboard under Business Settings → API Keys. Keys are shown once at creation and stored hashed — if you lose a key, rotate it. Each key belongs to one mode (Live or Sandbox) and carries a fixed set of scopes.

Scopes

Each endpoint requires a specific ability on the key. A key missing the required scope returns 403 forbidden_scope.

Sandbox & test mode

Test mode is a property of the key, not your account. A Sandbox key runs against a fully simulated environment; a Live key places real, billable orders. You can use both at the same time.

Sandbox orders use the same validation, field mapping, and real pricing, but skip file storage, OCR, and fulfillment. On creation, a sandbox order automatically walks through its lifecycle (processing → completed), firing the same webhooks as a live order and finally delivering a static sample document.

Every response and webhook carries a livemode flag so your integration can branch without inspecting the key:

• livemode: true — real, billable order
• livemode: false — sandbox / test order

Rate limits

Requests are rate‑limited per organization. The default allowance is 120 requests per minute. Exceeding it returns 429 rate_limited; retry after a short back‑off. If your integration needs a higher limit, contact support@rapidtranslate.org.

Responses

Every successful response wraps its payload in a data key. List endpoints add a meta block with pagination.

Single resource

{
  "data": {
    "id": "9b1c...-uuid",
    "reference": "APO-10432",
    "status": "processing",
    "total": 11270,
    "currency": "USD"
  }
}

Paginated list

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 134,
    "last_page": 6
  }
}

Errors

Errors use standard HTTP status codes and return a stable, machine‑readable error_code alongside a human message. Validation errors add a field‑keyed errors object.

{
  "message": "The given data was invalid.",
  "error_code": "validation_failed",
  "errors": {
    "source_language": ["The selected source language is invalid."]
  }
}

Order statuses

An order's status follows a stable lifecycle. These five values are also the ones accepted by the status filter on List orders:

While an order is in progress, more granular labels (for example Assigned To Translator, Translating, Shipped) may also appear. When approval is required, an order may briefly report payment_failed or credit_hold if a charge could not be collected — resolve the payment method and approve again.

Field values

The fixed sets accepted when creating an order.

Translation types

Turnaround

Delivery methods

Webhooks

Instead of polling, configure a webhook endpoint to receive events as they happen. Set your URL and view your signing secret in Business Settings → Webhooks. Webhooks are a convenience — Retrieve an order is always authoritative.

Events

Envelope

Every delivery has the same envelope: an event block (including livemode) and an event‑specific data block.

{
  "event": {
    "type": "order_status",
    "id": "evt_9b1c...",
    "livemode": true,
    "sent_at": "2026-08-28T10:20:00+00:00"
  },
  "data": {
    "order": {
      "id": "9b1c2d3e-...-uuid",
      "reference": "APO-10432",
      "status": "completed"
    }
  }
}

The document_delivery event adds a documents array (each with name, download_url, version, status) and a portal link. The client_review event adds an itemized pricing block and an actions.approve object with the URL to call.

Verifying signatures

Each request is signed so you can confirm it came from RapidTranslate. We send three headers:

Compute the expected signature as an HMAC‑SHA256 of the string "{timestamp}.{raw_request_body}" using your webhook signing secret, then compare it to the header value:

// PHP
$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $rawBody,
    $webhookSecret
);
$valid = hash_equals($expected, $signatureHeader);

Failed deliveries are retried with exponential back‑off (up to 5 attempts). Respond with a 2xx status to acknowledge receipt.