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 preferences page once API access has been enabled for your account. 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 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": "2023-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

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

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

Response - 200

{
    "data": [
        {
            "id": 2304778,
            "name": "School Documents.jpg",
            "type": "source",
            "size": 39099,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2023-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": "2023-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

Response - 201

{
    "id": 2304778,
    "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": 2304778,
    "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

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

Service Object

Transaction Object

Card Details Object

PayPal Details Object

Comment Object

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

Response - 200

{
    "data": [
        {
            "id": 3290112,
            "order_number": "55112-7859361",
            "reference": "HN-2632",
            "field1": "John Anderson",
            "field2": "Feb 1, 2023",
            "origin": "api",
            "status": "completed",
            "source_language": "es",
            "target_language": "en",
            "total": 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

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, 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,
    },
    "page_count": 2,
    "files": [
        2304778
    ]
}

Request Parameters

Response - 201

{
    "id": 3290112,
    "order_number": "55112-7859361",
    "reference": "HN-2632",
    "field1": "John Anderson",
    "field2": "Feb 1, 2023",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "total": 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
        }
    ],
    "files": [
        {
            "id": 2304778,
            "name": "School Documents.jpg",
            "type": "source",
            "size": 39099,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2023-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": "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": 61233,
            "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": []
        }
    ]
}

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",
    "reference": "HN-2632",
    "field1": "John Anderson",
    "field2": "Feb 1, 2023",
    "origin": "api",
    "status": "completed",
    "source_language": "es",
    "target_language": "en",
    "total": 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
        }
    ],
    "files": [
        {
            "id": 2304778,
            "name": "School Documents.jpg",
            "type": "source",
            "size": 39099,
            "download_url": "https://rushtranslate.com/api/v1/...",
            "created_at": "2023-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": "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": 61233,
            "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": []
        }
    ],
}

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

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": "2023-03-22T19:56:01Z",
            "completed_at": "2023-03-22T23:13:27Z",
            "files": []
        },
        {
            "id": 61234,
            "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": 23904338,
                    "name": "ID Document.jpg",
                    "type": "reference",
                    "size": 80296,
                    "download_url": "https://rushtranslate.com/api/v1/...",
                    "created_at": "2023-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

Response - 201

{
    "id": 61233,
    "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": 23904338,
            "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/orders/:order_id/revisions/:revision_id

Response - 200

{
    "id": 61233,
    "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": 23904338,
            "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/orders/:order_id/revisions/:revision_id

Response - 204

No Content