Endpoints
Getting a translation done via the API involves these steps:
POST /documents uploads a text string or file.
The request body should be a multipart/form-data message,
with a document field specifying the document to upload,
either as a file or as a plain-text string.
Make sure to set the Content-Type in the payload.
When sending the content as a string,
you can optionally specify the name of the file in a name parameter.
When the upload is successful,
you'll get a 201 Created response,
along with the JSON representation of the new document.
Save the document_id from this response,
to attach to the order you create in the next step.
Example of sending plain-text with Curl:
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
--form document="Here is some text to be translated." \
--form name=myfile.txt \
https://twb.translationcenter.org/api/v1/documents
Example of uploading a file with Curl:
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
--form [email protected] \
https://twb.translationcenter.org/api/v1/documents
Example response:
{
"document_id": 12345,
"name": "testfile.txt",
"self_link": "https://twb.translationcenter.org/api/v1/documents/12345",
"download_link": "https://twb.translationcenter.org/api/v1/document/12345/file"
}
POST /orders will create a new order from the given parameters.
It will return 201 Created,
and a JSON data structure with a link to view the order on the web.
Visit this link to communicate with the translators, etc.
Example request with Curl:
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"contact_email": "[email protected]",
"title": "Test title",
"source_lang": "eng",
"target_langs": ["fra", "esl"],
"source_document_ids": [12345],
"source_wordcount": 321,
"instructions": "Sample instructions for this job.",
"deadline": "2015-01-01 00:00:00",
"urgency": "high",
"project_id": 509,
"callback_url": "https://www.example.com/my-callback-url"
}' \
https://twb.translationcenter.org/api/v1/orders
The deadline must be in the UTC time zone, in the format YYYY-MM-DD HH:MM:SS.
urgency can optionally be specified to give translators additional information about how to prioritize this job.
Allowed values are high, low, or normal.
Optionally specify a project_id if the order is part of a pre-configured project,
with existing translation teams and resources.
See GET /projects to get a list of the project IDs you can specify here.
It's possible to omit the source documents,
and instead specify instructions to be shown to the translator after accepting the job,
with information about how to access the source documents elsewhere
(such as on an external translation platform).
Use the post_assign_instructions field for this.
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"contact_email": "[email protected]",
"source_lang": "eng",
"target_langs": ["fra"],
"source_wordcount": 321,
"instructions": "Sample instructions for this job.",
"urgency": "high",
"post_assign_instructions": "Go to https://example.com/xyz-123-abc to work on this job."
}' \
https://twb.translationcenter.org/api/v1/orders
Example response:
{
"order_id": 11400,
"order_web_url": "https://twb.translationcenter.org/workspace/client-workorders/view/id/11400"
}
When the work is complete,
a POST request will be sent to the callback_url you specified when creating the order.
(It's also possible to poll for completed orders.)
{
"event": "job:completed",
"event_data": {
"order_id":11400,
"order_web_url":"https://twb.translationcenter.org/workspace/client-workorders/view/id/11400"
"job_id":17001,
"job_web_url":"https://twb.translationcenter.org/workspace/jobs/view/id/17001",
"delivered_documents": [
{
"document_id": 12345,
"download_url": "https://twb.translationcenter.org/api/v1/document/12345/file"
}
]
}
}
You can download the completed documents from the links provided.
It's also possible to poll for completed orders, instead of or in addition to receiving a push notification when the work is complete.
GET /orders?delivery_status=to_accept will return a collection of orders with delivered documents that you have not yet accepted or rejected.
See GET /orders for details.
GET /document/{id}/file downloads a document as a file.
Check the response headers for the file name and type.
Example request with Curl:
curl -JO -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/document/12345/file'
Example response:
Content-Disposition: attachment; filename="test-part-1-fr.txt"
Content-Length: 3683
Content-Transfer-Encoding: binary
Content-Type: text/plain; charset=us-ascii
{binary file data}
curl: Saved to filename 'test-part-1-fr.txt'
Once you have downloaded the completed translation, mark it as accepted so you can exclude it from your polling results, or reject it so the work can be corrected. See PATCH /orders/:id/delivered_documents/:doc_id for details.
POST /documents uploads a text string or file.
The request body should be a multipart/form-data message,
with a document field specifying the document to upload,
either as a file or as a plain-text string.
Make sure to set the Content-Type in the payload.
When sending the content as a string,
you can optionally specify the name of the file in a name parameter.
When the upload is successful,
you'll get a 201 Created response,
along with the JSON representation of the new document.
Save the document_id from this response,
to attach to the order you create in the next step.
Example of sending plain-text with Curl:
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
--form document="Here is some text to be translated." \
--form name=myfile.txt \
https://twb.translationcenter.org/api/v1/documents
Example of uploading a file with Curl:
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
--form [email protected] \
https://twb.translationcenter.org/api/v1/documents
Example response:
{
"document_id": 12345,
"name": "testfile.txt",
"self_link": "https://twb.translationcenter.org/api/v1/documents/12345",
"download_link": "https://twb.translationcenter.org/api/v1/document/12345/file"
}
GET /documents/{id} gets a information about a document.
(To download the document itself, see downloading documents, below.)
Example request with Curl:
curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/documents/12345'
Example response:
{
"document_id": 12345,
"name": "test-part-1-fr.txt",
"self_link": "https://twb.translationcenter.org/api/v1/documents/12345",
"download_link": "https://twb.translationcenter.org/api/v1/document/12345/file"
}
GET /document/{id}/file downloads a document as a file.
Check the response headers for the file name and type.
Example request with Curl:
curl -JO -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/document/12345/file'
Example response:
Content-Disposition: attachment; filename="test-part-1-fr.txt"
Content-Length: 3683
Content-Transfer-Encoding: binary
Content-Type: text/plain; charset=us-ascii
{binary file data}
curl: Saved to filename 'test-part-1-fr.txt'
Translation work is initiated with an "order" (also known as a "work order") from a "client". The order is broken out into one or more "jobs", with one job for each target language.
POST /orders will create a new order from the given parameters.
It will return 201 Created,
with the current JSON representation of the order if the creation was a success.
See the GET /orders/:id endpoint for details.
If the user does not have access to create new orders a 403 Forbidden will be returned.
Example request with Curl:
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"contact_email": "[email protected]",
"title": "Test title",
"source_lang": "eng",
"target_langs": ["fra", "esl"],
"source_document_ids": [12345],
"source_wordcount": 321,
"instructions": "Sample instructions for this job.",
"deadline": "2015-01-01 00:00:00",
"urgency": "high",
"project_id": 509,
"callback_url": "https://www.example.com/my-callback-url"
}' \
https://twb.translationcenter.org/api/v1/orders
The deadline must be in the UTC time zone, in the format YYYY-MM-DD HH:MM:SS.
urgency can optionally be specified to give translators additional information about how to prioritize this job.
Allowed values are high, low, or normal.
Optionally specify a project_id if the order is part of a pre-configured project,
with existing translation teams and resources.
See GET /projects to get a list of the project IDs you can specify here.
It's possible to omit the source documents,
and instead specify instructions to be shown to the translator after accepting the job,
with information about how to access the source documents elsewhere
(such as on an external translation platform).
Use the post_assign_instructions field for this.
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"contact_email": "[email protected]",
"source_lang": "eng",
"target_langs": ["fra"],
"source_wordcount": 321,
"instructions": "Sample instructions for this job.",
"urgency": "high",
"post_assign_instructions": "Go to https://example.com/xyz-123-abc to work on this job."
}' \
https://twb.translationcenter.org/api/v1/orders
Example response:
{
"order_id": 11400,
"order_web_url": "https://twb.translationcenter.org/workspace/client-workorders/view/id/11400"
}
GET /orders/:id will return the specified order.
If the user does not have access to see the order 403 Forbidden will be returned.
Example request with Curl:
curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/order/24881'
Example response:
{
"order_id": 24881,
"self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881",
"order_web_url": "https:\/\/twb.translationcenter.org\/workspace\/client-workorders\/view\/id\/24881",
"status": "delivered",
"project_id": 0,
"client_id": 1211,
"orderer_contact_email": "[email protected]",
"orderer_account_id": 13040,
"client_contact_account_id": 13040,
"pm_account_id": 0,
"title": "Test title",
"source_lang": "und",
"source_wordcount": 243,
"instructions": "",
"deadline": "2015-03-01 00:00:00",
"delivered_documents": [
{
"document_id": 122897,
"attachment_id": 326357,
"download_link": "https:\/\/twb.translationcenter.org\/api\/v1\/document\/122897\/file",
"name": "test.txt",
"self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881\/delivered_documents\/326357",
"language": "eng",
"delivery_status": "to_accept"
}
]
}
GET /orders will return a collection of the orders that you have access to.
To filter the orders by delivery status,
pass a delivery_status parameter with a value of to_accept
(to get just the orders with delivered documents you haven't accepted or rejected yet),
accepted, or rejected.
Example request with Curl:
curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/orders'
Example response:
{
"_links": {
"self": {
"href": "https:\/\/twb.translationcenter.org\/api\/v1\/orders"
},
"next": {
"href": "https:\/\/twb.translationcenter.org\/api\/v1\/orders?page=2"
},
"prev": {
"href": null
}
},
"data": [
{
"order_id": 25774,
"self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/25774",
"order_web_url": "https:\/\/twb.translationcenter.org\/workspace\/client-workorders\/view\/id\/25774",
"status": "draft",
"project_id": 5681,
"client_id": 1211,
"orderer_contact_email": "[email protected]",
"orderer_account_id": 13040,
"client_contact_account_id": 13040,
"pm_account_id": 0,
"title": "Translation Request from twb",
"source_lang": "eng",
"source_wordcount": 100,
"instructions": "Please translate according to ...",
"deadline": "2015-03-29 07:46:10",
"delivered_documents": [ ]
},
{
"order_id": 24881,
"self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881",
"order_web_url": "https:\/\/twb.translationcenter.org\/workspace\/client-workorders\/view\/id\/24881",
"status": "delivered",
"project_id": 0,
"client_id": 1211,
"orderer_contact_email": "[email protected]",
"orderer_account_id": 13040,
"client_contact_account_id": 13040,
"pm_account_id": 0,
"title": "Test title",
"source_lang": "und",
"source_wordcount": 234,
"instructions": "",
"deadline": "2015-03-01 00:00:00",
"delivered_documents": [
{
"document_id": 122897,
"attachment_id": 326357,
"download_link": "https:\/\/twb.translationcenter.org\/api\/v1\/document\/122897\/file",
"name": "test-6-words.txt",
"self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881\/delivered_documents\/326357",
"language": "eng",
"delivery_status": "to_accept"
}
]
}
]
To accept or reject a delivered document,
send a PATCH request to the self_link property of the delivered document.
Set the Content-Type to application/json,
and send a JSON payload with the following properties:
delivery_status - either "accepted" or "rejected".reject_reason - a string explaining why the delivered document is being rejected.
Required if delivery_status is "rejected".Example request with Curl:
curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
--request PATCH \
-d '{ "delivery_status": "accepted" }' \
https://twb.translationcenter.org/api/v1/orders/24881/delivered_documents/326357 # The delivered document's self_link
Trouble using the PATCH method?
If your client library doesn't support the PATCH method,
you can send a POST request instead,
as long as you include an X-HTTP-Method-Override header set to PATCH.
Orders can be grouped into projects, so they can use project-specific translation teams and resources. Projects are associated with a "client" (the organization requesting the translation work to be done).
GET /projects gets a list of projects for a given client.
Specify the client ID in the client parameter.
Use client=me to get projects for the main client associated with your account.
If the client parameter is invalid, a 400 Bad Request response will be returned.
If you specify the ID of a client that you don't have access to,
a 403 Forbidden response will be returned.
Example request with Curl:
curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/projects?client=me'
Example response:
[
{
"project_id": 502,
"client_id": 929,
"name": "Nigerian Elections Project",
"summary": "Translation of crisis reports for Nigerian election monitors.",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse ornare purus eros, sit amet hendrerit ante consectetur tempor. Suspendisse faucibus tempus arcu ac molestie. Vestibulum posuere eleifend quam, sed fringilla augue ullamcorper in. Nulla tincidunt nisi orci, nec gravida sapien dapibus dictum. Vestibulum gravida ut metus sit amet gravida. In feugiat nulla vel neque placerat tristique. Aenean iaculis eu ipsum non finibus. Aliquam diam turpis, viverra eget tincidunt quis, semper vitae ipsum. Nulla pellentesque ac nisl feugiat pretium."
}
]