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.

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 to obtain a word count then update the service quantities to align with the word count and process a payment with your default payment method. Your order will then be assigned to a translator and status updated to in_progress.

If your order includes shipping or 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 two minutes.

Lastly, if you need to request a revision for an order we have a revision 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 API key must be provided in an HTTP Authorization header with the type set to Bearer. You can manage your API key from your account settings page. Treat your API Key as a password—keep it secret.

curl https://rushtranslate.com/api/v1/... \
    -H "Authorization: Bearer secret_key" \
    -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
  • PUT - 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 key was either not provided or not valid
403 Forbidden API key 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

When validation fails the API will return a 422 status code and an errors object containing an array with the field name as the key and the error message as the value. 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, typically to 20 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": 21,
        "last_page": 3,
        "path": "https://rushtranslate.com/api/v1/orders",
        "per_page": 20,
        "to": 40,
        "total": 44
    }
}

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:

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

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

  • in_progress - service quantities updated and your default payment method charged
  • client_review - order requires your approval prior to finalizing
  • completed - all files have been finalized and you may retrieve the completed files
  • cancelled - the order has been cancelled and refund issued if appropriate

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, 30 minutes, 1 hour, 4 hours and 8 hours

Sandbox

We offer a sandbox environment to test your code. Create your account and generate your API key using the web interface. Orders and revisions are automatically transitioned to the next status every two minutes.

  • For orders that include shipping or 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 appropriate endpoint. Once approved it will continue transitioning automatically again.
  • For orders without shipping or notarization, the status flow is: received, in_progress then completed.
  • For revisions the status flow is: requested, in_progress then completed.

The sandbox is setup to mimic the standard life cycle of an order in our system. This will allow you to fully test your code. Features include:

  • When an order is transitioned out of received status the service quantities will be updated, the order total calculated and an initial transaction created to pay for the order. For certified translation, we’ll randomly assign a quantity of between 1-15 pages and standard translation a quantity of between 200-3,750 words.
  • When an order is transitioned out of in_progress we’ll associate a single PDF file with the order with a type of translation.
  • When an order is transitioned out of approved and it includes shipping we’ll associate a shipment with it based on the address and shipping service you selected when placing the order.

Languages

Language Object

Field Type Description
code String ISO 639-2 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.

Request

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

Response - 200

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

Response Fields

Field Type Description
data Array List of Language objects

Files

File Object

Field Type Description
id String Unique 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)

Get File

Get detailed information about a specific file.

Request

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

Response - 200

{
    "data": {
        "id": "ac533e00-528c-11e9-8f61-099c33e5fc74",
        "name": "School Documents.jpg",
        "type": "source",
        "size": 39099,
        "download_url": "https://rushtranslate.com/api/v1/...",
        "created_at": "2019-02-17T15:51:11Z"
    }
}

Response Fields

Field Type Description
data Object File object

Create File

Creates a new file. Requires form data 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.

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 Fields

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

Response - 201

{
    "data": {
        "id": "2662c0b0-923b-46ad-9a80-31a89e48e54c",
        "location": "https://rushtranslate.com/api/v1/files/2662c0b0..."
    }
}

Response Fields

Field Type Description
id String Unique identifier
location String Location of the File resource

Download 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 two minutes.

Request

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

Response - 200

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

Response Fields

Field Type Description
url String Temporary download URL

Orders

Order Object

Field Type Description
order_number String Order number
reference String Client-supplied reference
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-2 source language code
target_language String ISO 639-2 target language code
price Number Total order price 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
address Object Address object
files Array List of File objects
transactions Array List of Transaction objects
comments Array List of Comment objects
revisions Array List of Revision objects
shipments Array List of Shipment 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)

Address Object

Field Type Description
recipient String Name of the person. Both name and company can be included
street_1 String First line of the address
street_2 String Second line of the address
city String City the address is located in
state String State or providence the address is located in
zip String Zip or postal code the address is located in
country String ISO 3166 country code for the country the address is located in

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, wire or check
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)

Shipment Object

Field Type Description
carrier String Carrier name - USPS, UPS or FedEx
service String Shipping service
tracking String Tracking number from carrier
created_at String Time and date when the transaction was created (UTC)

List Orders

Get a paginated list of your orders sorted in descending order by received_at date.

Request

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

Response - 200

{
    "data": [
        {
            "order_number": "55112-7859361",
            "reference": "HN-2632",
            "origin": "api",
            "status": "completed",
            "source_language": "es",
            "target_language": "en",
            "price": 11270,
            "received_at": "2019-02-17T15:52:13Z",
            "review_at": "2019-02-17T09:15:22Z",
            "approved_at": "2019-02-17T11:43:35Z",
            "completed_at": "2019-02-17T14:04:50Z",
            "cancelled_at": null
        },
        ...
    ],
    "links": {...},
    "meta": {...}
}

Response Fields

Field Type Description
data Array List of Order objects without related resources
links Object Pagination links
meta Object Pagination meta details

Get Order

Get detailed information about a specific order.

Request

GET https://rushtranslate.com/api/v1/orders/{order_number}

Response - 200

{
    "data": {
        "order_number": "55112-7859361",
        "reference": "HN-2632",
        "origin": "api",
        "status": "completed",
        "source_language": "es",
        "target_language": "en",
        "price": 11270,
        "received_at": "2019-02-17T15:52:13Z",
        "review_at": "2019-02-17T09:15:22Z",
        "approved_at": "2019-02-17T11:43:35Z",
        "completed_at": "2019-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
            },
            {
                "name": "USPS Priority Mail",
                "quantity": 1,
                "price": 1295,
                "discount": 0,
                "total": 1295
            }
        ],
        "address": {
            "recipient": "Alexander M. Montanez",
            "street_1": "3140 Hannah Street",
            "street_2": null,
            "city": "Charlotte",
            "state": "NC",
            "zip": "28273",
            "country": "United States"
        },
        "files": [
            {
                "id": "ac533e00-528c-11e9-8f61-099c33e5fc74",
                "name": "School Documents.jpg",
                "type": "source",
                "size": 39099,
                "download_url": "https://rushtranslate.com/api/v1/...",
                "created_at": "2019-02-17T15:51:11Z"
            },
            {
                "id": "98b83043-1a64-4aa6-9591-0ac6ab8832db",
                "name": "School-Documents-55112-7859361.pdf",
                "type": "translation",
                "size": 20748,
                "download_url": "https://rushtranslate.com/api/v1/...",
                "created_at": "2019-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": "2019-02-17T16:01:26Z"
            }
        ],
        "comments": [
            {
                "author": "Alexander M. Montanez",
                "body": "<p>Please spell last name Montanez.</p>",
                "created_at": "2019-02-17T15:52:13Z"
            }
        ],
        "revisions": [
            {
                "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
                "status": "completed",
                "body": "<p>School name is Canterbury School.</p>",
                "requested_at": "2019-02-17T12:22:57Z",
                "completed_at": "2019-02-17T13:04:13Z",
                "files": []
            }
        ],
        "shipments": [
            {
                "carrier": "USPS",
                "service": "Priority Mail",
                "tracking": "9205500000000000000000",
                "created_at": "2019-02-17T14:04:50Z"
            }
        ]
    }
}

Response Fields

Field Type Description
data Object Order object

Create Order

Creates a new order. Files must be created prior as their IDs will be included in the files array of this request.

Request

POST https://rushtranslate.com/api/v1/orders
{
    "reference": "HN-2632",
    "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,
        "shipping": true,
        "shipping_service": "standard",
        "shipping_signature": false
    },
    "address": {
        "recipient": "Alexander M. Montanez",
        "street_1": "3140 Hannah Street",
        "street_2": null,
        "city": "Charlotte",
        "state": "NC",
        "zip": "28273",
        "country": "United States"
    },
    "files": [
        "ac533e00-528c-11e9-8f61-099c33e5fc74"
    ]
}

Request Fields

Field Type Required Description
reference String N Reference number for your use
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
source_language String Y ISO 639-2 language code
target_language String Y ISO 639-2 language code
certification Boolean N If you would like certified translation service otherwise standard translation provided. - Default is false
expedited Boolean N If you would like expedited turnaround service. - Default is false
notarization Boolean N If you would like the certification notarized - only available with certified translation. - Default is false
currency_conversion Boolean N If you would like currency conversion - only available with certified translation. - Default is false
shipping Boolean N If you would like a hard copy shipped - only available with certified translation. - Default is false
shipping_service String S Level of shipping service - standard (USPS Priority Mail) or express (USPS Express Mail). Required if shipping.service is true
shipping_signature Boolean N If an adult signature should be required for delivery. - Default is false
address Object S Address to ship finalized order to. Required if shipping.service is true
recipient String S Name of the person - both name and company can be included. Required if shipping.service is true
street_1 String S First line of the address. Required if shipping.service is true
street_2 String N Second line of the address
city String S City the address is located in. Required if shipping.service is true
state String S State or providence the address is located in. Required if shipping.service is true
zip String S Zip or postal code the address is located in. Required if shipping.service is true
country String S ISO 3166 country code for the country the address is located in. Required if shipping.service is true
files Array Y List of file IDs - type must be either source or reference

Response - 201

{
    "data": {
        "order_number": "55112-7859361",
        "location": "https://rushtranslate.com/api/v1/orders/55112-7859361"
    }
}

Response Fields

Field Type Description
order_number String Order number
location String Location of Order resource

Cancel 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

PUT https://rushtranslate.com/api/v1/orders/{order_number}/cancel

Response - 204

No Content

Approve Order

Approve an order that has a status of client_review.

Request

PUT https://rushtranslate.com/api/v1/orders/{order_number}/approve

Response - 204

No Content

Revisions

Revision Object

Field Type Description
id String Unique 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.

Request

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

Response - 200

{
    "data": [
        {
            "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
            "status": "completed",
            "body": "<p>Please spell last name as Silvia.</p>",
            "requested_at": "2019-03-22T19:56:01Z",
            "completed_at": "2019-03-22T23:13:27Z",
            "files": []
        },
        {
            "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2019-02-17T12:22:57Z",
            "completed_at": "2019-02-17T13:04:13Z",
            "files": [
                {
                    "id": "8638ef10-4e60-11e9-b056-d9b67d3e969f",
                    "name": "ID Document.jpg",
                    "type": "reference",
                    "size": 80296,
                    "download_url": "https://rushtranslate.com/api/v1/...",
                    "created_at": "2019-02-17T12:21:04Z"
                }
            ]
        }
    ],
    "links": {
        "first": "https://rushtranslate.com/api/v1/revisions?page=1",
        "last": "https://rushtranslate.com/api/v1/revisions?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://rushtranslate.com/api/v1/revisions",
        "per_page": 20,
        "to": 2,
        "total": 2
    }
}

Response Fields

Field Type Description
data Array List of Revision objects
links Object Pagination links
meta Object Pagination meta details

Get Revision

Get detailed information about a specific revision.

Request

GET https://rushtranslate.com/api/v1/revisions/{revision_id}

Response - 200

{
    "data": {
        "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
        "status": "completed",
        "body": "<p>School name is Canterbury School.</p>",
        "requested_at": "2019-02-17T12:22:57Z",
        "completed_at": "2019-02-17T13:04:13Z",
        "files": [
            {
                "id": "8638ef10-4e60-11e9-b056-d9b67d3e969f",
                "name": "ID Document.jpg",
                "type": "reference",
                "size": 80296,
                "download_url": "https://rushtranslate.com/api/v1/...",
                "created_at": "2019-02-17T12:21:04Z"
            }
        ]
    }
}

Response Fields

Field Type Description
data Object Revision object

Create Revision

Creates 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.

Request

POST https://rushtranslate.com/api/v1/revisions
{
    "order_number": "55112-7859361",
    "body": "<p>School name is Canterbury School.</p>",
    "files": [
        "8638ef10-4e60-11e9-b056-d9b67d3e969f"
    ]
}

Request Fields

Field Type Required Description
order_number String Y Order number in need of revision
body String Y Revision body - basic HTML allowed
files Array Y List of file IDs

Response - 201

{
    "data": {
        "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
        "location": "https://rushtranslate.com/api/v1/revisions/8c6f..."
    }
}

Response Fields

Field Type Description
id String Unique identifier
location String Location of the Revision resource

Delete 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/revisions/{revision_id}

Response - 204

No Content