API Technology (TMS)

Content is machine translated from English by Phrase Language AI.

Our API sees application entities (projects, jobs, settings) as resources that can be retrieved, created, modified, and deleted.

Every HTTP method represents an action:

GET

Retrieves a resource, never changing the resource
POST

Creates a resource. POST is also used for operations that don’t fit into any of the four operations or have long or complex input—like searching translation memories or creating jobs.
PUT

Updates the resource. Please note that the whole entity is required with all of its fields, not only those changed; not including it means it should be set to null.
DELETE

Deletes the resource.

Important

Input and output data are usually in JSON format, UTF-8 encoded. For a file as request body content type application/octet-stream or multipart/form-data is used.

Entities use a flat structure when possible to maintain good response times. Instead of including whole child objects in answers, references that contain the ID, UID, and a few other attributes are contained. Either IDReference or UidReference objects to refer to related entities are expected.

All response lists are paged. Use the parameters pageNumber and pageSize to retrieve requested data. The maximum page size is 50.

Documentation

OpenAPI 3.0 is used for API documentation. Swagger code generators are recommended for client development.

Raw documentation files:

JSON
YAML

API Examples

Get list of all translation memories

GET

/web/api2/v1/transMemories

Response

200

{
    "pageNumber": 0,
    "content": [
        {
            "internalId": 1,
            "createdBy": {
                "userName": "admin",
                "id": "3",
                "firstName": "Jan",
                "lastName": "Janocko",
                "role": "ADMIN",
                "email": "jan.janocko@phrase.com"
            },
            "client": null,
            "note": "not necessary to use in TM",
            "dateCreated": "2018-01-09T14:07:46+0000",
            "id": "1",
            "targetLangs": [
                "es",
                "it"
            ],
            "subDomain": null,
            "businessUnit": {
                "id": "1",
                "name": "First BU"
            },
            "sourceLang": "en",
            "domain": null,
            "name": "My new TM"
        }
    ],
    "numberOfElements": 1,
    "totalElements": 1,
    "pageSize": 50,
    "totalPages": 1
}

Create new a translation memory

POST

/web/api2/v1/transMemories

{{
"name": "My new TM",
"sourceLang": "en",
"targetLangs": [
"es", "it-IT"
],
"businessUnit": {
"id": "1"
},
"note": "not necessary to use in TM"
}

Response

201

{
    "internalId": 1,
    "createdBy": {
        "userName": "admin",
        "id": "3",
        "firstName": "J",
        "lastName": "Jan",
        "role": "ADMIN",
        "email": "jan.j@phrase.com"
    },
    "client": null,
    "note": "not necessary to use in TM",
    "dateCreated": "2018-01-09T14:07:46+0000",
    "id": "1",
    "targetLangs": [
        "es",
        "it"
    ],
    "subDomain": null,
    "businessUnit": {
        "id": "1",
        "name": "First BU"
    },
    "sourceLang": "en",
    "domain": null,
    "name": "My new TM"
}

Adding Files When Creating a Job

Add this file to the body of the request as a binary attachment. Ensure Phrase and the Content-Disposition headers are correctly inserted.

Sample PHP from Postman:

<?php

$request = new HttpRequest();
$request->setUrl('https://cloud.memsource.com/web/api2/v1/projects/%7BUID%20of%20your%20project%7D/jobs');
$request->setMethod(HTTP_METH_POST);

$request->setQueryData(array(
'token' => 'Your token goes here'
));

$request->setHeaders(array(
'postman-token' => 'ABC',
'cache-control' => 'no-cache',
'content-disposition' => 'filename*=UTF-8''Sample.txt',
'memsource' => '{\\"targetLangs\\":[\\"de\\",\\"fr\\",\\"es\\"],\\"callbackUrl\\":\\"https://my-shiny-service.com/consumeCallback\\",\\"importSettings\\":{\\"uid\\":\\"WF0T1SfSHxII09yKr0dZh9\\"}}'
));

try {
$response = $request->send();

echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}

Error Handling

If there is a problem when handling an API request, the following JSON structure will be returned. The error code will always be present; the detailed description may be null.

{ "errorCode": "InvalidArguments",
"errorDescription": "Required argument \"password\" of type \"string\" is missing."
}

An error response can be detected by reading the HTTP status code of the response. If an error occurs, it will never be set to 2xx. The status code is 400 bad request, 401 or 403 for authentication or authorization problems.

Reporting Problems

When reporting problem to Technical Support, includes the following in the report:

API endpoint
Request
Time (and timezone)
Response
Phrase-Action-ID of the response