API Guide

The API guide lists all steps that are necessary (or optional) in order to integrate with contenthub. The steps are listed in a chronological order. Further details about objects, properties and endpoints can be found in the respective documentation.

  1. Login
  2. Upload document(s) for translation
  3. Configure and create a translationTask
  4. Refer the uploaded documents as source documents to a translationTask
  5. Complete translation task and wait for quotes
  6. Ask for quotes (already commited and open quotes)
  7. Accept and/or reject quotes
  8. Download target documents

1. Login

For login please see the example documentation for cURL: Authentication.

2. Upload document(s) for translation

Now you need to upload your documents you want to translate. You have several possibilities to upload documents please check the documents - specification for details. In this example we use the URI upload:

POST /rest/api/documents HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
ContentType: application/json

{
  "filename": "Lorem_ipsum.docx",
  "contentUri": "http://example.com/files/574d3526f342e39b88e5d414"
}

The response is the document:

HTTP/1.1 201 CREATED
Vary: Accept
Content-Type: text/javascript

{
  "length": 4461,
  "chunkSize": 261120,
  "uploadDate": "2016-07-30T11:10:00.184Z",
  "md5": "24c1750c14fcfdaabbbdb5150835fcb5",
  "filename": "Lorem_ipsum.docx",
  "id": "59a69d085606ba0007de6f50"
}

We need the document id in the next step.

3. Configure and create a translationTask

Now create a translationTask.

Example:

POST /rest/api/translationTasks HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
ContentType: application/json

{
  "source": "de-DE",
  "target": "en-GB",
  "projectId": "57d830ba0f620b2c4ab206db"
}

The response is the created translationTask. Please use the id of the translationTask for any further operation. The translationTask id should be also stored in the system that implements the connector, because it is the unique identifier which refers to the sent translation inside the client system.

{
  "id": "5804c3d5ffd16c59fd02d8a0",
  "source": "de-DE",
  "target": "en-GB",
  "createdAt": "2016-10-17T12:28:04.955+0000",
  "desiredDeadline": null,
  "complete": false,
  "email": "api-user@example.tld",
  "progress": "NEW",
  "projectId": "57d830ba0f620b2c4ab206db"
}

Please see TranslationTasks documentation for details.

4. Refer the uploaded documents as source documents to a translationTask

We use the document id to refer the document as source document to our created translationTask. You can either use the /translationTask/:id/sourceDocuments endpoint to do it, or you simply patch the translationTask:

Example:

PATCH /rest/api/translationTasks/:id HTTP/1.1

{
  "sourceDocumentIds": ["59a69d085606ba0007de6f50"]
}

You can also skip this step by simply provide the sourceDocumentIds in Step 3 like that:

Example:

POST /rest/api/translationTasks HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
ContentType: application/json

{
  "source": "de-DE",
  "target": "en-GB",
  "projectId": "57d830ba0f620b2c4ab206db",
  "sourceDocumentIds": ["5804c2afffd16c59fd02d89e"]
}

5. Mark the translationTask as “complete” and wait for quotes

To finish your translationTask configuration you need to set it to “complete”. To do so just change the “complete” property of the translationTask from false to true.

Example:

PATCH /rest/api/translationTasks/:id HTTP/1.1

{
  "complete": true
}

Now the system automatically creates quote enquiries for the configured vendors. And you can expect quotes soon.

6. Ask for quotes (already commited and open quotes)

You can simply pull the quotes endpoint of a translationTask to receive all quotes. Also you can pull the quoteEnquiries endpoint of a translationTask to check how many quotes you can expect.

Example

Check for already commited quotes:

GET /rest/api/translationTasks/:id/quotes HTTP/1.1

{
  "complete": true
}

Response:

[
  {
    "connectorQuoteId": "5891a7d00f62c3637782b978",
    "connectorEnquiryId": "5891a7b70f62c3637782b976",
    "createdAt": "2017-02-01T09:18:16.471Z",
    "number": "43949",
    "price": {
      "netAmount": "429.31",
      "vatPercentage": "19.0",
      "currency": "EUR",
      "vatAmount": "81.57",
      "grossAmount": "510.88"
    },
    "supplierName": "Test 24translate GmbH",
    "state": "OFFERED",
    "tapQuoteEnquiryId": "SYHNj2hZDTKBBQnPn",
    "id": "5891a7d802dde409d133ae51"
  },
  {
    "connectorQuoteId": "7276d72c-b50f-430f-880d-a73d45a0719b",
    "connectorEnquiryId": "5891a7c80f62d543d66b2ab2",
    "createdAt": "2017-02-01T09:18:16.641Z",
    "number": "MOCK-0fb643e7-9aed-42e0-9757-3fee9d26aea9",
    "price": {
      "netAmount": "587.73",
      "vatPercentage": "19",
      "currency": "EUR",
      "vatAmount": "111.67",
      "grossAmount": "699.40"
    },
    "supplierName": "Wieners + Wieners",
    "state": "OFFERED",
    "tapQuoteEnquiryId": "TGpbfP9d73PMtw6XZ",
    "id": "5891a7d802dde409d133ae56"
  }
]

Check for available quote enquiries:

GET /rest/api/translationTasks/:id/quoteEnquiries HTTP/1.1

Response:

[
  {
    "createdAt": "2017-02-01T08:15:02.010Z",
    "authorizationKey": "6171d2f4-acf0-4d91-8ce8-60f7c3465a4a",
    "lspVendorId": "579f5bdc0f6215543b5f5861",
    "lspVendorName": "Test 24translate GmbH",
    "translationTaskId": "uCbrmmRige6sTnXju",
    "enquiryId": "5891a7b70f62c3637782b976",
    "quotesFetched": true,
    "id": "SYHNj2hZDTKBBQnPn"
  },
  {
    "createdAt": "2017-02-01T08:15:02.010Z",
    "authorizationKey": "d0f579f0-0538-45d6-9de6-649631d8745d",
    "lspVendorId": "zbWp3XMAjuHxesKd3",
    "lspVendorName": "Wieners + Wieners",
    "translationTaskId": "uCbrmmRige6sTnXju",
    "enquiryId": "5891a7c80f62d543d66b2ab2",
    "quotesFetched": true,
    "id": "TGpbfP9d73PMtw6XZ"
  }
]

When the quotes are commited you will also see the quote reference (id) in the translationTask:

{
  "createdAt": "2017-02-01T09:18:16.643Z",
  "source": "de",
  "target": "fr",
  "desiredDeadline": "2017-02-03T09:00:00.000Z",
  "complete": true,
  "email": "api-user@example.tld",
  "sourceDocumentIds": [
    "5891a7a6883834000bfe8138"
  ],
  "quoteIds": [
    "5891a7d802dde409d133ae51",
    "5891a7d802dde409d133ae56",
    "5891a7d802dde409d133ae58"
  ],
  "progress": "TASK_COMPLETE",
  "projectId": "RJ3K7xW4axLWn5pGE",
  "id": "uCbrmmRige6sTnXju"
}

7. Accept and/or Reject quotes

To accept or reject quotes simply set the state of the quote you want to accept/reject. Please note that when you accept one quote, all other quotes will be rejected automatically.

Example

PATCH /rest/api/quotes/:id HTTP/1.1

{
  "state": "ACCEPTED"
}

Please see Quotes documentation for details. When a quote is accepted you can not change the state anymore to REJECTED.

The vendor gets notified automatically and the translation will be started. Now you just need to wait for the finished translation.

8. Download target documents

When the translation is delivered, the progress of the translationTask changes to TRANSLATION_DELIVERED.

Example

{
  "createdAt": "2017-01-24T17:54:07.763Z",
  "source": "en",
  "target": "pl",
  "desiredDeadline": "2017-01-30T08:00:00.000Z",
  "complete": true,
  "email": "api-user@example.tld",
  "sourceDocumentIds": [
    "5835d98ed523ad00204d1358",
    "5835d96bd523ad00204d1354",
    "588604f72331ab000aa06f81",
    "58860876ea3d5e000b920577"
  ],
  "quoteIds": [
    "58888d1c02dde40267d2dd06",
    "58888d1c02dde40267d2dd0b"
  ],
  "progress": "TRANSLATION_DELIVERED",
  "projectId": "RJ3K7xW4axLWn5pGE",
  "id": "AQT4Dn6YJRwGCpnue"
}

Simply pull the translationTask/:id endpoint to check the progress. Now you can download the translations. To do so use the translationTask/:id/targetDocuments/content endpoint and you will receive all targetDocuments as a zip-archive.

Example

GET /rest/api/translationTasks/:id/targetDocuments/content HTTP/1.1

To receive the documentIds you can pull the translationTask/:id/targetDocuments endpoint:

GET /rest/api/translationTasks/:id/targetDocuments HTTP/1.1

Response

[
  {
    "filename": "test.xlf",
    "aliases": null,
    "chunkSize": 261120,
    "uploadDate": "2017-01-25T13:40:08.827Z",
    "length": 36867,
    "contentType": "application/x-xliff+xml",
    "md5": "1b554cfb7aadded9fda20fbc60eb4803",
    "createdAt": "2017-01-25T13:40:08.827Z",
    "id": "5888aab802dde40267d45581"
  },
  {
    "filename": "test2.xlf",
    "aliases": null,
    "chunkSize": 261120,
    "uploadDate": "2017-01-25T13:40:09.205Z",
    "length": 771283,
    "contentType": "application/x-xliff+xml",
    "md5": "c237cbef12fac2cde1f0aa79ee81c308",
    "createdAt": "2017-01-25T13:40:09.205Z",
    "id": "5888aab902dde40267d45583"
  }
]

When no documents are available the response is an empty array.