Introduction

SmartMATE WorkFlow API is an Application Programmable Interface (API) offered to allow the integration of the services into your automated translation process.

The API calls use the HTTP protocol with common operations such as GET and POST. JSON data structures and data streams are used to transfer data between API clients and servers. The API is fully REST compliant which makes the API straightforward to integrate with a number of different systems.

How it works

The central concept of the SmartMATE WorkFlow API is request management. A request is an API call to a pre-defined translation task. The current API allows users to create a translation request, to query the progress of an existing request, and to download translated files when the request is completed.

Base URL

All RESTful API calls starts with the following URL prefix:

https://workflow-api.smartmate.co/api/v1.0

Authentication

HTTP Basic Authentication is supported to access the API. A username and password needs to be supplied in the HTTP header which will be authenticated against your account. To create a new request, the Customer Name and Contact Name are also needed from your account. Therefore, before accessing the API, users will need to request a username and password from us. Please contact our pre-sales team, so they can set up your account and supply your username and password.

API

The SmartMATE WorkFlow API is composed of three parts:

  • the languages API: to list the available languages

  • the requests API: for the creation and query of translation requests

  • the document API: to download translated documents.

languages

https://workflow-api.smartmate.co/api/v1.0/languages

GET

  • Description

HTTP GET method. It is used to list all supported languages that can be used in the following API methods.

  • Parameters

Table 1. Parameters for HTTP GET method of API /languages
Parameter Description

username

Required. The username of your account.

password

Required. The password of your account.
username and password parameters must both be provided in the HTTP header as part of HTTP Basic Authentication.

  • Response

The response is a JSON-encoded array, and each of the elements includes the following properties:

Table 2. Response for HTTP GET method of API /languages
Property Description

IsoCode

The ISO code of the language.

LanguageName

The name of the language.

  • Example [1]

The following example retrieves all supported languages from the SmartMATE WorkFlow API:

$ http -a "my_username":"my_password" GET https://workflow-api.smartmate.co/api/v1.0/languages
HTTP/1.0 200 OK
...
Content-Type: application/json
...
[
    {
        "IsoCode": "ach-EA",
        "LanguageName": "Acholi"
    },
    {
        "IsoCode": "aa-EA",
        "LanguageName": "Afar"
    },
...
    {
        "IsoCode": "zu-ZA",
        "LanguageName": "Zulu"
    }
]

requests

https://workflow-api.smartmate.co/api/v1.0/requests

GET

  • Description

HTTP GET method. It is used to list out all the requests of the current user in the API system. Extra parameters can be specified to filter the result.

The returned requests are always paginated and maximum number of 10 records are returned in one query.

  • Parameters

Table 3. Parameters for HTTP GET method of API /requests
Parameter Description

page

Optional. Integer number indicate the number page to display.

Tags

Optional. Only show the requests with given Tags. This parameter can be specified more than once, and any requests with at least one of the specified tags will be returned. A maximum number of 20 Tags parameter can be specified in one query.

-Tags

Optional. Hide the requests with given Tags. This parameter can be specified more than once, and any requests with any of the specified tags will NOT be returned. A maximum number of 20 -Tags parameter can be specified in one query.
username and password parameters must both be provided in the HTTP header as part of HTTP Basic Authentication.
Tags can be created in the POST method at request creation stage, or can be modified through PATCH method after creation.

  • Response

The response is a JSON-encoded object with the following properties:

Table 4. Response for HTTP GET method of API /requests
Property Description

count

The total number of requests that can be returned given the condition.

next

url to the next page.

previous

url to the previous page.

results

A JSON-encoded array, and each element is the content of a one request object. The detail of a request object content can be referred below as the response of GET method of requests/<request-id-or-no>.

  • Example [1]

$ http -a "your_username":"your_password" GET https://workflow-api.smartmate.co/api/v1.0/requests
HTTP/1.0 200 OK
...
Content-Type: application/json
...
{
    "count": 12,
    "next": "https://workflow-api.smartmate.co/api/v1.0/requests?page=2",
    "previous": null,
    "results": [
        ...
    ]
}
$ http -a "your_username":"your_password" GET https://workflow-api.smartmate.co/api/v1.0/requests/?Tags='havetag1'\&-Tags='notag2'
HTTP/1.0 200 OK
...
Content-Type: application/json
...
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        ...
    ]
}

POST

  • Description

HTTP POST method. It is used to create a new request by posting file data and associated parameters. File data is required to create a request. Users can post multiple files in an array in one API call. Each file that is posted in the request will be stored as a document in SmartMATE WorkFlow system, and a document ID will be returned for reference. The returned document IDs will be in an array that is in the same order as the files were posted in the request array.

If a request is created successfully from the API call, a request ID and number will be returned for reference. Users can use request ID or number to query the request and document status through the API call request/<request_id_or_no> method below.

The content type of the request must be multipart/form-data.

  • Parameters

Table 5. Parameters for HTTP POST method of API /requests
Parameter Description

username

Required. The username of your account.

password

Required. The password of your account.

CustomerName

Required. The complete name of a particular customer that is allocated by us.

ContactName

Required. The complete name, formatted as LastName, FirstName, of a contact from the previously specified customer.

SourceLanguageCode

Required. The value is the ISO code obtained from the /languages method.

TargetLanguageCodes

Required. The value is the ISO code obtained from the /languages method.

DeliveryDate

Required. The expected delivery date, formatted as yyyy-MM-dd hh:mm:ss (i.e.: 2010-09-13 14:35:29).

Title

Optional. The title of the created request flow. Will leave empty if not supplied.

Note

Optional. The instructions and comments on the created request flow. Will leave empty if not supplied.

PurchaseOrder

Optional. The purchase order on the created request flow. Will leave empty if not supplied.

files

Required. Source file content posted in multipart/form-data format.

references

Optional. Reference file content posted in multipart/form-data format.

NotifyUrl

Optional. The notification URL that SmartMATE API system will POST to after the request status has been marked as completed.

Tags

Optional. The list of tags. Tags can only be alphanumeric characters, and less than 64 characters. It can be specified more than once to allow multiple Tags for one request. One request can have maximum number of 20 Tags.

RequesterReference

Optional. Requester name or number for tracking purpose.

PIN

Optional. Unique PIN number for tracking purpose.
username and password parameters must both be provided in the HTTP header as part of HTTP Basic Authentication.
TargetLanguageCodes may be specified more than once to allow the translation from one source language into multiple target languages. All target languages specified by TargetLanguageCodes will be joined together as a complete list of target languages. For each of the source files in the request, there will be a number of final documents at the end, depending on the number of target languages specified. For client tools that don’t support sending multiple TargetLanguageCodes parameters, you can join all language codes into a single one with commas (e.g. en-US, fr-FR, de-DE) and send it with one TargetLanguageCodes parameter.
files and references can be specified more than once to allow the translation of multiple files with multiple references. There is no requirements that one translation file need to have one reference file, since reference is only optional can can be even supplied within a single zipped file. However, for client tools that don’t support sending file data with the same parameter name, you can send multiple file data with with name file_0, file_1, …​, file_N, or reference_0, reference_1, …​, reference_N. Again, there is no need to correspdonent reference_n with file_n. Also For each of the files specified in the request, there will be one source document associated with the generated request.
If NotifyUrl is supplied, once the request status has become completed, SmartMATE API system will POST to the specific URL with the following fields: RequestId, RequestNo and RequestStatus. Unless the response of the POST request to NotifyUrl returns HTTP status code 200, SmartMATE API system will retry POST to the same URL for another 7 times, the time difference between the following ones will be 5 minutes, 10 minutes, 30 minutes, 1 hour, 6 hours, 12 hours and 1 day. It will stop if any of the retries responses with HTTP status code 200. Note that the above intervals are approximated and are not guaranteed to be on time and also there might be more or less notifications than expected, subject to the settings of API system.

  • Response

The response is a JSON-encoded object with the following properties:

Table 6. Response for HTTP POST method of API /requests
Property Description

RequestId

The ID of the created request for further reference.

RequestNo

The number of the created request for further reference.

RequestStatus

The status of the created request, can only be one of completed, onHold or inProgress.

Documents

A JSON-encoded array stands for the source documents of the created request, and each of the elements correspond to the posted file objects. Each of the element includes properties in the following table.

Property Description

DocumentId

The ID of the document.

DocumentName

The name of the document, which was from the file object in the API request.

IsoCode

The ISO code of the language of the source document.

LanguageName

The name of the language of the source document.

References

A JSON-encoded array stands for the reference files of the created request. Each of the element includes properties in the following table.

Property Description

ReferenceName

The name of the reference document, which was from the reference object in the API request.

  • Example [1]

$ http -f -a "your_username":"your_password" POST https://workflow-api.smartmate.co/api/v1.0/requests \
CustomerName="Your Customer Name" ContactName="Your Contact Surname, Your Contact First Name" \
SourceLanguageCode="en-US" TargetLanguageCodes="de-DE" TargetLanguageCodes="zh-CN" \
DeliveryDate="2016-12-12 12:12:12" \
files@/path/file-one-name.txt files@/path/file-two-name.txt
HTTP/1.1 201 CREATED
...
Content-Type: application/json
...
{
    "Documents": [
        {
            "DocumentId": null,
            "DocumentName": "file-one-name.txt",
            "IsoCode": "en-US",
            "LanguageName": "English (USA)"
        },
        {
            "DocumentId": null,
            "DocumentName": "file-two-name.txt",
            "IsoCode": "en-US",
            "LanguageName": "English (USA)"
        }
    ],
    "RequestId": "1250936094-13321",
    "RequestNo": "TI-160302-1",
    "RequestStatus": "onHold"
}

requests/<request-id-or-no>

https://workflow-api.smartmate.co/api/v1.0/requests/<request-id-or-no>

For backward compatibility, the following URL still works:

https://workflow-api.smartmate.co/api/v1.0/request/<request-id-or-no>

GET

  • Description

HTTP GET method. It is used to query the status of the request created by /requests method. It also returns available final documents associated with the request.

A valid request ID or number (noted as <request-id-or-no> in the API URL) returned by a successful /requests method is required to form the URL.

  • Parameters

Table 7. Parameters for HTTP GET method of API /request/<request-id-or-no>
Parameter Description

username

Required. The username of your account.

password

Required. The password of your account.
username and password parameters must both be provided in the HTTP header as part of HTTP Basic Authentication.

  • Response

The response is a JSON-encoded object with the following properties:

Table 8. Response for HTTP GET method of API /request/<request-id-or-no>
Property Description

RequestId

The ID of the queried request.

RequestNo

The number of the queried request.

RequestStatus

The status of the queried request, can only be one of onHold, inProgress or completed.

Documents

A JSON-encoded array stands for the source documents of the created request, and each of the elements correspond to the posted file objects. Each of the elements includes properties in the following table.

Property Description

DocumentId

The ID of the source document.

DocumentName

The name of the source document.

IsoCode

The ISO code of the language of the source document.

LanguageName

The name of the language of the source document.

FinalDocuments

A JSON-encoded array contains all final document for this source document, and properties of the elements as explained in the following table FinalDocuments table.

Tracking

A JSON-encoded array stands for the tracking information of the created request. The tracking information is broken down into language first, then each language is broken down into files. The first level is target language information, and each of the elements includes properties in the following table.

Property Description

LanguageCode

The IsoCode of the target language.

LanguageStatus

The current status of all the documents in this language, can only be one of onHold, inProgress or completed.

Progress

Optional. The percentage of current progress of the target language.

Documents

Optional. A JSON-encoded array contains all documents for this target language, and properties of the elements as explained in the following Documents table.
Table 9. Element properties of FinalDocuments field of the Documents field of response to HTTP GET method of API /request/<request-id-or-no>
Property Description

DocumentId

The ID of the final document. Its value is used in the API /document/<document-id> to download file content.

DocumentName

The name of the final document.

IsoCode

Optional. The ISO code of the language of the final document.

LanguageName

Optional. The name of the language of the final document.
Table 10. Element properties of Documents field of the Tracking field of response to HTTP GET method of API /request/<request-id-or-no>
Property Description

DocumentId

The ID of the original document.

DocumentName

The name of the original document.

DocumentStatus

The current status of this document, can only be one of onHold, inProgress or completed.

Progress

Optional. The percentage of current progress of the document.

CurrentStep

Optional. The name of localisation step that the document is currently on.
Depending on the delivery, it is possible that some of the target languages specified in the request have no final document associated with them. So it is possible that the FinalDocuments field length will vary for each of the source documents.
DocumentId of the original documents could be changed until the status of the request is turned into completed.
Tracking information is optional and should not be relied for final document delivery. Note that if there were any differences between the Documents property on the root level and the Tracking property, please use the information from the Documents property on the root level. Tracking information is only available to requests submitted to the live system since August 2019, the staging system doesn’t offer tracking information.

  • Examples [1]

$ http -a "your_username":"your_password" GET https://workflow-api.smartmate.co/api/v1.0/request/TI-160302-5
HTTP/1.1 200 OK
...
Content-Type: application/json
...
{
    "RequestId": "1250936094-13325",
    "RequestNo": "TI-160302-5",
    "RequestStatus": "onHold",
    "Tracking": null
}
$ http -a "your_username":"your_password" GET https://workflow-api.smartmate.co/api/v1.0/request/TI-160302-5
HTTP/1.1 200 OK
...
Content-Type: application/json
...
{
    "RequestId": "1250936094-13325",
    "RequestNo": "TI-160302-5",
    "RequestStatus": "inProgress",
    "Tracking": [
        {
            "Documents": [
                {
                    "CurrentStep": "Validation",
                    "DocumentId": "746155792-85278",
                    "DocumentName": "file-one-name.txt",
                    "DocumentStatus": "inProgress",
                    "Progress": "80%"
                },
                {
                    "CurrentStep": "Translation",
                    "DocumentId": "746155792-85279",
                    "DocumentName": "file-two-name.txt",
                    "DocumentStatus": "inProgress",
                    "Progress": "20%"
                }
            ],
            "LanguageCode": "en-US",
            "LanguageStatus": "inProgress",
            "Progress": "50%"
        },
    ]
}
$ http -a "your_username":"your_password" GET https://workflow-api.smartmate.co/api/v1.0/request/TI-160302-5
HTTP/1.1 200 OK
...
Content-Type: application/json
...
{
    "Documents": [
        {
            "DocumentId": "746155792-85278",
            "DocumentName": "file-one-name.txt",
            "FinalDocuments": [
                {
                    "DocumentId": "746155792-85297",
                    "DocumentName": "file-one-name_1.txt",
                    "IsoCode": "",
                    "LanguageName": ""
                },
                {
                    "DocumentId": "746155792-85298",
                    "DocumentName": "file-one-name_2.txt",
                    "IsoCode": "",
                    "LanguageName": ""
                }
            ],
            "IsoCode": "en-US",
            "LanguageName": "English (USA)"
        },
        {
            "DocumentId": "746155792-85279",
            "DocumentName": "file-two-name.txt",
            "FinalDocuments": [
                {
                    "DocumentId": "746155792-85299",
                    "DocumentName": "file-two-name_1.txt",
                    "IsoCode": "",
                    "LanguageName": ""
                }
            ],
            "IsoCode": "en-US",
            "LanguageName": "English (USA)"
        }
    ],
    "RequestId": "1250936094-13325",
    "RequestNo": "TI-160302-5",
    "RequestStatus": "completed",
    "Tracking": [
        {
            "Documents": [
                {
                    "DocumentId": "746155792-85278",
                    "DocumentName": "file-one-name.txt",
                    "DocumentStatus": "completed",
                    "Progress": "100%"
                },
                {
                    "DocumentId": "746155792-85279",
                    "DocumentName": "file-two-name.txt",
                    "DocumentStatus": "completed",
                    "Progress": "100%"
                }
            ],
            "LanguageCode": "en-US",
            "LanguageStatus": "completed",
            "Progress": "100%"
        },
    ]
}

PATCH

  • Description

HTTP PATCH method. It is used to modify a created request. Currently only the Tags field can be modified.

  • Parameters

Table 11. Parameters for HTTP PATCH method of API /document/<document-id>
Parameter Description

Tags

Optional. The new tags for the specific request. If one empty string is specific, the current Tags field will be cleared to empty. Tags can only be alphanumeric characters, and less than 64 characters. It can be specified more than once to allow multiple Tags for one request, and one request can only have maximum number of 20 Tags.
username and password parameters must both be provided in the HTTP header as part of HTTP Basic Authentication.
The content type of the request must be multipart/form-data.

  • Response

The response is the same as GET method of requests/<request-id-or-no>.

  • Example [1]

$ http -f -a "your_username":"your_password" PATCH https://workflow-api.smartmate.co/api/v1.0/requests/[request_no] Tags="newtag1" Tags="newtag2"
HTTP/1.0 200 OK
...
Content-Type: application/json
...
{
    ...
    "Tags": [
        "newtag1",
        "newtag2"
    ],
    ...
}

documents/<document-id>

https://workflow-api.smartmate.co/api/v1.0/documents/<document-id>

For backward compatibility, the following URL still works:

https://workflow-api.smartmate.co/api/v1.0/document/<document-id>

GET

  • Description

HTTP GET method. It is used to obtain the final document content as a data stream.

A valid document ID (noted as <document-id> in the API URL) returned by a successful /request/<request_id_or_no> method is required to form the URL.

  • Parameters

Table 12. Parameters for HTTP GET method of API /document/<document-id>
Parameter Description

username

Required. The username of your account.

password

Required. The password of your account.
username and password parameters must both be provided in the HTTP header as part of HTTP Basic Authentication.

  • Response

The final document content is served as application/octet-stream. The client can read the stream data and write it to a local file for storage.

  • Example [1]

$ http -a "your_username":"your_password" GET https://workflow-api.smartmate.co/api/v1.0/document/746155792-85299
HTTP/1.0 200 OK
Connection: close
Content-Type: application/octet-stream
...
[the actual content of the file is omitted here]

Error Handling

Standard HTTP Status Codes have been used in the API. If the API failed for a certain reason, it will return a JSON object with the following properties:

Property Description

detail

Optional. The reason of API failure.

[parameter_name]

Optional. The reason of API failure for this particular parameter.

If you have any difficulty consuming the API, please contact us at support@smartmate.co.

Testing (Staging) Environment

Staging environment is set up for testing purpose only, and supports all the API above. To access the staging environment, access URI needs to be changed from https://workflow-api.smartmate.co/ to https://workflow-api.smartmate.co/staging/ for all the URIs above. Therefore, the above URIs now becomes:

https://workflow-api.smartmate.co/staging/api/v1.0/languages
https://workflow-api.smartmate.co/staging/api/v1.0/requests
https://workflow-api.smartmate.co/staging/api/v1.0/requests/<request-id-or-no>
https://workflow-api.smartmate.co/staging/api/v1.0/documents/<document-id>

Staging system is independent from the production system, therefore, make sure you are using the correct username, password, Customer Name and Contact Name that were issued to you for the staging system, if they are different from the ones for the production system.

Browsable API

Please click API-Root to navigate through the the browsable API.

1. Examples are illustrated with HTTPie, which is a user-friendly cURL-like tool that can consume RESTful services easily. Due to compatibility issues, the version of HTTPie that is used in this documentation is 1.0.0-dev. Please check HTTPie documentation for installation guides.