WritePath Translation API (PHP, Java)

Intro

For a quick & easy start with our API, simply use the class we provide below or download it from Github (PHP, Java). It takes care of authorization, JSON encoding and decoding and it can do a few more very convenient things.

How to get your API keys? Sign up here and request the API keys in the settings section of your account.

We use JSON. Every response looks like this:
                    {
                        "response": {

                        },
                        "opStatus": "ok"
                        }
                
If something has gone wrong, the response looks like this:
                {
                    "response": {
                    "errorCode": "4001",
                    "errorMessage": "Something has gone wrong"
                    },
                    "opStatus": "error"
                    }
                
You can use the error codes to map the error in your own application.

Methods

The following document describes the operations you will be able to execute with the WritePath Translation API.


Get word count of plain text(POST)

Summary
Receive the word count of the a text string. Text can include basic HTML tags which won't be counted.
URL
https://www.writepath.co/api/wordcount
Authentication
Required

Parameters

api_key required Your public API key
private_key required Your private API key
service required The service you require: 1 = editing, 2 = translation only, 4 = premium translation (translation + editing)
langID required The id of the translation / editing language. Click here to see the list of available languages.
text required the text you would like to have translated or edited. Can include HTML tags, these are not counted as words.

Example call

                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$service = '2'; // i.e. Standard Translation
$langID = '5'; // i.e. English - Chinese (Simplified)
$text = 'My very long text';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->getWordCountPlainText($service, $langID, $text);

Response

                {
                "response": {
                "wordCount": "710"
                },
                "opStatus": "ok"
                }
                

Get word count of document (POST)

Summary
Receive the word count of the text in a document (.docx, .pptx, .xlsx). Text can include basic HTML tags which won't be counted.
URL
https://www.writepath.co/api/wordcount
Authentication
Required

Parameters

api_key required Your public API key
private_key required Your private API key
service required The service you require: 1 = editing, 2 = translation only, 4 = premium translation (translation + editing)
langID required The id of the translation / editing language. Click here to see the list of available languages.
filename required The path + filename of your document (only .docx, .pptx, .xlsx)
                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$service = '2'; // i.e. Standard Translation
$langID = '5'; // i.e. English - Chinese (Simplified)
$filename = 'c:/mydoc.docx';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->getWordCountDocument($service, $langID, $filename);

Response

                {
                "response": {
                "wordCount": "710"
                },
                "opStatus": "ok"
                }
                

Post a job with plain text (POST)

Summary
Send a job with plain text to the service. The calculated word count will be deducted from your account and the case made available to translators/editors who match the category of your job. Use the method Get word count of plain text first, if you want to get a quote before you post a job.
URL
https://www.writepath.co/api/job
Authentication
required

Parameters

api_key required Your public API key
private_key required Your private API key
service required The service you require: 1 = editing, 2 = translation only, 4 = premium translation (translation + editing)
langID required The id of the translation / editing language. Click here to see the list of available languages.
category required The category / topic your text is about. Click here to see a list of available categories.
text required the text you would like to have translated or edited. Can include HTML tags, these are not counted as words.
instructions optional instructions for the translator / editor.
notify_url optional When job is finished, a REST post is sent to that URL

Example call

                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$service = '2'; // i.e. Standard Translation
$langID = '5'; // i.e. English - Chinese (Simplified)
$category = '3'; // i.e. Technology
$text = 'My very long text';
$instructions = 'here are my instructions';
$notify_url = 'http://www.mydomain.com/notify_me.php';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->sendPlainText($service, $langID, $category, $text, $instructions, $notify_url);

Response

                {
                "response": {
                "wordsUsed": "710",
                "orderId": "411"
                },
                "opStatus": "ok"
                }
                

Post a job with a document(POST)

Summary
Send a job with file attachment to the service. Supported file types: .docx, .xlsx, .pptx. The calculated word count will be deducted from your account and the case made available to translators/editors who match the category of your job. Use the method Get word count of document first, if you want to get a quote before you post a job.
URL
https://www.writepath.co/api/job
Authentication
required

Parameters

api_key required Your public API key
private_key required Your private API key
service required The service you require: 1 = editing, 2 = translation only, 4 = premium translation (translation + editing)
langID required The id of the translation / editing language. Click here to see the list of available languages.
category required The category / topic your text is about. Click here to see a list of available categories.
filename required The path + filename of your document (only .docx, .pptx, .xlsx)
instructions optional instructions for the translator / editor.
notify_url optional When job is finished, a REST post is sent to that URL

Example call

                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$service = '2'; // i.e. Standard Translation
$langID = '5'; // i.e. English - Chinese (Simplified)
$category = '3'; // i.e. Technology
$filename = 'c:/mydoc.docx';
$instructions = 'here are my instructions';
$notify_url = 'http://www.mydomain.com/notify_me.php';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->sendDocument($service, $langID, $category, $filename, $instructions, $notify_url);

Response

                    {
                    "response": {
                    "wordsUsed": "710",
                    "orderId": "411"
                    },
                    "opStatus": "ok"
                    }
                

Fetch job status(GET)

Summary
Retrieves a specific job.
URL
https://www.writepath.co/api/job/{id}
Authentication
required

Parameters

api_key required Your public API key
private_key required Your private API key
id required id of the job you want to fetch. It's the orderId you get returned if you post a job.
format required The format of the returned content. 1 = as a file, 2 = as plain text

Example call

                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$id = '379';
$format = '1';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->getStatus($id, $format);

Response (document)

                    {
                    "response": {
                    "wordsUsed": "710",
                    "status": "finished",
                    "dueDate": "1384570722",
                    "wordsBalance": "532",
                    "commentFinished": "",
                    "document": "A4BDLP0..." (base64)
                    },
                    "opStatus": "ok"
                    }
                

Response (plain text)

                    {
                    "response": {
                    "wordsUsed": "710",
                    "status": "finished",
                    "dueDate": "1384570722",
                    "wordsBalance": "532",
                    "commentFinished": "",
                    "document": "this is the translated text"
                    },
                    "opStatus": "ok"
                    }
                

Possible values for status are "working" and "finished". "commentFinished" and "document" are set as soon as the process is finished. "document" contains the edited document as base64 encoded Microsoft Word document.


Fetch current word balance (POST)

Summary
Retrieves the current word count balance.
URL
https://www.writepath.co/api/balance
Authentication
required

Parameters

api_key required Your public API key
private_key required Your private API key

Example call

                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->getWordBalance();

response

                    {
                    "response": {
                    "wordsBalance": "522"
                    },
                    "opStatus": "ok"
                    }
                

Post a comment (POST)

Summary
Post a comment on a job.
URL
https://www.writepath.co/api/jobs/{id}/comment
Authentication
required

parameters

api_key required Your public API key
private_key required Your private API key
id required The id of the job (= orderId) you want to comment on.

Example call

                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->postComment(379,'this is a comment for job #379');

response

                    {
                    "response": {
                    },
                    "opStatus": "ok"
                    }
                

Post multiple jobs with plain text (POST)

Summary
Send multiple jobs with plain text to the service. The calculated word count will be deducted from your account and the case made available to translators/editors who match the category of your job. Use the method Get word count of plain text first, if you want to get a quote before you post a job.
URL
https://www.writepath.co/api/bjobs
Authentication
Required

Parameters

api_key required Your public API key
private_key required Your private API key
service required The service you require: 1 = editing, 2 = translation only, 4 = premium translation (translation + editing)
langID required The id of the translation / editing language. Click here to see the list of available languages.
category required The category / topic your text is about. Click here to see a list of available categories.
text required the array (List) of text you would like to have translated or edited. Can include HTML tags, these are not counted as words.
instructions optional instructions for the translator / editor.
notify_url optional When job is finished, a REST post is sent to that URL
                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$service = '2'; // i.e. Standard Translation
$langID = '6'; // i.e. English - Chinese (Traditional)
$category = '3'; // i.e. Technology
$text = {'My very long text','My very long another text'};
$instructions = 'here are my instructions';
$notify_url = 'http://www.mydomain.com/notify_me.php';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->sendPlainText($service, $langID, $category, $text, $instructions, $notify_url);

Response

                {"batchId":"31","response":[{"wordsUsed":"250","orderId":"40184"},{"wordsUsed":"3","orderId":"40186"}],"opStatus":"ok"}
                

Fetch multiple jobs status posted as a batch (GET)

Summary
Retrieves a specific job.
URL
https://www.writepath.co/api/bjob/{id}
Authentication
required

Parameters

api_key required Your public API key
private_key required Your private API key
id required id of the job you want to fetch. It's the orderId you get returned if you post a job.
format required The format of the returned content. 1 = as a file, 2 = as plain text. Only use 2 in this version, 1 is not supported yet.

Example call

                    include 'WritepathClient.php';

$api_key = '12345678';
$private_key = 'ABCDEFGH';

$id = '31';
$format = '2';

$WritepathClient = new WritepathClient($api_key, $private_key);
$reply = $WritepathClient->getBatchedStatus($id, $format);

Response (document)

                    {"batchId":31,"response":[{"wordsUsed":"250","status":"working","dueDate":"1487402914","wordsBalance":"1000","commentFinished":null,"document":null},{"wordsUsed":"3","status":"finished","dueDate":"1487402914","wordsBalance":"1000","commentFinished":"test","document":"this is the translated text"}],"opStatus":"ok"}
                

Response (plain text)

                    {
                    "response": {
                    "wordsUsed": "710",
                    "status": "finished",
                    "dueDate": "1384570722",
                    "wordsBalance": "532",
                    "commentFinished": "",
                    "document": "this is the translated text"
                    },
                    "opStatus": "ok"
                    }
                

Possible values for status are "working" and "finished". "commentFinished" and "document" are set as soon as the process is finished. "document" contains the edited document as base64 encoded Microsoft Word document.


Callbacks

Callbacks are automatic notifications which are sent to your notification URL (which you specify with your post job or post plain text method). Callbacks are available for the following events:


Callback when job has been finished (POST)

Callback result (document / plain text)

                    {
                    "response": {
                    "orderId": "2345",
                    "wordsUsed": "764",
                    "status": "finished",
                    "dueDate": "1405747052",
                    "commentFinished": null,
                    "A4BDLP0..." (base64)
                    },
                    "opStatus": "ok"
                    }
                

Callback when comment posted from translator or editor (POST)

Callback result

                    {
                    "response": {
                    "orderId": "2345",
                    "comment": "this is my comment",
                    "date": 1405561885
                    },
                    "opStatus": "ok"
                    }
                

Error codes

The following error codes are used. If you want to localize the message, use the code number to map your message.

Error code Error message
1000Authentication failed
1100api_key is a required field
1150private_key is a required field
1200ts - timestamp is a required field
1201ts - timestamp must be numeric
1250data is a required field
1251JSON data cannot be decoded
1252type is a required field and can only be 1 or 2
1800job is a required field
1801comment is a required field
1802file upload failed (did you check that the file is correct and the extension supported?)
1803Wrong file type
1804Wrong job id
1805No words in document
1806No words in plain text
1807Can't write to file
1808File too big. Max. 15MB allowed
2700Not enough word credits - please top up
3000body or document - only one field can be set
3001Neither body nor document are set - set one
3002Service type, language ID and category must be provided
3003Wrong category
3004Wrong service
3005Wrong language ID
3006Service and language ID do not match
3007Copy writing service not supported in API
3008all parameters are requested
3009need filename with document
3010need array of text
4000Can not add comment: job has not been claimed yet
4001Job unknown: check id
4002No result
4003API format doesn't match with your upload format (1=file, 2=plain text)

Download libraries

Download PHP translation API class (.zip) Ver. 1.2 Deprecated
Download Java translation API class (.zip) Ver. 1.2 Deprecated
Download PHP translation API class (.zip) Ver. 1.3
Download Java translation API class (.zip) Ver. 1.3