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 five 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 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 preferences 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.

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.

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": "2023-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. Contact us for assistance getting your account approved, setup, and personal access token generated. 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

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

Create a File

Creates 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

Response - 201

{
    "id": "ac533e00-528c-11e9-8f61-099c33e5fc74",
    "name": "School Documents.jpg",
    "type": "source",
    "size": 39099,
    "download_url": "https://rushtranslate.com/api/v1/...",
    "created_at": "2023-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": "ac533e00-528c-11e9-8f61-099c33e5fc74",
    "name": "School Documents.jpg",
    "type": "source",
    "size": 39099,
    "download_url": "https://rushtranslate.com/api/v1/...",
    "created_at": "2023-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

Orders

Order Object

Compact Order Object

Service Object

Address Object

Transaction Object

Card Details Object

PayPal Details Object

Comment Object

Shipment Object

List Orders

Get a paginated list of your orders sorted in descending order by received_at date. Returns a paginated array of compact order objects.

Request

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

Response - 200

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

Create an Order

Creates 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, 2023",
    "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 Parameters

Response - 201

{
    "order_number": "55112-7859361",
    "reference": "HN-2632",
    "field1": "John Anderson",
    "field2": "Feb 1, 2023",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "price": 11270,
    "received_at": "2023-02-17T15:52:13Z",
    "review_at": "2023-02-17T09:15:22Z",
    "approved_at": "2023-02-17T11:43:35Z",
    "completed_at": "2023-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": "2023-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": "2023-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": "2023-02-17T16:01:26Z"
        }
    ],
    "comments": [
        {
            "author": "Alexander M. Montanez",
            "body": "<p>Please spell last name Montanez.</p>",
            "created_at": "2023-02-17T15:52:13Z"
        }
    ],
    "revisions": [
        {
            "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2023-02-17T12:22:57Z",
            "completed_at": "2023-02-17T13:04:13Z",
            "files": []
        }
    ],
    "shipments": [
        {
            "carrier": "USPS",
            "service": "Priority Mail",
            "tracking": "9205500000000000000000",
            "created_at": "2023-02-17T14:04:50Z"
        }
    ]
}

Retrieve an Order

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

Request

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

Response - 200

{
    "order_number": "55112-7859361",
    "reference": "HN-2632",
    "field1": "John Anderson",
    "field2": "Feb 1, 2023",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "price": 11270,
    "received_at": "2023-02-17T15:52:13Z",
    "review_at": "2023-02-17T09:15:22Z",
    "approved_at": "2023-02-17T11:43:35Z",
    "completed_at": "2023-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": "2023-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": "2023-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": "2023-02-17T16:01:26Z"
        }
    ],
    "comments": [
        {
            "author": "Alexander M. Montanez",
            "body": "<p>Please spell last name Montanez.</p>",
            "created_at": "2023-02-17T15:52:13Z"
        }
    ],
    "revisions": [
        {
            "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2023-02-17T12:22:57Z",
            "completed_at": "2023-02-17T13:04:13Z",
            "files": []
        }
    ],
    "shipments": [
        {
            "carrier": "USPS",
            "service": "Priority Mail",
            "tracking": "9205500000000000000000",
            "created_at": "2023-02-17T14:04:50Z"
        }
    ]
}

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_number/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_number/approve

Response - 204

No Content

Revisions

Revision Object

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/revisions

Response - 200

{
    "data": [
        {
            "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
            "status": "completed",
            "body": "<p>Please spell last name as Silvia.</p>",
            "requested_at": "2023-03-22T19:56:01Z",
            "completed_at": "2023-03-22T23:13:27Z",
            "files": []
        },
        {
            "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
            "status": "completed",
            "body": "<p>School name is Canterbury School.</p>",
            "requested_at": "2023-02-17T12:22:57Z",
            "completed_at": "2023-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": "2023-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
    }
}

Create a 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. Returns a revision object.

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 Parameters

Response - 201

{
    "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
    "status": "completed",
    "body": "<p>School name is Canterbury School.</p>",
    "requested_at": "2023-02-17T12:22:57Z",
    "completed_at": "2023-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": "2023-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/revisions/:revision_id

Response - 200

{
    "id": "8c6f0660-4d35-11e9-93d0-8377d5c7abb3",
    "status": "completed",
    "body": "<p>School name is Canterbury School.</p>",
    "requested_at": "2023-02-17T12:22:57Z",
    "completed_at": "2023-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": "2023-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/revisions/:revision_id

Response - 204

No Content