API Documentation

RushTranslate provides a REST API for human translation services allowing you to place and manage your orders programmatically. Our API is HTTPS only and utilizes standard HTTP capabilities for passing parameters and authentication. The API will respond with standard HTTP response codes and return JSON.

Please contact us to request API access. This service is available at no additional charge for high volume customers. Utilization of our API requires the authorization of an invoice account, which enables us to accurately charge you for your usage.

Workflow

When creating an order you'll first create the files by submitting individual POST requests to the files endpoint. The API will return the ID of the newly created file resource. When submitting a POST request to the orders endpoint you'll include an array of file IDs you'd like to associate with the order.

Once the order is created our staff will review the files and any notes you've provided, then assign to a translator and the status will be updated to in_progress.

If your order includes notarization it will require your approval prior to being finalized. We've supplied an approval endpoint for that.

By utilizing the webhook functionality you can be notified when your order status changes so you can take the appropriate action rather than having to poll the API for changes.

Files are encrypted and stored with no public policy on Amazon S3. To access your files you'll use the file download endpoint, which will create a temporary signed URL to allow the file to be downloaded. The URL expires after five minutes.

Lastly, if you need to request a revision for an order we have an endpoint for that as well. If you need to include reference files with your revision request you'll follow the same process as when including files when placing an order via the API.

Authentication

This API uses shared secret authentication. Your personal access token must be provided in an HTTP Authorization header with the type set to Bearer. You can manage your personal access tokens from your account settings page. Personal Access Tokens give full read/write access to your account, so treat your tokens like a password—keep them secret.

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

URLs

We offer two environments; a sandbox environment for testing and a production environment for your live application. All endpoints will 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 passed as JSON with the Content-Type: application/json header. The only exception is when making POST requests to the files endpoint, which requires form data with the Content-Type: multipart/form-data header.

Certain fields including order notes, comment body, and revision body allow basic HTML tags including b, br, em, li, ol, p, s, u and ul. Tags not included in that list will be removed as will arguments within the tags.

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 will be returned expressing successful responses, client error responses, and server error responses.

Code Name Description
200 OK Request was successful and the response contains data
201 Created Resource was created
204 No Content Request was successful and response is empty
400 Bad Request Request could not be understood
401 Unauthorized API token was either not provided or not valid
403 Forbidden API token was valid, but you are denied access
404 Not Found Resource was not found
413 Entity Too Large Request is larger than the server is willing to process
422 Unprocessable Entity Validation failed. The response will contain details
429 Too Many Requests Throttle limit has been reached
500 Internal Server Error The server encountered an error and cannot fulfill the request
503 Service Unavailable The server cannot process the request at the moment

Error Messages

Status codes besides 204 will return a response object with further details via the message key. When validation fails, the API will return a 422 and include an errors object with field names as keys and arrays of error messages as the values. 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 requests per minute. When the throttle limit has been reached a 429 status code will be returned. All responses will include headers with your rate details.

Name Description
X-RateLimit-Limit Number of requests allowed per minute
X-RateLimit-Remaining Number of requests remaining in the current minute
Retry-After Number of seconds to wait until rate limit will reset if the rate limit was reached

Pagination

Requests that return multiple results are paginated with a default of 60 items. You can override the `per_page` value with a max of 500 items. The response will include 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 a callback URL is specified when placing an order via our API, we will make an HTTP POST request to that URL to notify of specific status changes. This request will include JSON in the body as follows:

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

Below are the various statuses that will trigger a notification and the corresponding descriptions for each.

  • in_progress - order has been assigned to a translator
  • client_review - order requires your approval prior to finalizing
  • completed - all files have been finalized and you may retrieve the completed files
  • cancelled - order has been cancelled and any translation work stopped

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

  • 200 - request was successful and we will not retry
  • 406 - request not accepted and we will not retry
  • For any other code, we will attempt to retry the POST request with the following delays between each attempt: 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

Language Object

Field Type Description
code String ISO 639 language code
name String Language name
active Boolean Whether or not this language is currently active

List Languages

Get the list of languages we support. The language codes included in the response will be 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

File Object

Field Type Description
id Number File identifier
name String Name
type String Type of file - source, reference, translation or revision
size Number File size in bytes
download_url String Location for file download
created_at String Time and date when the file was created (UTC)

List Files

Get a paginated list of files. Returns a paginated array of file objects.

Request

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

Request Parameters

Field Type Required Description
certified_from String N Filter by certified date, returning only those that were certified on or after the specified date
certified_to String N Filter by certified date, returning only those that were certified on or before the specified date
created_from String N Filter by created date, returning only those that were created on or after the specified date
created_to String N Filter by created date, returning only those that were created on or before the specified date
extension String N Filter by file extension; docx, pdf, xlsx, etc...
is_archived Boolean N Filter by archived status. Default is false
notarized_from String N Filter by notarized date, returning only those that were notarized on or after the specified date
notarized_to String N Filter by notarized date, returning only those that were notarized on or before the specified date
order Number N Filter by order ID
quote Number N Filter by quote ID
search String N Search by filename
sort String N Comma separated list of sort options; certified_at, created_at, extension, filename, notarized_at, size, type, and updated_at. Prepend `-` for descending order.
type String N Comma separated list of file type options; source, reference, translation, or revision.

Response - 200

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

Retrieve a File

Get 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": "2024-02-17T15:51:11Z"
}

Create a File

Create a new file. Requires a form data request with the Content-Type: multipart/form-data header. File uploads are limited to 100Mb in size. Each file may 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

Field Type Required Description
file Object Y File to be uploaded
type String Y Type of file - source or reference

Response - 201

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

Retrieve a File

Get 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": "2024-02-17T15:51:11Z"
}

Download a File

Retrieve a temporary download URL for the file. Files are encrypted and stored in an Amazon S3 bucket. When you want to download a file, this request will generate a temporary signed URL allowing access to download the file securely. 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

Field Type Description
url String Temporary download URL

Delete a File

It's only possible to delete a file that has not been associated with a quote or order. If you need to delete other files, please contact our support team.

Request

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

Response - 204

No Content

Orders

Order Object

Field Type Description
id Number Order identifier
order_number String Order number
order_url String Order URL for web app
reference String Customer-supplied internal reference (number, ID, etc.)
field1 String Client-supplied data for use in custom coversheets for white label services
field2 String Client-supplied data for use in custom coversheets for white label services
origin String Origin of the order - api or website
status String Current order status - received, in_progress, in_review, client_review, approved, finalizing, in_revision, completed, on_hold, or cancelled
source_language String ISO 639 source language code
target_language String ISO 639 target language code
total Number Order total in cents (USD)
received_at String Time and date when the order was placed (UTC)
review_at String Time and date when the order was available for review by the client (UTC)
approved_at String Time and date when the order was approved by the client (UTC)
completed_at String Time and date when the order was completed (UTC)
cancelled_at String Time and date when the order was cancelled (UTC)
services Array List of service objects
files Array List of file objects
transactions Array List of transaction objects
comments Array List of comment objects
revisions Array List of revision objects

Service Object

Field Type Description
name String Name
quantity Number Quantity ordered
price Number Price each in cents (USD)
discount Number Discount each in cents (USD)
total Number Total service price in cents (USD)

Transaction Object

Field Type Description
type String Type of transaction - charge or refund
amount Number Transaction amount in cents (USD)
description String Description of the transaction
payment_type String Type of payment - card, paypal, or invoice
card_details Object Card details object
paypal_details Object PayPal details object
created_at String Time and date when the transaction was created (UTC)

Card Details Object

Field Type Description
card_type String Type of card - Visa, MasterCard, Discover or American Express
masked_number String Masked card number
expiration_date String Expiration date of card

PayPal Details Object

Field Type Description
paypal_email String Email address of the paypal account

Comment Object

Field Type Description
author String Name of the comment author
body String Comment body - basic HTML allowed
created_at String Time and date when the comment was created (UTC)

List Orders

Get a paginated list of your orders. Returns a paginated array of order objects.

Request

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

Request Parameters

Field Type Required Description
completed_from String N Filter by completed date, returning only those that were completed on or after the specified date
completed_to String N Filter by completed date, returning only those that were completed on or before the specified date
created_from String N Filter by created date, returning only those that were created on or after the specified date
created_to String N Filter by created date, returning only those that were created on or before the specified date
search String N Search by filename or customer reference
sort String N Comma separated list of sort options; completed_at, created_at, status, and updated_at. Prepend `-` for descending order.
source_language String N Filter by source language ISO 639 language code
target_language String N Filter by target language ISO 639 language code

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, 2024",
            "origin": "api",
            "status": "completed",
            "source_language": "es",
            "target_language": "en",
            "total": 11270,
            "received_at": "2024-02-17T15:52:13Z",
            "review_at": "2024-02-17T09:15:22Z",
            "approved_at": "2024-02-17T11:43:35Z",
            "completed_at": "2024-02-17T14:04:50Z",
            "cancelled_at": null
        },
        ...
    ],
    "links": {...},
    "meta": {...}
}

Create an Order

Create a new order. Files must be created prior 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, 2024",
    "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

Field Type Required Description
reference String N Your internal reference (number, ID, etc.)
field1 String N Data for use in custom coversheets for white label services
field2 String N Data for use in custom coversheets for white label services
callback_url String N Callback URL for webhooks
notes String N Notes for staff or translators - basic HTML allowed
services Object Y Specify the services you'd like to order
services.source_language String Y ISO 639 language code
services.target_language String Y ISO 639 language code
services.certification Boolean N If you would like certified translation service otherwise standard translation provided. - Default is false
services.expedited Boolean N If you would like expedited turnaround service. - Default is false
services.notarization Boolean N If you would like the certification notarized - only available with certified translation. - Default is false
services.currency_conversion Boolean N If you would like currency conversion - only available with certified translation. - Default is false
page_count Number Y* Number of pages in the order files (250 words per page) - required if services.certification is true
word_count Number Y* Number of words in the order files - required if services.certification is true
files Array Y List of file IDs - type must be either source or reference

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, 2024",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "total": 11270,
    "received_at": "2024-02-17T15:52:13Z",
    "review_at": "2024-02-17T09:15:22Z",
    "approved_at": "2024-02-17T11:43:35Z",
    "completed_at": "2024-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": "2024-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": "2024-02-17T13:04:13Z"
        }
    ],
    "transactions": [
        {
            "type": "charge",
            "amount": 11270,
            "description": "Order Payment",
            "payment_type": "credit_card",
            "card_details": {
                "card_type": "Visa",
                "masked_number": "411111******1111",
                "expiration_date": "10/2020"
            },
            "paypal_details": null,
            "created_at": "2024-02-17T16:01:26Z"
        }
    ],
    "comments": [
        {
            "author": "Alexander M. Montanez",
            "body": "<p>Please spell last name Montanez.</p>",
            "created_at": "2024-02-17T15:52:13Z"
        }
    ],
    "revisions": [
        {
            "id": 61233,
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2024-02-17T12:22:57Z",
            "completed_at": "2024-02-17T13:04:13Z",
            "files": []
        }
    ]
}

Retrieve an Order

Get 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, 2024",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "total": 11270,
    "received_at": "2024-02-17T15:52:13Z",
    "review_at": "2024-02-17T09:15:22Z",
    "approved_at": "2024-02-17T11:43:35Z",
    "completed_at": "2024-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": "2024-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": "2024-02-17T13:04:13Z"
        }
    ],
    "transactions": [
        {
            "type": "charge",
            "amount": 11270,
            "description": "Order Payment",
            "payment_type": "credit_card",
            "card_details": {
                "card_type": "Visa",
                "masked_number": "411111******1111",
                "expiration_date": "10/2020"
            },
            "paypal_details": null,
            "created_at": "2024-02-17T16:01:26Z"
        }
    ],
    "comments": [
        {
            "author": "Alexander M. Montanez",
            "body": "<p>Please spell last name Montanez.</p>",
            "created_at": "2024-02-17T15:52:13Z"
        }
    ],
    "revisions": [
        {
            "id": 61233,
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2024-02-17T12:22:57Z",
            "completed_at": "2024-02-17T13:04:13Z",
            "files": []
        }
    ],
}

Cancel an Order

Cancel an existing order. Only orders that have a status of received are eligible to cancel 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 that has a status of client_review.

Request

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

Response - 204

No Content

Revisions

Revision Object

Field Type Description
id Number Revision identifier
status String Current revision status - requested, in_progress, in_review, completed or on_hold
body String Revision body HTML
requested_at Number Time and date when the revision was requested (UTC)
completed_at String Time and date when the revision was completed (UTC)
files Array List of File objects

List Revisions

Get 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": "2024-03-22T19:56:01Z",
            "completed_at": "2024-03-22T23:13:27Z",
            "files": []
        },
        {
            "id": 61234,
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2024-02-17T12:22:57Z",
            "completed_at": "2024-02-17T13:04:13Z",
            "files": [
                {
                    "id": 23904338,
                    "name": "ID Document.jpg",
                    "type": "reference",
                    "size": 80296,
                    "download_url": "https://rushtranslate.com/api/v1/...",
                    "created_at": "2024-02-17T12:21:04Z"
                }
            ]
        }
    ],
    "links": {...},
    "meta": {...}
}

Create a Revision

Create a new revision for an order. Files (optional) must be created prior as their IDs will be included in the files array of this request. Only a file type of reference will be 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

Field Type Required Description
body String Y Revision body - basic HTML allowed
files Array Y List of file IDs

Response - 201

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

Retrieve a Revision

Get detailed information about a specific revision. 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": "2024-02-17T12:22:57Z",
    "completed_at": "2024-02-17T13:04:13Z",
    "files": [
        {
            "id": 23904338,
            "name": "ID Document.jpg",
            "type": "reference",
            "size": 80296,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2024-02-17T12:21:04Z"
        }
    ]
}

Delete a Revision

Delete an existing revision. Only revisions that have a status of requested are eligible to delete 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