Intercontact InterTMS Translation API

intercontact translations has been helping companies communicate more successfully since 1991. What makes us different from others on the market? Our passion, sophisticated language technologies and high standards of quality.

This short guide is a starting point to connect your application or translation workload to intercontact’s Translation API.

Full documentation with examples for all calls is available at

About the InterTMS Translation API

The InterTMS Translation API can be used to digitally retrieve and transmit translations to intercontact.

It is based on the REST standard for HTTP-API’s which is the standard predominantly used to exchange data between machines. It is easy for people to read and minimizes the transmition overhead.

The following chapters will give any developer a basic understanding of how to send translatable text and retrieve the final translation afterwards.

How to get access to the API

The InterTMS is a closed API. In order To get started with automated translation workflows, you should first get in contact with the sales team. You can reach out to them via e-mail ( or by phone. Check out for more information.


We will describe the important endpoints and entities in this section.


A projectDefinition is a pre defined project definition. It will describe the properties of the text you send to us. This could be used e.g. for identifying machine translation text vs. human translation text or any other special requirements for your specific use case. We will provide you with this information beforehand.


A translationJob contains translationUnits. You can add as many translationUnits to a TranslationJob as you like. It helps to group logical linked translationUnits to a logical unit. You also need to define the source language and the requested target languages at this stage.


A translationUnit is a logical part of your translation content. This could be e.g. a product name, product description, page content or any other content. The source text can be provided as plain text or HTML format. Keep in mind that the maximum text length is 500,000 characters. It is possible to assign an identifier to each translationUnit. This could be helpful for later identification and matching for the import process. This identifier needs to be smaller than 255 characters.


The API is secured with a technique called JSON Web Token (JWT). It utilizes the standard authorization header using the Bearer scheme. Example: “Bearer {token}”. The intercontact Translation API is secured with the JSON Web Token industry standard (RFC 7519). Each customer is provided with an individual user account to request a short lived bearer token which must be implemented in the authorization header. You can get an access token from the authorization endpoint located at for the live environment or at for the sandbox environment. The oauth2 authentication flow has to be “grant_type”=“password”. The corresponding client has to be “client_id”=“CustomerAPI”. You can find a full documentation of JWT-tokens and how they work here:


Request POST Payload

    "grant_type": "password"
	"username": "%USERNAME%"
    "password": "%PASSWORD%"

Request Headers

Content-Type: application/x-www-form-urlencoded

Response Body

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c","expires_in":3600,"token_type":"Bearer","scope":"openid profile roles"}

TranslationJob Endpoint

This is the first endpoint in the process of transmitting translatable text to intercontact. It returns an Identifier which is necessary for the next API calls. In this endpoint you define a collection like entity which you can then fill with translationUnit’s.


Request POST Payload

	"foreignIdentifier":  "ProductId:80",
	"targetLanguages": [
	"sourceLanguage":  "de-DE",
	"projectDefinition":  "33BA86CD-D0DD-4B92-DCF9-08D9DCD21C67"

Response Body Code 200: OK

This endpoint will return the translationJob ID. This is necessary to submit the actual translations in the next step!


TranslationUnit Endpoint

This is the endpoint used to submit the actual translations to intercontact. This call can be called multiple times depending on your use case and data structure.


Request POST Payload

        "text": "T-Shirt blau",
        "language": "de-DE"
    "externalId": "ProductId:80:Title",
    "jobId": "c4defabc-1301-4297-8715-8fdfbc0b716a",

Response Body Code 200: OK

This endpoint will return the created translationUnit ID.


Mark TranslationJob as complete

When all translationUnit’s have been transmitted to intercontact, the next step to get the translationJob translated, is to mark the created translationJob as ready for translation. This action cannot be reverted. After setting the translationJob to the ready state, no changes can be made to that particular translationJob and it’s translationUnit’s.

Retrieving final translations

Option 1: Polling for status change

It is possible to monitor the status of the translationJob. When the translationJob’s state has been changed to Translated, you can get all translationUnits of this specific translationJob. You could, fo example, fetch the status periodically every 5 minutes until the translation is finished.

Option 2: Awaiting Webhook

In this scenario we would send a Webhook to an API endpoint provided by you.
The POST payload looks like this:

    "jobId": "c4defabc-1301-4297-8715-8fdfbc0b716a",
    "projectDefinitionId": "33BA86CD-D0DD-4B92-DCF9-08D9DCD21C67",
    "webhookEvent": "TranslationJob_Delivered"

The pre-defined secret is included in the request header “X-Secret”. Please check this secret before starting any action!

After receiving this webhook, you can poll the results once.