API Documentation

Introduction

The RushTranslate API provides a seamless way to integrate professional document translation services into your applications. Whether you're managing document translations at scale or need certified translations with notarization, our API allows you to automate the entire workflow—from submitting files to retrieving completed translations and managing revisions.

This guide will walk you through the core API functionality, including how to create orders, upload and manage files, approve notarized documents, and track the progress of your translations in real time. With webhook notifications, you can stay updated on order status changes without the need for constant polling. Authentication is handled via secure personal access tokens, ensuring that your data remains protected.

You'll also find details on request formats, authentication methods, response structures, error handling, and rate limits to help you implement the API efficiently. Our sandbox environment allows for testing before deploying in production, ensuring a smooth integration process. Let's get started!

Workflow

To create an order, start by uploading files using individual POST requests to the files endpoint. The API will return an ID for each file, which you'll include in a POST request to the orders endpoint to associate them with the order.

Once the order is created, our team will review the files and any notes provided before assigning a translator. The order status will then update to in progress. If notarization is required, you'll need to approve it before finalization via the approval endpoint.

Webhooks allow you to receive real-time notifications when your order status changes, eliminating the need for polling. Files are securely stored on Amazon S3 with no public access and can be downloaded using a temporary signed URL that expires after five minutes.

If you need to request a revision, an endpoint is available for that as well. Reference files for revisions follow the same upload process as when placing an order.

Authentication

The API uses shared secret authentication, requiring your personal access token to be included in the HTTP Authorization header with the type set to Bearer. You can manage your tokens from your account settings page once enabled on your profile by our team. Since personal access tokens provide full read/write access to your account, handle them like passwords and keep them secure.

curl https://rushtranslate.com/api/v1/... \
    -H "Authorization: Bearer <token>" \
    -H "Accept: application/json"

URLs

We provide two environments: a sandbox for testing and a production environment for live applications. All endpoints use the following base URLs:

Sandbox URL

https://sandbox.rushtranslate.com/api/v1

Production URL

https://rushtranslate.com/api/v1

Requests

When making requests, parameters should be sent as JSON with the Content-Type: application/json header. The only exception is POST requests to the files endpoint, which require form data with the Content-Type: multipart/form-data header.

Certain fields, including order notes, comment body, and revision body, support basic HTML tags: b, br, em, li, ol, p, s, u, and ul. Any other tags or attributes will be stripped.

This API implements the following HTTP verbs:

• GET - read resources
• POST - create new resources
• PATCH - modify existing resources
• DELETE - remove resources

Responses

All endpoints return JSON with the Content-Type: application/json header.

Status Codes

Standard HTTP response codes indicate the outcome of requests, including successful responses, client errors, and server errors.

Error Messages

Status codes other than 204 will return a response object with additional details in the message key. If validation fails, the API will return a 422 status and include an errors object, where field names serve as keys and error messages are provided as arrays. Nested fields use dot notation, as shown in the example.

{
    "message": "The given data was invalid.",
    "errors": {
        "services.source_language": [
            "The source language field is required."
        ],
        "services.target_language": [
            "The target language field is required."
        ]
    }
}

Rate Limiting

Requests are limited to 60 per minute. If the throttle limit is exceeded, a 429 status code will be returned. All responses include headers with your rate limit details.

Pagination

Requests returning multiple results are paginated with a default of 60 items. You can override the per_page value, up to a maximum of 500 items. The response includes links and meta objects containing pagination details.

{
    "data": [...],
    "links": {
        "first": "https://rushtranslate.com/api/v1/orders?page=1",
        "last": "https://rushtranslate.com/api/v1/orders?page=3",
        "prev": "https://rushtranslate.com/api/v1/orders?page=1",
        "next": "https://rushtranslate.com/api/v1/orders?page=3"
    },
    "meta": {
        "current_page": 2,
        "from": 61,
        "last_page": 3,
        "path": "https://rushtranslate.com/api/v1/orders",
        "per_page": 60,
        "to": 120,
    }
}

Webhooks

If you specify a callback URL when placing an order via our API, we will send an HTTP POST request to that URL to notify you of status changes. This request will include JSON in the body.

{
    "id": 3290541,
    "order_number": "12543-5465123",
    "status": "completed",
    "updated_at": "2025-03-0T22:00:26Z",
}

The following statuses will trigger a notification, along with their descriptions:

• in_progress - Order has been assigned to a translator.
• client_review - Order requires your approval before finalization.
• completed - All files have been finalized and are ready for retrieval.
• cancelled - Order has been cancelled, and any translation work has stopped.

We listen for the following status codes when making a POST request:

• 200 - Request was successful; no retries will be made.
• 406 - Request was not accepted; no retries will be made.
• For any other status code, we will retry the POST request with the following delays: 15 minutes, 1 hour, 4 hours, 8 hours, and 24 hours.

Sandbox

We offer a sandbox environment to test your code. Contact us for assistance getting your account approved, setup, and personal access token generated. The sandbox is designed to mimic the standard life cycle of an order in our system. Orders and revisions are automatically transitioned to the next status every two minutes. When an order is transitioned out of in_progress we'll associate a single PDF file with the order with a type of translation.

• For orders that include notarization, the status flow is: received, in_progress, client_review, approved, then completed. Once the order is transitioned to the status of client_review it will not transition automatically to approved. You must approve it using the order approval endpoint. Once approved it will continue transitioning automatically again.
• For orders without notarization, the status flow is: received, in_progress, then completed.
• For revisions the status flow is: requested, in_progress, then completed.

Languages

The API provides a list of supported languages, including their ISO 639 codes and availability status. These language codes are required when placing orders to specify source and target languages.

Language Object

List Languages

Retrieve the list of supported languages. The response includes language codes, which are required when placing orders via the API. Returns an array of language objects.

Request

GET https://rushtranslate.com/api/v1/languages

Response - 200

[
    {
        "code": "ar",
        "name": "Arabic",
        "active": true
    },
    {
        "code": "bg",
        "name": "Bulgarian",
        "active": true
    },
    ...
]

Files

The API allows you to upload, manage, and retrieve files associated with translation orders. Files can be categorized as source files for translation, reference materials, completed translations, or revisions. This section covers how to create, list, retrieve, download, and delete files, including details on file storage and access via temporary signed URLs.

File Object

List Files

Retrieve a paginated list of files. The response includes a paginated array of file objects.

Request

GET https://rushtranslate.com/api/v1/files

Request Parameters

Response - 200

{
    "data": [
        {
            "id": 2304778,
            "name": "School Documents.jpg",
            "type": "source",
            "size": 39099,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2025-02-17T15:51:11Z"
        },
        ...
    ],
    "links": {...},
    "meta": {...}
}

Create a File

Upload a new file using a form data request with the Content-Type: multipart/form-data header. File uploads are limited to 100MB, and each file can be attached to only one resource after creation. Returns a file object.

File types

• source - files to be translated, if possible combine multi-page documents into a single file prior to upload
• reference - reference files to assist the translator if being associated with an order resource or marked up files to be associated with a revision resource

Request

POST https://rushtranslate.com/api/v1/files

{
    "file": {},
    "type": "source"
}

Request Parameters

Response - 201

{
    "id": 2304778,
    "name": "School Documents.jpg",
    "type": "source",
    "size": 39099,
    "download_url": "https://rushtranslate.com/api/v1/...",
    "created_at": "2025-02-17T15:51:11Z"
}

Retrieve a File

Retrieve detailed information about a specific file. Returns a file object.

Request

GET https://rushtranslate.com/api/v1/files/:file_id

Response - 200

{
    "id": 2304778,
    "name": "School Documents.jpg",
    "type": "source",
    "size": 39099,
    "download_url": "https://rushtranslate.com/api/v1/...",
    "created_at": "2025-02-17T15:51:11Z"
}

Download a File

Generate a temporary download URL for a file. Files are encrypted and stored in an Amazon S3 bucket. This request returns a signed URL that provides secure access to download the file. URLs expire after five minutes.

Request

GET https://rushtranslate.com/api/v1/files/:file_id/download

Response - 200

{
    "url": "https://rushtranslate-s3.amazonaws.com/files/..."
}

Response Attributes

Delete a File

Files can only be deleted if they have not been associated with a quote or order. To delete other files, please contact our support team.

Request

DELETE https://rushtranslate.com/api/v1/files/:file_id

Response - 204

No Content

Orders

The API allows you to create, manage, and track translation orders efficiently. Orders contain details such as status, language pairs, services, associated files, transactions, and comments. This section covers how to list, retrieve, create, approve, and cancel orders, ensuring seamless integration with your workflow.

Order Object

Service Object

Transaction Object

Comment Object

List Orders

Retrieve a paginated list of your orders. The response includes a paginated array of order objects.

Request

GET https://rushtranslate.com/api/v1/orders

Request Parameters

Response - 200

{
    "data": [
        {
            "id": 3290112,
            "order_number": "55112-7859361",
            "order_url": "https://rushtranslate.com/order/55112-7859361/mC18ihWVx...",
            "reference": "HN-2632",
            "field1": "John Anderson",
            "field2": "Feb 1, 2025",
            "origin": "api",
            "status": "completed",
            "source_language": "es",
            "target_language": "en",
            "total": 11270,
            "received_at": "2025-02-17T15:52:13Z",
            "review_at": "2025-02-17T09:15:22Z",
            "approved_at": "2025-02-17T11:43:35Z",
            "completed_at": "2025-02-17T14:04:50Z",
            "cancelled_at": null
        },
        ...
    ],
    "links": {...},
    "meta": {...}
}

Create an Order

Create a new order. Files must be uploaded first, as their IDs will be included in the files array of this request. Returns an order object.

Request

POST https://rushtranslate.com/api/v1/orders

{
    "reference": "HN-2632",
    "field1": "John Anderson",
    "field2": "Feb 1, 2025",
    "callback_url": "https://domain.com/webhooks",
    "notes": "<p>Please spell the last name Montanez.</p>",
    "services": {
        "source_language": "es",
        "target_language": "en",
        "certification": true,
        "expedited": true,
        "notarization": true,
        "currency_conversion": false,
    },
    "page_count": 2,
    "files": [
        2304778
    ]
}

Request Parameters

Response - 201

{
    "id": 3290112,
    "order_number": "55112-7859361",
    "order_url": "https://rushtranslate.com/order/55112-7859361/mC18ihWVx...",
    "reference": "HN-2632",
    "field1": "John Anderson",
    "field2": "Feb 1, 2025",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "total": 11270,
    "received_at": "2025-02-17T15:52:13Z",
    "review_at": "2025-02-17T09:15:22Z",
    "approved_at": "2025-02-17T11:43:35Z",
    "completed_at": "2025-02-17T14:04:50Z",
    "cancelled_at": null,
    "services": [
        {
            "name": "Certified Translation",
            "quantity": 2,
            "price": 2495,
            "discount": 0,
            "total": 4990
        },
        {
            "name": "Expedited Turnaround",
            "quantity": 2,
            "price": 1495,
            "discount": 0,
            "total": 2990
        },
        {
            "name": "Notarization",
            "quantity": 1,
            "price": 1995,
            "discount": 0,
            "total": 1995
        }
    ],
    "files": [
        {
            "id": 2304778,
            "name": "School Documents.jpg",
            "type": "source",
            "size": 39099,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2025-02-17T15:51:11Z"
        },
        {
            "id": 2304779,
            "name": "School-Documents-55112-7859361.pdf",
            "type": "translation",
            "size": 20748,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2025-02-17T13:04:13Z"
        }
    ],
    "transactions": [
        {
            "type": "charge",
            "amount": 11270,
            "description": "Order Payment",
            "payment_type": "invoice",
            "created_at": "2025-02-17T16:01:26Z"
        }
    ],
    "comments": [
        {
            "author": "Alexander M. Montanez",
            "body": "<p>Please spell last name Montanez.</p>",
            "created_at": "2025-02-17T15:52:13Z"
        }
    ],
    "revisions": [
        {
            "id": 61233,
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2025-02-17T12:22:57Z",
            "completed_at": "2025-02-17T13:04:13Z",
            "files": []
        }
    ]
}

Retrieve an Order

Retrieve detailed information about a specific order. Returns an order object.

Request

GET https://rushtranslate.com/api/v1/orders/:order_id

Response - 200

{
    "id": 3290112,
    "order_number": "55112-7859361",
    "order_url": "https://rushtranslate.com/order/55112-7859361/mC18ihWVx...",
    "reference": "HN-2632",
    "field1": "John Anderson",
    "field2": "Feb 1, 2025",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "total": 11270,
    "received_at": "2025-02-17T15:52:13Z",
    "review_at": "2025-02-17T09:15:22Z",
    "approved_at": "2025-02-17T11:43:35Z",
    "completed_at": "2025-02-17T14:04:50Z",
    "cancelled_at": null,
    "services": [
        {
            "name": "Certified Translation",
            "quantity": 2,
            "price": 2495,
            "discount": 0,
            "total": 4990
        },
        {
            "name": "Expedited Turnaround",
            "quantity": 2,
            "price": 1495,
            "discount": 0,
            "total": 2990
        },
        {
            "name": "Notarization",
            "quantity": 1,
            "price": 1995,
            "discount": 0,
            "total": 1995
        }
    ],
    "files": [
        {
            "id": 2304778,
            "name": "School Documents.jpg",
            "type": "source",
            "size": 39099,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2025-02-17T15:51:11Z"
        },
        {
            "id": 2304779,
            "name": "School-Documents-55112-7859361.pdf",
            "type": "translation",
            "size": 20748,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2025-02-17T13:04:13Z"
        }
    ],
    "transactions": [
        {
            "type": "charge",
            "amount": 11270,
            "description": "Order Payment",
            "payment_type": "invoice",
            "created_at": "2025-02-17T16:01:26Z"
        }
    ],
    "comments": [
        {
            "author": "Alexander M. Montanez",
            "body": "<p>Please spell last name Montanez.</p>",
            "created_at": "2025-02-17T15:52:13Z"
        }
    ],
    "revisions": [
        {
            "id": 61233,
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2025-02-17T12:22:57Z",
            "completed_at": "2025-02-17T13:04:13Z",
            "files": []
        }
    ]
}

Cancel an Order

Cancel an existing order. Only orders with a status of received can be canceled via the API. For orders with other statuses, please contact support.

Request

POST https://rushtranslate.com/api/v1/orders/:order_id/cancel

Response - 204

No Content

Approve an Order

Approve an order with a status of client_review.

Request

POST https://rushtranslate.com/api/v1/orders/:order_id/approve

Response - 204

No Content

Revisions

Revisions allow you to request changes to a completed translation. This section covers how to create, retrieve, list, and delete revisions, including the ability to attach reference files. Revisions follow a status flow, ensuring that changes are properly tracked and processed.

Revision Object

List Revisions

Retrieve a paginated list of your revisions, sorted in descending order by requested_at date. Returns a paginated list of revision objects.

Request

GET https://rushtranslate.com/api/v1/orders/:order_id/revisions

Response - 200

{
    "data": [
        {
            "id": 61233,
            "status": "completed",
            "body": "<p>Please spell last name as Silvia.</p>",
            "requested_at": "2025-03-22T19:56:01Z",
            "completed_at": "2025-03-22T23:13:27Z",
            "files": []
        },
        {
            "id": 61234,
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2025-02-17T12:22:57Z",
            "completed_at": "2025-02-17T13:04:13Z",
            "files": [
                {
                "id": 23904338,
                "name": "ID Document.jpg",
                "type": "reference",
                "size": 80296,
                "download_url": "https://rushtranslate.com/api/v1/...",
                "created_at": "2025-02-17T12:21:04Z"
                }
            ]
        }
    ],
    "links": {...},
    "meta": {...}
}

Create a Revision

Create a new revision request for an order. Optional files must be uploaded first, as their IDs will be included in the files array of this request. Only files of type reference are accepted. Returns a revision object.

Request

POST https://rushtranslate.com/api/v1/orders/:order_id/revisions

{
    "body": "<p>School name is Canterbury School.</p>",
    "files": [
        23904338
    ]
}

Request Parameters

Response - 201

{
    "id": 61233,
    "status": "completed",
    "body": "<p>School name is Canterbury School.</p>",
    "requested_at": "2025-02-17T12:22:57Z",
    "completed_at": "2025-02-17T13:04:13Z",
    "files": [
        {
            "id": 23904338,
            "name": "ID Document.jpg",
            "type": "reference",
            "size": 80296,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2025-02-17T12:21:04Z"
        }
    ]
}

Retrieve a Revision

Retrieve detailed information about a specific revision request. Returns a revision object.

Request

GET https://rushtranslate.com/api/v1/orders/:order_id/revisions/:revision_id

Response - 200

{
    "id": 61233,
    "status": "completed",
    "body": "<p>School name is Canterbury School.</p>",
    "requested_at": "2025-02-17T12:22:57Z",
    "completed_at": "2025-02-17T13:04:13Z",
    "files": [
        {
            "id": 23904338,
            "name": "ID Document.jpg",
            "type": "reference",
            "size": 80296,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2025-02-17T12:21:04Z"
        }
    ]
}

Delete a Revision

Delete an existing revision request. Only revisions with a status of requested can be deleted via the API. For revisions with other statuses, please contact support.

Request

DELETE https://rushtranslate.com/api/v1/orders/:order_id/revisions/:revision_id

Response - 204

No Content