NAV Navbar
Linux Windows
  • Getting started with SDL MT Cloud
  • Authentication
  • Subscriptions info
  • Asynchronous Translation
  • Asynchronous Language Identification
  • Account Management
  • User Management
  • Dictionary Management
  • Dictionary Terms Management
  • Brands Management
  • Input Formats
  • Language Codes
  • Script Codes
  • Error codes and messages
  • Deprecated Endpoints
  • Getting started with SDL MT Cloud

    In order to create an asynchronous translation you should follow the next steps. We strongly suggest that when you make any API call, you include a request identifier in the header called Trace-ID which is a unique request identifier (UUID) so that if there are any issues with your API calls we will be able to trace them in our system. The Trace-ID header is described in the below API calls and should be unique per request.

    Step 1: Authenticate

    Before you are able to use any of the Cloud MT API calls you need to authenticate. By providing either a username and a password or a client id and a client secret. For username/password authentcation happens using the /v4/token/user endpoint as decribed here For clientid/clientsecret authentication happens using the /v4/token endpoint as described here section. Authentication requests are handled using the OAuth 2.0 Authorization Framework.

    Once you authenticate you will get back an access token. The Access Token will be added to the Authorization header of all API requests in the form "Authorization": "Bearer asd0eXAi..."

    Step 2: Create a translation


    Also, check what is the input format that matches your input type by checking the input formats section. Please note that for text translation only a subset of the input formats are available as described in the Asynchronous text translation section.
    Note: Providing the wrong input format for your input will result in a erroneous translation.

    Step 3: Check the translation status

    Use this call to check what is the status of your translation by providing your requestId as described in the check the translation status section
    The translation status can be: INIT, TRANSLATING, DONE, FAILED. If the status is INIT or TRANSLATING you'll have to keep calling the check translation status endpoint until the translation has the status DONE or FAILED

    You need to set a sleep time between the subsequent calls made to the status endpoint /v4/mt/translations/async/{requestId} which should vary from 100 milliseconds for smaller inputs (up to 500 characters) to 500 milliseconds for larger inputs.
    If the returned translation status is DONE then check the next step to see how to retrieve your translation.
    If the returned translation status is FAILED then the translation process encountered some issues and the translation needs to be submitted again. If you get status FAILED more than two times in a row then the translation for that input will most likely not work and you should contact support.

    Step 4: Retrieve the translated content

    Use this call to retrieve the translated content of your request. For this you will need to call the /v4/mt/translations/async/{requestId}/content endpoint as described in both the text translation and the file translation sections.
    For text translation you will get back a JSON and in the translation element you will get back the translated text.
    For file translation you will get back the binary content of the translated file.

    Authentication

    Token Request with API credentials

    The purpose of this call is to authenticate our clients and return an Access Token which will be used for further calls to the API. The token is now valid by default for 24 since it was first issued. The expiresAt property is the one that will provide accurate information about when the token will expire. After that, in order to make API calls, the user will have to ask for a new token. This call should be used by integrators to allow their apps to use MT Cloud. This allows the integrations to make calls without a user context. This Access Token will be added to the Authorization header of all API requests in the form "Authorization": "Bearer asd0eXAi..."

    curl -XPOST -H "Content-type: application/json" -d '{
        "clientId": "F0ZUe28HFE8eaMLRLGJrIK0M6WGI92Nu",
        "clientSecret": "HFE8etNdtUP1liTrIKCtvlbGZ8Bv6Sxb-TAO_etNdHEcbWGu0KPGkVIu4QjiNEBt"
    }' '"sdl-mt-api-root-url"/v4/token'
    
    curl -XPOST -H "Content-type: application/json" -d ^
    "{^
     \"clientId\":\"F0ZUe28HFE8eaMLRLGJrIK0M6WGI92Nu\",^
     \"clientSecret\":\"HFE8etNdtUP1liTrIKCtvlbGZ8Bv6Sxb-TAO_etNdHEcbWGu0KPGkVIu4QjiNEBt\"^
    }" "sdl-mt-api-root-url"/v4/token
    

    HTTP Request
    POST /v4/token

    Request Parameters



    Request JSON:

    {
        "clientId": "F0ZUe28HFE8eaMLRLGJrIK0M6WGI92Nu",
        "clientSecret": "HFE8etNdtUP1liTrIKCtvlbGZ8Bv6Sxb-TAO_etNdHEcbWGu0KPGkVIu4QjiNEBt"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    clientId string yes The clientId associated with the account
    clientSecret string yes The client secret for this clientId



    Response JSON:

    {
    "accessToken": "asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI",
    "validityInSeconds": 86400,
    "tokenType": "Bearer",
    "expiresAt": 1538505336000
    }
    

    Response

    Format
    JSON

    Name Type Description
    accessToken string Valid access token in JSON Web Token (JWT) format
    validityInSeconds integer The time the token is valid
    tokenType string Bearer
    expiresAt long A timestamp (epoch) representing the expiration time of the token



    Error JSON:

    {
       "errors":[
          {
             "code":54,
             "description":"Unable to generate the access token. Verify your credentials and try again."
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the token is successfully generated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    500 Application internal error





    Token Request with user credentials

    The purpose of this call is to authenticate our clients and return an Access Token which will be used for further calls to the API. The token is now valid by default for 24 hrs. After that, in order to make API calls, the user will have to ask for a new token. This call should be used by integrators who need to make calls with the user's credentials. This Access Token will be added to the Authorization header of all API requests in the form "Authorization": "Bearer asd0eXAi..."

    curl -XPOST -H "Content-type: application/json" -d '{
        "username": "beglobal@sdl.com",
        "password": "beglobal"
    }' '"sdl-mt-api-root-url"/v4/token/user'
    
    curl -XPOST -H "Content-type: application/json" -d ^
    "{^
     \"username\":\"beglobal@sdl.com\",^
     \"password\":\"beglobal\"^
    }" "sdl-mt-api-root-url"/v4/token/user
    

    HTTP Request
    POST /v4/token/user

    Request Parameters



    Request JSON:

    {
        "username": "beglobal@sdl.com",
        "password": "beglobal"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    username string yes User's email address
    password string yes User's password



    Response JSON:

    {
    "accessToken": "asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI",
    "validityInSeconds": 86400,
    "tokenType": "Bearer",
    "expiresAt": 1538505336000
    }
    

    Response

    Format
    JSON

    Name Type Description
    accessToken string Valid access token in JSON Web Token (JWT) format
    validityInSeconds integer The time the token is valid
    tokenType string Bearer
    expiresAt long A timestamp (epoch) representing the expiration time of the token



    Error JSON:

    {
       "errors":[
          {
             "code":54,
             "description":"Unable to generate the access token. Verify your credentials and try again."
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the token is successfully generated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    500 Application internal error





    Subscriptions info

    The purpose of this endpoint is to enable retrieving information about subscriptions. The call has to be made in the context of an account.

    Get all active language pairs from all active subscriptions

    This call should be used to retrieve information about all active language pairs form all active subscriptions of the specified account. You need to provide your account id.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/subscriptions/language-pairs'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/subscriptions/language-pairs
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/accounts/{accountId}/subscriptions/language-pairs

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    
    {
      "accountId": 2,
      "endDate": "2025/05/18",
      "languagePairs": [
        {
            "name": "engita_generic",
            "active": "yes",
            "displayName": "Generic",
            "sourceLanguageId": "eng",
            "targetLanguageId": "ita",
            "model": "generic"
        },
        {
            "name": "engspa_custom",
            "active": "yes",
            "displayName": "Custom",
            "sourceLanguageId": "eng",
            "targetLanguageId": "spa",
            "model": "custom"
        }
      ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer The account id for which subscriptions were requested
    endDate string The expire date of the current subscription
    languagePairs list The language pairs list
    name string Language pair name
    displayName string Display Name used in BeGlobal UI
    sourceLanguageId string Three letters language code of the source language
    targetLanguageId string Three letters language code of the target language
    model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)
    {
        "errors": [{
            "code": 1002,
            "description": "account with id 12 does not exist"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When all account language pairs are successfully returned
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get subscription

    This call should be used to retrieve information about the subscription. You need to provide the subscription id for which you want the info.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/subscriptions/123'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/subscriptions/123
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    GET /v4/accounts/{accountId}/subscriptions/{subscriptionId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "id": 123,
       "accountId": 12,
       "description ": "description of the subscription",
       "startDate": "2018/05/19",
       "endDate": "2019/05/18",
       "active": "yes",
       "languagePairs": [
            {
                "name": "engfra_custom",
                "active": "yes",
                "displayName": "Custom",
                "sourceLanguageId": "eng",
                "targetLanguageId": "fra",
                "model": "custom"
            },
            {
                "name": "engger_custom",
                "active": "yes",
                "displayName": "Custom",
                "sourceLanguageId": "eng",
                "targetLanguageId": "ger",
                "model": "custom"
            }
        ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    id integer Unique numeric identifier for the subscription
    accountId integer Unique numeric identifier for the account associated to the subscription
    description string A brief description of the subscription
    startDate string Start date of the subscription validity
    endDate string End date of the subscription validity
    active string Subscription State
    languagePairs list The language pairs list
    name string Language pair name
    displayName string Display Name used in BeGlobal UI
    sourceLanguageId string Three letters language code of the source language
    targetLanguageId string Three letters language code of the target language
    model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the subscription is returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get all subscriptions for the account

    This call should be used to retrieve information about all the subscriptions of the specified account.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/{accountId}/subscriptions'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/{accountId}/subscriptions
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    GET /v4/accounts/{accountId}/subscriptions?pageNumber={pageNumber}&pageSize={pageSize}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters

    Name Type Mandatory Default value Description
    pageNumber int no 1 Integer specifying the requested page number
    pageSize int no 10 Integer specifying the requested page size, limited to 100



    Response JSON:

    {
       "accountId": 12,
       "totalCount": 11,
       "pageNumber": 1,
       "pageSize": 2,
       "subscriptions": [
        {
           "id": 452,
           "accountId": 12,
           "description ": "description of the subscription",
           "startDate": "2018/05/19",
           "endDate": "2019/05/18",
           "active": "yes",
           "languagePairs": [
                {
                    "name": "engfra_custom",
                    "active": "yes",
                    "displayName": "Custom",
                    "sourceLanguageId": "eng",
                    "targetLanguageId": "fra",
                    "model": "custom"
                },
                {
                    "name": "engger_custom",
                    "active": "yes",
                    "displayName": "Custom",
                    "sourceLanguageId": "eng",
                    "targetLanguageId": "ger",
                    "model": "custom"
                }
            ]
        },
        {
           "id": 452,
           "accountId": 12,
           "description ": "description of the subscription",
           "startDate": "2018/05/19",
           "endDate": "2019/06/18",
           "active": "yes",
           "languagePairs": [
                {
                    "name": "engita_generic",
                    "active": "yes",
                    "displayName": "Generic",
                    "sourceLanguageId": "eng",
                    "targetLanguageId": "ita",
                    "model": "generic"
                },
                {
                    "name": "engspa_custom",
                    "active": "yes",
                    "displayName": "Custom",
                    "sourceLanguageId": "eng",
                    "targetLanguageId": "spa",
                    "model": "custom"
                }
              ]
            }
          ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    totalCount integer Total number of subscriptions in account
    pageNumber integer Requested page number
    pageSize integer Requested page size
    subscriptions list The list of all subscriptions associated with the given accountId
    accountId integer Unique numeric identifier for the account associated to the subscriptions
    id integer Unique numeric identifier for the subscription
    description string A brief description of the subscription
    startDate string Start date of the subscriptions validity
    endDate string End date of the subscriptions validity
    active string Subscription State
    languagePairs list The language pairs list
    name string Language pair name
    displayName string Display Name used in BeGlobal UI
    sourceLanguageId string Three letters language code of the source language
    targetLanguageId string Three letters language code of the target language
    model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the subscriptions were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Asynchronous Translation

    The purpose of this flow is to be used for large text, file and resource translations. This flow has 3 steps for text and file translation.

    For the text and file translation the steps are:

    It is also possible to cancel an asynchronous translation while it is in progress.

    Asynchronous Text Translation

    1. Create the translation



    Translation Example:

    curl -X POST -H "Content-type: application/json" \
    -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -d '{"input":["Have a nice week!"],
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra",
    "model": "TravelVertical123",
    "inputFormat": "PLAIN",
    "translationMode": "quality",
    "dictionaries": ["0d967785-2857-46d7-9e10-4f6d1346db06", "717e47fa-0293-4898-b218-f948720f5321"]}' \
    "sdl-mt-api-root-url"/v4/mt/translations/async
    
    curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -d ^
    "{^
      \"sourceLanguageId\": \"eng\",^
      \"targetLanguageId\": \"fra\",^
      \"inputFormat\": \"PLAIN\",^
      \"model\": \"TravelVertical123\",^
      \"input\": [\"Have a nice week\"],^
      \"dictionaries\": [\"0d967785-2857-46d7-9e10-4f6d1346db06\", \"717e47fa-0293-4898-b218-f948720f5321\"]^
    }" "sdl-mt-api-root-url"/v4/mt/translations/async
    

    This call creates the translation by sending the input and the parameters as a JSON object.

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/mt/translations/async

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters

    Format
    JSON

    Name Type Mandatory Default value Description
    sourceLanguageId string yes Three letters language code of the source language or auto which signals that the source language should be auto detected
    targetLanguageId string yes Three letters language code of the target language
    model string no* See notes below a string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)
    submissionType string no text This can be: text
    inputFormat string no PLAIN Format of input content
    input* string yes Content to be translated
    dictionaries string array no empty A string array containing dictionary ids
    translationMode string no quality A string representing a translation mode. Currently we support two translation modes: "speed" and "quality". In “quality mode”, our algorithms perform an extended statistical search, which sometimes results in a better quality output. “Speed mode” is instead optimized towards returning a translation as fast as possible.

    Text Input formats

    Name Description
    HTML HTML
    PLAIN Plain text (UTF8)
    XLINE Plain text, one sentence per line
    TMX Translation Memory eXchange
    XLIFF XML Localization Interchange File Format
    BCM SDL Proprietary format
    XML Extensible Markup Language
    SDLXML Treats every closing XML tag in the input as the end of a segment. The XML format in contrast does not make this assumption.



    Request JSON:

    {
       "sourceLanguageId": "eng",
       "targetLanguageId": "fra",
       "model": "Custom021",
       "submissionType": "text",
       "inputFormat": "PLAIN",
       "translationMode": "quality",
       "input":[
          "Have a nice week!"
       ],
       "dictionaries": ["0d967785-2857-46d7-9e10-4f6d1346db06", "717e47fa-0293-4898-b218-f948720f5321"]
    }
    



    Response JSON:

    {
       "sourceLanguageId": "eng",
       "targetLanguageId": "fra",
       "model": "Custom021",
       "submissionType": "text",
       "inputFormat": "PLAIN",
       "requestId":"gfui83oah"
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    sourceLanguageId string Three letters language code of the given or the detected source language
    targetLanguageId string Three letters language code of the target language
    model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)
    inputFormat string Format of input
    submissionType string This can be: text
    requestId string The id of the translation request. This has to be used for the subsequent calls
    {
       "errors":[
          {
             "code":47,
             "description":"sourceLanguageId language is not code 3 format or auto. (was 5)"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the translation is successfully initiated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    2. Check the translation status

    This call will allow the user to check the status of a previously created translation. The translation status can be: INIT, TRANSLATING, DONE, FAILED. If the translation is DONE the content of the translation can be retrieved. If the translation is TRANSLATING then the status call has to be triggered again. If the translation is FAILED then it needs to be submitted again.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/mt/translations/async/{requestId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters

    Name Type Mandatory Default value Description
    includeProgressInfo boolean no false Boolean specifying if the translation progress must be included in the translation status response



    Response JSON:

    {
       "translationStatus":"TRANSLATING",
       "translationProgress": 42
    }
    
    {
        "translationStatus": "DONE",
        "inputFormat": "PLAIN",
        "outputFormat": "PLAIN",
        "translationStats": {
            "inputWordCount": 5,
            "inputCharCount": 26,
            "inputByteCount": 26,
            "translationWordCount": 5,
            "translationCharCount": 21,
            "translationByteCount": 22
        },
        "translationProgress": 100
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    translationStatus string A string representing the status of the translation.
    Can be one of the following
    INIT - source text was received by system and will be validated
    TRANSLATING - the translation process is in progress
    DONE - the translation was completed. When this status is returned then the Retrieve Content call should be triggered.
    FAILED - the translation failed. When this status is returned the Get Status calls should stop because there is no way to recover from this state.
    inputFormat string Format of input content
    outputFormat string Format of output content
    translationStats string Statistics about the translation
    inputWordCount int Number of input words in the source translated
    inputCharCount int Number of input characters in the source translated
    inputByteCount int Number of input bytes in the source translated
    translationWordCount int Number of output words in the source translated
    translationCharCount int Number of output characters in the source translated
    translationByteCount int Number of output bytes in the source translated
    translationProgress int Integer specifying the translation's progress. The value is populated based on includeProgressInfo query parameter value.
    {
        "errors": [{
            "code": 43,
            "description": "Unknown status for requestId {0}"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the translation status is successfully returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    3. Retrieve the translated content

    This call will allow the user to get the resulted translation.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah/content'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah/content
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/mt/translations/async/gfui83oah/content

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "sourceLanguageId": "eng",
       "targetLanguageId": "fra",
       "model": "TravelVertical021",
       "translation":[
          "Avoir une bonne semaine!"
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    sourceLanguageId string Three letters language code of the given or the detected source language
    targetLanguageId string Three letters language code of the target language
    model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)
    inputFormat string Format of input
    translation string array Array with the translated inputs
    {
        "errors": [{
            "code": 42,
            "description": "Invalid requestId {0}"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the translated content is successfully returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Asynchronous File Translation

    1. Create the translation

    This call creates the translation by sending the input and the parameters Multipart form data.

    curl -XPOST \
       -H "Content-Type:multipart/form-data" \
       -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" \
       -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" \
       -F "sourceLanguageId=eng" \
       -F "targetLanguageId=fra" \
       -F "model=generic" \
       -F "input=@\"./demo.txt\";filename=\"demo.txt\"" \
       -F "inputFormat=PLAIN" \
       -F "translationMode=quality" \
       -F "dictionaries=703e2693-704f-4588-8e9c-97799eeb75ae" \
       -F "dictionaries=ab783076-c9e0-4557-8f06-8be9055fa34c" \
     '"sdl-mt-api-root-url"/v4/mt/translations/async'
    
    curl -XPOST^
     -H "Content-Type:multipart/form-data"^
     -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI"^
     -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
     -F "sourceLanguageId=eng"^
     -F "targetLanguageId=fra"^
     -F "model=generic"^
     -F "input=@\"demo.txt\";filename=\"demo.txt\""^
     -F "inputFormat=PLAIN"^
     -F "translationMode=quality"^
     -F "dictionaries=703e2693-704f-4588-8e9c-97799eeb75ae"^
     -F "dictionaries=ab783076-c9e0-4557-8f06-8be9055fa34c"^
     "sdl-mt-api-root-url"/v4/mt/translations/async
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/mt/translations/async

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Request Body:

    (Request Body)
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="input"
    Content-Type: application/octet-stream
    Content-Length: 9
    
    doc 1
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="sourceLanguageId"
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 3
    
    eng
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="targetLanguageId"
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 3
    
    fra
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="model"
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 7
    
    generic
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="inputFormat"
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 10
    
    text/plain
    --8MsmExZ-SgFlDSniddeMZOkUV90emq--
    
    a5805422-7ed3-4702-bbf9-339e180dd280
    --8MsmExZ-SgFlDSniddeMZOkUV90emq--
    Content-Disposition: form-data; name="dictionaries"
    
    c215e1e6-8ccd-4f31-9acd-3c025976e907
    --8MsmExZ-SgFlDSniddeMZOkUV90emq--
    Content-Disposition: form-data; name="dictionaries"
    

    Request Parameters

    Format
    multipart/form-data

    Name Type Mandatory Default value Description
    sourceLanguageId string yes Three letters language code of the source language or auto which signals that the source language should be auto detected
    targetLanguageId string yes Three letters language code of the target language
    model string no* See notes below a string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)
    submissionType string no text This can be: text
    inputFormat string no PLAIN Format of input content. See Input Formats.
    input file yes The binary content of the file
    dictionaries string no empty A multi value parameter containing dictionary ids
    translationMode string no quality A string representing a translation mode. Currently we support two translation modes: "speed" and "quality". In “quality mode”, our algorithms perform an extended statistical search, which sometimes results in a better quality output. “Speed mode” is instead optimized towards returning a translation as fast as possible.



    Response JSON:

    {
       "sourceLanguageId": "eng",
       "targetLanguageId": "fra",
       "model": "TravelVertical021",
       "type": "resource",
       "inputFormat": "PDF",
       "requestId":"gfui83oah"
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    sourceLanguageId string Three letters language code of the given or the detected source language
    targetLanguageId string Three letters language code of the target language
    model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. TravelVertical123)
    inputFormat string Format of input content
    submissionType string This can be: text
    requestId string The id of the translation request. This has to be used for the subsequent calls
    {
       "errors":[
          {
             "code":47,
             "description":"sourceLanguageId language is not code 3 format or auto. (was 5)"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the translation is successfully initiated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    2. Check the translation status

    This call will allow the user to check the status of a previously created translation.The translation status can be: INIT, DONE, TRANSLATING, FAILED. If the translation is DONE the content of the translation can be retrieved. If the translation is TRANSLATING then the status call has to be triggered again. If the translation is FAILED then it needs to be submitted again.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/mt/translations/async/gfui83oah

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters



    Name Type Mandatory Default value Description
    includeProgressInfo boolean no false Boolean specifying if the translation progress must be included in the translation status response



    Response JSON:

    {
       "translationStatus":"TRANSLATING",
       "translationProgress": 42
    }
    
    {
        "translationStatus": "DONE",
        "inputFormat": "PLAIN",
        "outputFormat": "PLAIN",
        "translationStats": {
            "inputWordCount": 5,
            "inputCharCount": 26,
            "inputByteCount": 26,
            "translationWordCount": 5,
            "translationCharCount": 21,
            "translationByteCount": 22
        },
        "translationProgress": 100
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    translationStatus string A string representing the status of the translation.
    Can be one of the following
    INIT - input content was received by system and will be validated
    TRANSLATING - the translation process is in progress
    DONE - the translation was completed. When this status is returned then the Retrieve Content call should be triggered.
    FAILED - the translation failed. When this status is returned the Get Status calls should stop because there is no way to recover from this state.
    translationStats string Statistics about the translation
    inputFormat string Format of input content
    outputFormat string Format of output content
    inputWordCount int Number of input words in the source translated
    inputCharCount int Number of input characters in the source translated
    inputByteCount int Number of input bytes in the source translated
    translationWordCount int Number of output words in the source translated
    translationCharCount int Number of output characters in the source translated
    translationByteCount int Number of output bytes in the source translated
    translationProgress int Integer specifying the translation's progress. The value is populated based on includeProgressInfo query parameter value.
    {
        "errors": [{
            "code": 43,
            "description": "Unknown status for requestId {0}"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the translation status is successfully returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    3. Retrieve the translated content

    This call will allow the user to get the resulted translation.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah/content'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah/content
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/mt/translations/async/gfui83oah/content

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    BINARY

    The binary content of the translated file is returned.

    {
        "errors": [{
            "code": 42,
            "description": "Invalid requestId {0}"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the translated content is successfully returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Cancelling an Asynchronous Translation

    This call registers a cancellation request for a translation, by calling the endpoint described below. The translation cannot be cancelled if it is in one of the following states: DONE, FAILED. Call the Translation Status afterwards for confirmation.

    curl -XPOST \
       -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" \
       -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" \
     '"sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah/cancel'
    
    curl -XPOST^
     -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI"^
     -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
     "sdl-mt-api-root-url"/v4/mt/translations/async/gfui83oah/cancel
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/mt/translations/async/gfui83oah/cancel

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
      "requestId": "gfui83oah"
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    requestId string The id of the translation request
    {
       "errors":[
          {
             "code":63,
             "description":"Cannot cancel translation, status is already: DONE"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    202 When the cancel translation request has been registered
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Asynchronous Language Identification

    The purpose of this flow is to be used for large text, file and resource language identification. It consists of three steps:

    Asynchronous Text Language Identification

    1. Trigger language identification

    This call triggers the language identification by sending the input and the parameters as a JSON object.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
    "input": "A mountain is generally steeper than a hill"}, \
    "inputFormat": "PLAIN"}' \
    '"sdl-mt-api-root-url"/v4/multi-language-identification/async'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
     \"content\": \"A mountain is generally steeper than a hill\",^
     \"inputFormat\": \"PLAIN\"^
    }" "sdl-mt-api-root-url"/v4/multi-language-identification/async
    



    Request JSON:

    {
       "input": "A mountain is generally steeper than a hill",
       "inputFormat": "PLAIN"
    }
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/multi-language-identification/async

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters

    Format
    JSON

    Name Type Mandatory Default value Description
    input string yes The source text for which we want to identify the language.
    inputFormat string no PLAIN Format of input content

    Text Input formats

    Name Description
    HTML HTML
    PLAIN Plain text (UTF8)
    XLINE Plain text, one sentence per line
    TMX Translation Memory eXchange
    XLIFF XML Localization Interchange File Format
    BCM SDL Proprietary format
    XML Extensible Markup Language
    SDLXML Treats every closing XML tag in the input as the end of a segment. The XML format in contrast does not make this assumption.



    Response JSON:

    {
      "requestId": "80fe4962-be9e-11e9-b972-2a2ae2dbcce4"
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    requestId string The id of the language identification request. This has to be used for the subsequent calls.
    {
        "errors": [
          {
            "code": 1000,
            "description": "Failed to store language detection information"
          }
        ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 Language detection was successfully triggered
    400 Input data is not valid
    401 Authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    2. Check the status of language identification

    This call will allow the user to check the status of a previously triggered language detection. The status can be: INIT, IN_PROGRESS, DONE, FAILED.

    curl -GET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/multi-language-identification/async/{requestId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
      "status": "DONE"
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    status string The status of the language identification for given request identifier.
    Can be one of the following:
    INIT - source text was received by the system and will be validated
    IN_PROGRESS - the language detection is in progress
    DONE - the language detection is complete. When this status is returned, the retrieve result call should be triggered.
    FAILED - the language identification failed. When this status is returned the GET status calls should stop because there is no way to recover from this state.
    {
        "status": "FAILED",
        "errors": [
          {
            "code": 41,
            "description": "Language detection failed"
          }
        ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    status string
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    When the language detection status is "FAILED" the response will contain also the failure reason.

    Returned HTTP Codes:

    Http Code Description
    200 Status was successfully retrieved
    400 Input data is not valid
    401 Authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    3. Retrieve the result of language identification

    This call will allow the caller to get the result of a triggered language identification, based on a request identifier.
    The result of the language identification is by default stored for 48 hours. In case the account's DELETE_CONTENT feature is enabled, the result of the language identification is deleted after its first successful retrieve.

    curl -GET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4/result'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4/result
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/multi-language-identification/async/{requestId}/result

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
      "encoding": "utf8",
      "languages": [
        {
          "code": "eng",
          "name": "English",
          "languageTag": "en",
          "score": 0.99
        }
      ],
      "scripts": [
        {
          "code": "Latn",
          "name": "Latin",
          "percent": 80.6
        },
        {
          "code": "Zyyy",
          "name": "Common",
          "percent": 19.4
        }
      ]
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    encoding string Source content encoding
    languages array Array of detected languages, sorted in descending order of their score
    code string Detected language code (See Languages Table)
    languageTag string Detected language tag
    name string Detected language full name (See Languages Table)
    score float A value between 0 and 1; the closer the value is to 1, the greater the association between the detected language and source content
    scripts array Array of scripts that constitute the input text, sorted in descending order of the percentage of characters using that script.
    code string ISO-15924 code of detected script (See Script Codes)
    name string Name of detected script
    percent float Percentage of source content using specific script
    {
        "errors": [
          {
            "code": 61,
            "description": "result not found for requestId 80fe4962-be9e-11e9-b972-2a2ae2dbcce4"
          }
        ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 Result was successfully returned
    400 Input data is not valid
    401 Authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Asynchronous File Language Identification

    This call will allow the user to identify the source language of a given file input.

    curl -XPOST \
      -H "Content-Type:multipart/form-data" \
      -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" \
      -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" \
      -F "input=@\"./demo.txt\";filename=\"demo.txt\"" \
      -F "inputFormat=PLAIN" \
    '"sdl-mt-api-root-url"/v4/multi-language-identification/async'
    
    curl -XPOST^
     -H "Content-Type:multipart/form-data"^
     -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI"^
     -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
     -F "input=@\"demo.txt\";filename=\"demo.txt\""^
     -F "inputFormat=PLAIN"^
     "sdl-mt-api-root-url"/v4/multi-language-identification/async
    



    Request Body:

    (Request Body)
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="input"
    Content-Type: application/octet-stream
    Content-Length: 9
    
    doc 1
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="inputFormat"
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 10
    
    text/plain
    --8MsmExZ-SgFlDSniddeMZOkUV90emq--
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/multi-language-identification/async

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters

    Format
    multipart/form-data

    Name Type Mandatory Default value Description
    input file yes The binary content of the file
    inputFormat string no PLAIN Format of input content. See Input Formats.



    Response JSON:

    {
      "requestId": "80fe4962-be9e-11e9-b972-2a2ae2dbcce4"
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    requestId string The id of the language identification request. This has to be used for the subsequent calls.
    {
        "errors": [
          {
            "code": 1000,
            "description": "Failed to store language detection information"
          }
        ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 Language detection was successfully triggered
    400 Input data is not valid
    401 Authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    2. Check the status of language identification

    This call will allow the user to check the status of a previously triggered language detection. The status can be: INIT, IN_PROGRESS, DONE, FAILED.

    curl -GET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/multi-language-identification/async/{requestId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
      "status": "DONE"
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    status string The status of the language identification for given request identifier.
    Can be one of the following:
    INIT - input content was received by the system and will be validated
    IN_PROGRESS - the language detection is in progress
    DONE - the language detection is complete. When this status is returned, the retrieve result call should be triggered.
    FAILED - the language identification failed. When this status is returned the GET status calls should stop because there is no way to recover from this state.
    {
        "status": "FAILED",
        "errors": [
          {
            "code": 41,
            "description": "Language detection failed"
          }
        ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    status string
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    When the language detection status is "FAILED" the response will contain also the failure reason.

    Returned HTTP Codes:

    Http Code Description
    200 Status was successfully retrieved
    400 Input data is not valid
    401 Authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    3. Retrieve the result of language identification

    This call will allow the caller to get the result of a triggered language identification, based on a request identifier.
    The result of the language identification is by default stored for 48 hours. In case the account's DELETE_CONTENT feature is enabled, the result of the language identification is deleted after its first successful retrieve.

    curl -GET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4/result'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/multi-language-identification/async/80fe4962-be9e-11e9-b972-2a2ae2dbcce4/result
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/multi-language-identification/async/{requestId}/result

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
      "encoding": "utf8",
      "languages": [
        {
          "code": "eng",
          "name": "English",
          "languageTag": "en",
          "score": 0.99
        }
      ],
      "scripts": [
        {
          "code": "Latn",
          "name": "Latin",
          "percent": 80.6
        },
        {
          "code": "Zyyy",
          "name": "Common",
          "percent": 19.4
        }
      ]
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    encoding string Source content encoding
    languages array Array of detected languages, sorted in descending order of their score
    code string Detected language code (See Languages Table)
    languageTag string Detected language tag
    name string Detected language full name (See Languages Table)
    score float A value between 0 and 1; the closer the value is to 1, the greater the association between the detected language and source content
    scripts array Array of scripts that constitute the input text, sorted in descending order of the percentage of characters using that script.
    code string ISO-15924 code of detected script (See Script Codes)
    name string Name of detected script
    percent float Percentage of source content using specific script
    {
        "errors": [
          {
            "code": 61,
            "description": "result not found for requestId 80fe4962-be9e-11e9-b972-2a2ae2dbcce4"
          }
        ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 Result was successfully returned
    400 Input data is not valid
    401 Authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Account Management

    The purpose of this set of API calls is to enable account management from the API. Only users with special permissions will be able to call the Get and Update operations on accounts.

    Get account

    This call should be used to retrieve information about the account. You need to provide the account id for which you want the info.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    GET /v4/accounts/{accountId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "accountId": 12,
       "name": "SDL Demo Account",
       "active": "yes",
       "description": "production",
       "apiCredentials":[
          {
             "name":"Api credentials for account",
             "clientId":"fxzfNX91sdaReMDvjyjhTvkINI0",
             "clientSecret":"hts3QVQ7dscsadfYoAAXD7OMRqKCrxq0LhX2N8TBbmW0aPu6RXJu0ch",
             "active":"yes"
          }
       ],
        "accountSetting": {
            "accountCategory": "TRIAL",
            "accountCategoryFeatures": [
                {
                    "name": "API_KEYS",
                    "value": 5
                },
                {
                    "name": "CHARACTERS",
                    "value": 20000000000
                },
                {
                    "name": "CUSTOM_LPS",
                    "value": 10
                },
                {
                    "name": "DELETE_CONTENT",
                    "value": 0
                },
                {
                    "name": "DICTIONARIES",
                    "value": 200
                },
                {
                    "name": "GENERIC_LPS",
                    "value": 2147483647
                },
                {
                    "name": "USERS",
                    "value": 5000
                }
            ]
        }
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account
    name string Account name
    active string Account state
    description string Account description
    apiCredentials list The api credentials list
    clientId string The generated client id
    clientSecret string The generated client secret
    active string API Credentials state
    accountSetting object Contains the account category with its features information



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the account is returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get all users for the account

    This call should be used to retrieve a list with all the users for the account. You need to provide the account id for which you want the info. In addition to the account id you should provide a page (number) and a size (for the page) parameter. Both parameters are optional, but a default value will be set if not provided.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/users?pageNumber=1&pageSize=3'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/users?pageNumber=1&pageSize=3
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    GET /v4/accounts/{accountId}/users?pageNumber={pageNumber}&pageSize={pageSize}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters



    Name Type Mandatory Default value Description
    pageNumber int no 1 Integer specifying the requested page number
    pageSize int no 10 Integer specifying the requested page size, limited to 100



    Response JSON:

    {
       "totalCount": 3,
       "pageNumber": 1,
       "pageSize": 3,
       "accountId": 221,
       "users": [
            {
               "userId": 1,
               "firstName": "John",
               "middleName": "M",
               "lastName": "smith",
               "email": "jsmith@sdl.com",
               "userRole": "admin",
               "active": "yes"
            },
            {
               "userId": 2,
               "firstName": "David",
               "middleName": "M",
               "lastName": "Anderson",
               "email": "danderson@sdl.com",
               "userRole": "translator",
               "active": "yes"
            },
            {
               "userId": 3,
               "firstName": "Andrew",
               "middleName": "M",
               "lastName": "Jones",
               "email": "ajones@sdl.com",
               "userRole": "translator",
               "active": "no"
            }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account
    userId integer User ID in the system
    firstName string Users's first name
    middleName string Users's middle name
    lastName string Users's last name
    email string Users's email
    userRole string Users's role
    active string Users's state
    totalCount integer Total number of users in account
    pageNumber integer Requested page number
    pageSize integer Requested page size



    Error JSON:

    {
       "errors":[
          {
             "code":1003,
             "description":"No account was found"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the users were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Create API Credentials for Account

    This call is used to create a set of API credentials for the account. This will create a clientId and a clientSecret pair which can be used to authenticate apps and get tokens as presented in the Get Token With API Credentials call.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "name": "SDL Demo Account",
       "active": "yes",
       "description": "production"
    }' '"sdl-mt-api-root-url"/v4/accounts/1/api-credentials'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
     \"name\": \"SDL Demo Account\",^
     \"active\": \"yes\",^
     \"description\": \"production\"^
    }" "sdl-mt-api-root-url"/v4/accounts/1/api-credentials
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    PUT /v4/accounts/{accountId}/api-credentials

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "name": "SDL Demo Account",
       "active": "yes",
       "description": "production"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    name string yes String specifying the api credentials name
    active string no yes [yes/no] specify if the account is active or inactive



    Response JSON:

    
    {
       "name":"SDL Demo Account",
       "active":"yes",
       "description":"production",
       "accountId":1,
       "apiCredentials":[
          {
             "name":"Api credentials for account",
             "clientId":"fxzfNX91sdaReMDvjyjhTvkINI0",
             "clientSecret":"hts3QVQ7dscsadfYoAAXD7OMRqKCrxq0LhX2N8TBbmW0aPu6RXJu0ch",
             "active":"yes"
          }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    name string The name of the API Credentials
    clientId string The generated client id
    clientSecret string The generated client secret
    active string API Credentials state



    Error JSON:

    {
       "errors":[
          {
             "code":1015,
             "description":"Cannot create api credentials with name API DEMO for account 1"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the api credentials are successfully created
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Update API Credentials for Account

    This call is used to update a set of API credentials for the account. The name and the active state of the credentials can be changed.

    curl -XPUT -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "name": "SDL Demo Credentials",
       "active": "yes"
    }' '"sdl-mt-api-root-url"/v4/accounts/1/api-credentials/fxzfNX91sdaReMDvjyjhTvkINI0'
    
    curl -XPUT -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
     \"name\": \"SDL Demo Credentials\",^
     \"active\": \"yes\"^
    }" "sdl-mt-api-root-url"/v4/accounts/1/api-credentials/fxzfNX91sdaReMDvjyjhTvkINI0
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    PUT /v4/accounts/{accountId}/api-credentials/{clientId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "name": "SDL Demo Account",
       "active": "yes",
       "description": "production"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    name string yes String specifying the api credentials name
    active string no yes [yes/no] specify if the account is active or inactive



    Response JSON:

    
    {
       "name":"SDL Demo Account",
       "active":"yes",
       "description":"production",
       "accountId":1,
       "apiCredentials":[
          {
             "name":"Api credentials for account",
             "clientId":"fxzfNX91sdaReMDvjyjhTvkINI0",
             "clientSecret":"hts3QVQ7dscsadfYoAAXD7OMRqKCrxq0LhX2N8TBbmW0aPu6RXJu0ch",
             "active":"yes"
          }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    name string The name of the API Credentials
    clientId string The generated client id
    clientSecret string The generated client secret
    active string API Credentials state



    Error JSON:

    {
       "errors":[
          {
             "code":1015,
             "description":"Cannot create api credentials with name API DEMO for account 1"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the api credentials are successfully updated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Delete API Credentials for Account

    This call is used to delete API credentials of an account. You need to provide a valid accountId and clientId to be able to delete the API credentials.

    curl -XDELETE -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d
    '"sdl-mt-api-root-url"/v4/accounts/1/api-credentials/fxzfNX91sdaReMDvjyjhTvkINI0'
    
    curl -XDELETE -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Content-type: application/json" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -d ^
     "sdl-mt-api-root-url"/v4/accounts/1/api-credentials/fxzfNX91sdaReMDvjyjhTvkINI0
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    PUT /v4/accounts/{accountId}/api-credentials/{clientId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    When the API credeantials are deleted successfully no content is returned

    Error Response



    Error JSON:

    {
       "errors":[
          {
             "code":1015,
             "description":"Cannot delete api credentials with name API DEMO for account 1"
          }
       ]
    }
    

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the api credentials are successfully deleted
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Regenerate API Credentials Secret for Account

    This call is used to regenerate secret for API credentials of an account. You need to provide a valid accountId and clientId to be able to regenerate the API credentials secret.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d
    '"sdl-mt-api-root-url"/v4/accounts/1/api-credentials/fxzfNX91sdaReMDvjyjhTvkINI0/secret'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Content-type: application/json" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -d ^
     "sdl-mt-api-root-url"/v4/accounts/1/api-credentials/fxzfNX91sdaReMDvjyjhTvkINI0/secret
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    POST /v4/accounts/{accountId}/api-credentials/{clientId}/secret

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    
    {
       "name":"SDL Demo Account",
       "active":"yes",
       "description":"production",
       "accountId":1,
       "apiCredentials":[
          {
             "name":"Api credentials for account",
             "clientId":"fxzfNX91sdaReMDvjyjhTvkINI0",
             "clientSecret":"qKCrxq0LhX2N8TBbhts3QVQ7dscsadfYoAAXD7OMRmW0aPu6RXJu0ch",
             "active":"yes"
          }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    name string The name of the API Credentials
    clientId string The generated client id
    clientSecret string The generated client secret
    active string API Credentials state

    Error Response



    Error JSON:

    {
       "errors":[
          {
             "code":1020,
             "description":"Cannot regenerate api credentials secret for clientId: fxzfNX91sdaReMDvjyjhTvkINI0 for account 1"
          }
       ]
    }
    

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    201 When the api credentials secret is successfully regenerated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get API Credentials self

    This call should be used to retrieve information about the credentials.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/api-credentials/self'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/api-credentials/self
    

    Access token type
    API credentials

    HTTP Request
    GET /v4/accounts/api-credentials/self

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "accountId": 12,
       "clientId":"fxzfNX91sdaReMDvjyjhTvkINI0"
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account
    clientId string Unique identifier for API Credentials



    Error JSON:

    {
       "errors":[
          {
             "code": 55,
             "description": "Invalid access token. The Token has expired."
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the API credentials are returned
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get Domain Wildcards for Account

    This call should be used to retrieve information about the domain wildcards of an account.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/1/domain-wildcards'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/1/domain-wildcards
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    GET /v4/accounts/{accountId}/domain-wildcards

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "accountId":1,
       "domainWildcards": [
            {
                "domainName": "sdl.com"
            }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account
    domainName string Wildcard used to create federated users



    Error JSON:

    {
       "errors":[
          {
             "code": 55,
             "description": "Invalid access token. The Token has expired."
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the domain wildcards for the account is returned
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Create Domain Wildcards for Account

    This call should be used to create a new domain wildcards of an account.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "domainName": "domain.com"
    }'
    '"sdl-mt-api-root-url"/v4/accounts/1/domain-wildcards'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
      \"domainName\": \"domain.com\"^
    }" "sdl-mt-api-root-url"/v4/accounts/1/domain-wildcards
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    POST /v4/accounts/{accountId}/domain-wildcards

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "domainName": "domain.com"
    }
    

    Format
    JSON

    Name Type Mandatory Default Value Description
    domainName string yes String specifying the domain wildcard used to create new users



    Response JSON:

    {
       "accountId":1,
       "domainWildcards": [
            {
                "domainName": "sdl.com",
                "active": "yes"
            },
            {
                "domainName": "domain.com",
                "active": "yes"
            }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account
    domainName string Wildcard used to create federated users
    active string Domain Wildcards state



    Error JSON:

    {
       "errors":[
          {
             "code": 55,
             "description": "Invalid access token. The Token has expired."
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the domain wildcards for the account is created
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Delete Domain Wildcards for Account

    This call should be used to delete a domain wildcard from an account.

    curl -XDELETE -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" \
    '"sdl-mt-api-root-url"/v4/accounts/1/domain-wildcards/domain.com'
    
    curl -XDELETE -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" ^
     "sdl-mt-api-root-url"/v4/accounts/1/domain-wildcards/domain.com
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    DELETE /v4/accounts/{accountId}/domain-wildcards/{domainWildcard}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    When the Domain Wildcard is deleted successfully no content is returned.



    Error JSON:

    {
       "errors":[
          {
             "code": 55,
             "description": "Invalid access token. The Token has expired."
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the domain wildcards for the account is deleted
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error





    User Management

    The purpose of this set of API calls is to enable user management from the API perspective. They include CRUD operations on users. Each user call has to be made in the context of an account. No user can exist without an associated account. Each user has an associated role.

    User Roles

    Role Translate Create User Update User Get User Information Delete User Get Account Info Update Account Info
    Admin Yes Yes Yes Yes Yes Yes Yes
    Linguist Yes No Yes (self) Yes (self info) No No No
    Translator Yes No Yes (self) Yes (self info) No No No

    Create user

    This call creates a new user within the system. The user will be part of the same account as the Admin that creates it. When a new user is created there are two possible scenarios. 1. The user has an identity created with SDL ID in which case it can start using BeGlobal right away using his SDL ID credentials. (email and password) 2. The user does not have an identity created with SDL ID. In this case a new identity will be created and the user will receive a confirmation email and an email with a request to update his password. The update needs to happen otherwise the user will not be able to use the system.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "firstName": "John",
       "middleName": "M",
       "lastName": "Smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/users'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
      \"firstName\": \"John\",^
      \"middleName\": \"M\",^
      \"lastName\": \"Smith\",^
      \"email\": \"jsmith@mail.com\",^
      \"userRole\": \"translator\",^
      \"active\": \"yes\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/users
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    POST /v4/accounts/{accountId}/users

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "firstName": "John",
       "middleName": "M",
       "lastName": "smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    firstName string yes String specifying the first name of the user
    middleName string no Empty string String specifying the middle name of the user
    lastName string yes String specifying the last name of the user
    email string yes User's email. This has to be valid. It will be used for login
    userRole string no Translator The role that the user has.
    active string no [no] [yes/no]



    Response JSON:

    {
       "userId": 123,
       "firstName": "John",
       "middleName": "M",
       "lastName": "smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes",
       "accountId": 12
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    userId integer Unique numeric identifier for the user
    firstName string User's first name
    middleName string User's middle name
    lastName string User's last name
    email string User's email
    userRole string User's role
    active string Users active state
    accountId integer Unique numeric identifier for the user's account



    Error JSON:

    {
       "errors":[
          {
             "code":1005,
             "description":"Role: Wrong does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the user is successfully created
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get user

    This call should be used to retrieve information about the user. You need to provide the user id for which you want the info.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/users/123'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/users/123
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    GET /v4/accounts/{accountId}/users/{userId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "userId": 123,
       "firstName": "John",
       "middleName": "M",
       "lastName": "smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes",
       "accountId": 12
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    userId integer Unique numeric identifier for the user
    firstName string User's first name
    middleName string User's middle name
    lastName string User's last name
    email string User's email
    userRole string User's role
    active string Users active state
    accountId integer Unique numeric identifier for the user's account



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the user is returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get user self information

    This call should be used to retrieve information about the logged in (current) user.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/users/self'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/users/self
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    GET /v4/accounts/users/self

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "userId": 123,
       "firstName": "John",
       "middleName": "M",
       "lastName": "smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes",
       "accountId": 12,
       "accountCategory": "TRIAL",
       "eulaAccepted": "yes",
       "allowChangePassword": true,
       "deleteContentEnabled": true
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    userId integer Unique numeric identifier for the user
    firstName string User's first name
    middleName string User's middle name
    lastName string User's last name
    email string User's email
    userRole string User's role
    active string Users active state
    accountId integer Unique numeric identifier for the user's account
    accountCategory string Category name of the user's account
    eulaAccepted string EULA agreement was accepted
    allowChangePassword boolean Is the user allowed to change his password
    deleteContentEnabled boolean Is the content deleted after translation was retrieved

    Returned HTTP Codes:

    Http Code Description
    200 When the user is returned
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error



    Error JSON:

    {
       "errors":[
          {
             "code":55,
             "description": "Invalid access token. The Token has expired."
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the user is returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Update user

    This call is used to update an existing user within the system. You need to provide the user id for which you want the update to happen. All user information needs to be provided. Partial updates are not allowed.

    curl -XPUT -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "firstName": "John",
       "middleName": "M",
       "lastName": "smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/users/12'
    
    curl -XPUT -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
     \"firstName\": \"John\",^
     \"middleName\": \"Mr\",^
     \"lastName\": \"smith\",^
     \"email\": \"jsmith@mail.com\",^
     \"userRole\": \"translator\",^
     \"active\": \"yes\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/users/12
    

    Access token type
    User credentials - Allowed User Roles: Admin*, Linguist**, Translator**

    *Admin - Allowed to update: firstName, middleName, lastName, userRole, active
    **Linguist, Translator - Allowed to update self information: firstName, middleName, lastName

    HTTP Request
    PUT /v4/accounts/{accountId}/users/{userId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "firstName": "John",
       "middleName": "M",
       "lastName": "smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    firstName string yes String specifying the first name of the user
    middleName string yes String specifying the middle name of the user
    lastName string yes String specifying the last name of the user
    email string yes User's email. This has to be valid. It will be used for login
    userRole string yes The role that the user has.
    active string yes [yes/no]



    Response JSON:

    {
       "userId": 123,
       "firstName": "John",
       "middleName": "M",
       "lastName": "smith",
       "email": "jsmith@sdl.com",
       "userRole": "translator",
       "active": "yes",
       "accountId": 12
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    userId integer Unique numeric identifier for the user
    firstName string User's first name
    middleName string User's middle name
    lastName string User's last name
    email string User's email
    userRole string User's role
    active string Users active state
    accountId integer Unique numeric identifier for the user's account



    Error JSON:

    {
       "errors":[
          {
             "code":1005,
             "description":"Role: Wrong does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the user is successfully updated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Delete user

    This call is used to delete an existing user. The user id needs to be provided.

    curl -XDELETE -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" \
    '"sdl-mt-api-root-url"/v4/accounts/12/users/123'
    
    curl -XDELETE -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" ^
    "sdl-mt-api-root-url"/v4/accounts/12/users/123
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    DELETE /v4/accounts/{accountId}/users/{userId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    When the user is deleted successfully no content is returned



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"user with id 123 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the user is deleted
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Search users

    This call should be used to retrieve information about the users by providing a search term. Searching with an missing/empty search term will return all users in the system, similar to a get all users call. When providing a term, the value is searched in all fields of the user: Id, role, email, firstName, middleName, lastName. The search term can contain more than one word(delimited by spaces), which means a search will be performed for each word, trough all name fields(firstName, middleName, lastName) of the user. Ex: searchTerm="John Doe" will return users: User(middleName="John",lastName="Doe"), User(firstName="Doe",lastName="John"), etc... In addition, you should provide a page number and a page size parameter. Both parameters are optional, but a default value will be set.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'content-type: application/json' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -d '{
        "searchTerm":"123"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/users/search'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "content-type: application/json" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -d ^
    "{^
      \"searchTerm\": \"123\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/users/search
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    POST /v4/accounts/{accountId}/users/search?pageNumber={pageNumber}&pageSize={pageSize}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters

    Name Type Mandatory Default value Description
    pageNumber int no 1 Integer specifying the requested page number
    pageSize int no 10 Integer specifying the requested page size, limited to 100

    Request Parameters



    Request JSON:

    {
       "searchTerm":"123"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    searchTerm string no Empty string String used for search in users (case insensitive).



    Response JSON:

    {
        "totalCount": 1,
        "pageNumber": 1,
        "pageSize": 10,
        "accountId": 4,
        "users": [
        {
            "firstName": "John",
            "middleName": "M",
            "lastName": "Doe",
            "email": "jsmith@sdl.com",
            "userRole": "translator",
            "active": "yes",
            "userId": 123
        }]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the user's account
    totalCount integer Total number of users matched by the search in the specified account
    pageNumber integer Requested page number
    pageSize integer Requested page size
    users list List of users
    userId integer Unique numeric identifier for the user
    firstName string User's first name
    middleName string User's middle name
    lastName string User's last name
    email string User's email
    userRole string User's role
    active string Users active state



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the users were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error





    Dictionary Management

    The purpose of this set of API calls is to enable dictionary management from the API perspective. They will allow users to create a dictionary, add terms to an existing dictionary and manage dictionaries.

    Create dictionary

    This call creates a new dictionary within a specific account

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "name": "dictionary",
       "description": "first dictionary",
       "source": "eng",
       "target": "dut"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
      \"name\": \"dictionary\",^
      \"description\": \"first dictionary\",^
      \"lastName\": \"Smith\",^
      \"source\": \"eng\",^
      \"target\": \"dut\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/dictionaries
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    POST /v4/accounts/{accountId}/dictionaries

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "name": "dictionary",
       "description": "first dictionary",
       "source": "eng",
       "target": "dut"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    name string yes String specifying the name of the dictionary. Must be unique within the account.
    description string no Empty string String specifying a description for the dictionary.
    source string yes Three letters language code of the source language for the dictionary.
    target string yes Three letters language code of the target language for the dictionary.



    Response JSON:

    {
       "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
       "name": "dictionary",
       "description": "first dictionary",
       "source": "eng",
       "target": "dut"
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    dictionaryId string Unique string identifier for the dictionary
    accountId integer Unique numeric identifier for the account associated to the dictionary
    name string Name of the dictionary
    description string Description for the dictionary.
    source string Three letters language code of the source language for the dictionary
    target string Three letters language code of the target language for the dictionary



    Error JSON:

    {
       "errors":[
          {
             "code":1025,
             "description":"dictionary with name: ... already exists"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the dictionary is successfully created
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get dictionary

    This call should be used to retrieve information about the dictionary. The dictionary id must be provided.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    GET /v4/accounts/{accountId}/dictionaries/{dictionaryId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
       "name": "dictionary",
       "description": "first dictionary",
       "source": "eng",
       "target": "dut",
       "accountId": 12
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    dictionaryId string Unique string identifier for the dictionary
    accountId integer Unique numeric identifier for the account associated to the dictionary
    name string Name of the dictionary
    description string Description for the dictionary.
    source string Three letters language code of the source language for the dictionary
    target string Three letters language code of the target language for the dictionary



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the dictionary is returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Update dictionary

    This call is used to update an existing dictionary. You need to provide the dictionary id. All dictionary information needs to be provided. Partial updates are not allowed.

    curl -XPUT -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
       "name": "dictionary",
       "description": "first dictionary",
       "source": "eng",
       "target": "dut"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442'
    
    curl -XPUT -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
     \"name\": \"dictionary\",^
     \"description\": \"first dictionary\",^
     \"source\": \"eng\",^
     \"target\": \"dut\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    PUT /v4/accounts/{accountId}/dictionaries/{dictionaryId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "name": "dictionary",
       "description": "first dictionary",
       "source": "eng",
       "target": "dut"
    }
    

    Format
    JSON

    Name Type Description
    name string Name of the dictionary
    description string Description for the dictionary.
    source string Three letters language code of the source language for the dictionary
    target string Three letters language code of the target language for the dictionary



    Response JSON:

    {
       "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
       "name": "dictionary",
       "description": "first dictionary",
       "source": "eng",
       "target": "dut",
       "accountId": 12
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    dictionaryId string Unique string identifier for the dictionary
    accountId integer Unique numeric identifier for the account associated to the dictionary
    name string Name of the dictionary
    description string Description for the dictionary.
    source string Three letters language code of the source language for the dictionary
    target string Three letters language code of the target language for the dictionary



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the dictionary is successfully updated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Delete dictionary

    This call is used to delete an existing dictionary. The dictionary id needs to be provided.

    curl -XDELETE -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" \
    '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442'
    
    curl -XDELETE -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" ^
    "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    DELETE /v4/accounts/{accountId}/dictionaries/{dictionaryId}

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    When the dictionary is deleted successfully, no content is returned.



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the dictionary is deleted
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get all dictionaries for the account

    This call should be used to retrieve information about all the dictionaries of the specified account. You need to provide the account id for which you want the info.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/dictionaries
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    GET /v4/accounts/{accountId}/dictionaries

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Response JSON:

    {
       "accountId": 2,
       "dictionaries": [
         {
           "name": "dictionary1",
           "description": "first dictionary",
           "source": "eng",
           "target": "dut",
           "dictionaryId": "0a1f42b3-c048-4965-8e9f-6ddf7bc8adf2",
           "createdBy": "dictionary.creator@sdl.com",
           "creationDate": "2019/12/03",
           "lastModifiedBy": "johnDoe@sdl.com",
           "lastModifyDate": "2019/12/23"
         },
         {
           "name": "dictionary2",
           "description": "second dictionary",
           "source": "eng",
           "target": "fra",
           "dictionaryId": "0ad805ee-3b87-479d-914e-a326eaabe5e4",
           "createdBy": "johnDoe@sdl.com",
           "creationDate": "2019/11/03",
           "lastModifiedBy": "johnDoe@sdl.com",
           "lastModifyDate": "2020/01/07"
         }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account associated to the dictionary
    dictionaryId string Unique string identifier for the dictionary
    name string Name of the dictionary
    description string Description for the dictionary.
    source string Three letters language code of the source language for the dictionary
    target string Three letters language code of the target language for the dictionary
    createdBy string The email of the user who created the dictionary
    creationDate string Date when the dictionary was created
    lastModifiedBy string The email of the user who last modified the dictionary
    lastModifyDate string Date when the dictionary was last modified



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the dictionaries were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error





    Dictionary Terms Management

    The purpose of this set of API calls is to enable dictionary term management from the API perspective. They will allow users to manage terms for a specific dictionary.

    Create term

    This call creates a new term within a specific dictionary.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "source": "play",
       "target": "jouer",
       "comment": "english to french"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
      \"source\": \"play\",^
      \"target\": \"jouer\"^
      \"comment\": \"english to french\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    POST /v4/accounts/{accountId}/dictionaries/{dictionaryId}/terms

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "source": "play",
       "target": "jouer",
       "comment": "english to french"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    source string yes String specifying the source segment for dictionary item. Must be unique within the specified dictionary (case insensitive).
    target string yes String specifying the target segment for dictionary item.
    comment string no Empty string An optional comment about the term pair.



    Response JSON:

    {
       "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
       "accountId": 12,
       "source": "play",
       "target": "jouer",
       "comment": "english to french"
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    dictionaryId string Id of the dictionary
    accountId integer Unique numeric identifier for the account associated to the dictionary
    source string Source segment for dictionary item
    target string Target segment for dictionary item
    comment string Description for the term pair.



    Error JSON:

    {
       "errors":[
          {
             "code":1023,
             "description":"Term already exists: play"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the term is successfully created for the specified dictionary
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get all terms for a dictionary

    This call should be used to retrieve information about all the terms of a dictionary. You need to provide the account id and dictionary id as path params.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    GET /v4/accounts/{accountId}/dictionaries/{dictionaryId}/terms

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters

    Name Type Mandatory Default value Description
    pageNumber int no 1 Integer specifying the requested page number
    pageSize int no 10 Integer specifying the requested page size, limited to 100



    Response JSON:

    {
      "totalCount": 2,
      "pageSize": 10,
      "pageNumber": 1,
      "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
      "accountId": 12,
      "terms": [
           {
              "comment": "english to french",
              "source": "play",
              "target": "jouer"
           },
           {
              "comment": "other",
              "source": "leg",
              "target": "jambe"
           }
      ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    dictionaryId string Id of the dictionary
    accountId integer Unique numeric identifier for the account associated to the dictionary
    source string Source segment for dictionary item
    target string Target segment for dictionary item
    comment string Comment for the term.
    totalCount integer Total number of terms in the dictionary
    pageNumber integer Requested page number
    pageSize integer Requested page size



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the dictionary terms were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Update term

    This call is used to update a list of terms within a dictionary. The list with existing term sources to update and new terms values, needs to be provided in the json body. All source, target and comment need to be provided. Partial updates are not allowed.

    curl -XPUT -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "update": [
        {
         "currentTerm" : {
             "source": "play"
         },
         "updatedTerm" : {
            "source": "player",
            "target": "joueur",
            "comment": "comment"
         }
        }
       ]
    }' '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms'
    
    curl -XPUT -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
    "update": [^
        {^
        "\currentTerm\" : {^
           \"source\": \"play\"^
          },^
        "\currentTerm\" : {^
           \"source\": \"player\",^
           \"target\": \"joueur\",^
           \"comment\": \"comment\"^
          }^
         }^
         ]^
    }" "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    PUT /v4/accounts/{accountId}/dictionaries/{dictionaryId}/terms

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "update":[
          {
             "currentTerm":{
                "source":"play"
             },
             "updatedTerm":{
                "source":"player",
                "target":"joueur",
                "comment":"comment"
             }
          }
       ]
    }
    
    

    Format
    JSON

    Name Type Mandatory Default value Description
    update list yes List of terms to be updated
    currentTerm object yes Term to be updated
    source string yes String specifying the source segment for dictionary item to be updated
    updatedTerm object yes Term's new information
    source string yes String specifying the source segment for dictionary item. Must be unique within the specified dictionary (case insensitive).
    target string yes String specifying the target segment for dictionary item.
    comment string no Empty string An optional comment about the term pair.



    Response JSON:

    {
       "dictionaryId":"e8b01170-1bc4-4d61-89f7-fc2f65733442",
       "accountId":12,
       "terms":[
          {
             "source":"player",
             "target":"joueur",
             "comment":"comment"
          }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    dictionaryId string Id of the dictionary
    accountId integer Unique numeric identifier for the account associated to the dictionary
    source string Source segment for dictionary item
    target string Target segment for dictionary item
    comment string Description for the term pair.



    Error JSON:

    {
       "errors":[
          {
             "code":1023,
             "description":"Term not found: play"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the term is successfully updated for the specified dictionary
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Delete term

    This call is used to delete a list of terms within a dictionary. The terms sources to delete needs to be provided in the json body.

    curl -XPUT -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
        "delete": [
          {
            "source": "play"
          },
          {
            "source": "player"
          }
        ]
    }' '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms'
    
    curl -XPUT -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" ^
    "{^
        \"delete\": [^
          {^
            \"source\": \"play\"^
          },^
          {^
            \"source\": \"play\"^
          }^
        ]^
    }" "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    PUT /v4/accounts/{accountId}/dictionaries/{dictionaryId}/terms

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "delete":[
          {
             "source":"play"
          },
          {
             "source":"player"
          }
       ]
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    delete list yes List of terms to be deleted
    source string yes String specifying the source segment for dictionary item. Must be unique within the specified dictionary (case insensitive).

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    When the dictionary term is deleted successfully, no content is returned.



    Error JSON:

    {
       "errors":[
          {
              "code":1023,
              "description":"Term not found: play"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the term is deleted from the specified dictionary
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Search terms in a dictionary

    This call should be used to search specific terms in a dictionary. You need to provide the account id and dictionary id as path params.
    Also in the request body the search criteria can be specified, see below. The search matches by prefix of any property specified in the search criteria. If multiple properties are specified for search, a reunion for all matched terms will be provided (ex: source: "a" and target: "b" all terms with source prefix "a" and all terms with target prefix "b" will be returned).

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'content-type: application/json' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -d '{
        "source": "p",
        "target": "p",
        "comment": "p"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms/search'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "content-type: application/json" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "{^
      \"source\": \"p\",^
      \"target\": \"p\",^
      \"comment\": \"p\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms/search
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    POST /v4/accounts/{accountId}/dictionaries/{dictionaryId}/terms/search

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters

    Name Type Mandatory Default value Description
    pageNumber int no 1 Integer specifying the requested page number
    pageSize int no 10 Integer specifying the requested page size, limited to 100

    Request Parameters



    Request JSON:

    {
       "source": "p",
       "target": "p",
       "comment": "p"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    source string no Empty string String specifying the prefix of a source term for dictionary item (case insensitive).
    target string no Empty string String specifying the prefix of a target term for dictionary item (case insensitive).
    comment string no Empty string String specifying the prefix of the comment of dictionary item (case insensitive).



    Response JSON:

    {
      "totalCount": 2,
      "pageSize": 10,
      "pageNumber": 1,
      "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
      "accountId": 12,
      "terms": [
           {
              "comment": "english to french",
              "source": "play",
              "target": "jouer"
           },
           {
              "comment": "other",
              "source": "sometimes",
              "target": "parfois"
           }
      ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    dictionaryId string Id of the dictionary
    accountId integer Unique numeric identifier for the account associated to the dictionary
    source string Source segment for dictionary item
    target string Target segment for dictionary item
    comment string Comment for the term.
    totalCount integer Total number of terms matched by the search criteria in the specified dictionary
    pageNumber integer Requested page number
    pageSize integer Requested page size



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the dictionary terms were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Import dictionary

    This call is used to import all terms from a .xlsx file in a dictionary which already exists. You need to provide the account id and dictionary id. File will have the following structure: First populated line will be a header which contains source on first column, target on second column and comment on the third one --> | source | target | comment |

    After that, every line will contain source on first column, target on second one and comment on the third.

    - source and target are mandatory

    - comment is optional

    If the file contains any errors the import call will return the first 10 errors but all valid terms will be imported.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' \
       -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
       -H "Content-type: multipart/form-data" \
       -F 'content=@dictionary.xlsx' \
       -F overwriteDuplicates=true \
     '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms'
    
    curl -XPOST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhUk0TVRkQk5qZzRwczovL2F"^
        -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
        -H "Content-type: multipart/form-data"^
        -F "content=@\"dictionary.xlsx\""^
        -F "overwriteDuplicates=true"^
      "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    POST /v4/accounts/{accountId}/dictionaries/{dictionaryId}/terms

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters

    Format
    multipart/form-data

    Name Type Mandatory Default value Description
    overwriteDuplicates boolean no false Value specifying that imported elements with same source will overwrite or not old values
    content file yes The binary content of the file. If the imported file contains terms with duplicated source, the last one will be added to the dictionary with the rules specified by "overwriteDuplicates".

    Response



    Error JSON:

    {
       "errors":[
            {
                "code": 18,
                "description": "source from line 4 parameter is missing or is empty."
            },
            {
                "code": 1023,
                "description": "Term already exists: das"
            }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the terms are successfully imported in the specified dictionary
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Export dictionary

    This call should be used to retrieve in a file all the terms for the dictionary. You need to provide the account id and dictionary id for which you want the info.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms/export'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/dictionaries/e8b01170-1bc4-4d61-89f7-fc2f65733442/terms/export
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    GET /v4/accounts/{accountId}/dictionaries/{dictionaryId}/terms/export

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    BINARY

    The binary content of all terms for the dictionary. Binary should be converted to .xlsx



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the dictionary terms were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error





    Brands Management

    The purpose of this set of API calls is to enable brands management from the API perspective. They will allow users to manage brands for a specific account.

    Create brand

    This call creates a new brand within a specific account.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "source": "BrandName",
       "comment": "comment"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/brands'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
      \"source\": \"BrandName\",^
      \"comment\": \"comment\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/brands
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    POST /v4/accounts/{accountId}/brands

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "source": "BrandName",
       "comment": "comment"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    source string yes String specifying the name of the brand. Must be unique within the specified account (case insensitive).
    comment string no Empty string String specifying a description for the brand.



    Response JSON:

    {
       "accountId": 12,
       "source": "BrandName",
       "comment": "comment"
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account associated to the brand
    source string Name of the brand
    comment string Description for the brand.



    Error JSON:

    {
       "errors":[
          {
             "code":1023,
             "description":"Term already exists: BrandName"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the brand is successfully created
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Get all brands for the account

    This call should be used to retrieve information about all the brands of the specified account. You need to provide the account id for which you want the info as a path param.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/brands'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/brands
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    GET /v4/accounts/{accountId}/brands

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters

    Name Type Mandatory Default value Description
    pageNumber int no 1 Integer specifying the requested page number
    pageSize int no 10 Integer specifying the requested page size, limited to 100



    Response JSON:

    {
      "totalCount": 1,
      "pageSize": 10,
      "pageNumber": 1,
      "terms": [
        {
          "comment": "comment",
          "source": "BrandName"
        }
      ],
      "accountId": 12
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account associated to the brand
    source string Name of the brand
    comment string Description for the brand.
    totalCount integer Total number of brands in the account
    pageNumber integer Requested page number
    pageSize integer Requested page size



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the brands were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Update brand

    This call is used to update a list of brands in account. The existing brand sources to update and new brands values, needs to be provided in the json body. Both brand name and comment need to be provided. Partial updates are not allowed.

    curl -XPUT -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
       "update": [
        {
         "currentTerm" : {
             "source": "play"
         },
         "updatedTerm" : {
            "source": "player",
            "comment": "comment"
         }
        }
       ]
    }' '"sdl-mt-api-root-url"/v4/accounts/12/brands'
    
    curl -XPUT -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
    "update": [^
        {^
        "\currentTerm\" : {^
           \"source\": \"play\"^
          },^
        "\currentTerm\" : {^
           \"source\": \"player\",^
           \"comment\": \"comment\"^
          }^
         }^
         ]^
    }" "sdl-mt-api-root-url"/v4/accounts/12/brands
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    PUT /v4/accounts/{accountId}/brands

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "update":[
          {
             "currentTerm":{
                "source":"play"
             },
             "updatedTerm":{
                "source":"player",
                "comment":"comment"
             }
          }
       ]
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    update list yes List of brands to be updated
    currentTerm object yes Brand to be updated
    source string yes String specifying the source segment for brand to be updated
    updatedTerm object yes Brand's new information
    source string yes String specifying the name of the brand. Must be unique within the specified account (case insensitive).
    comment string no Empty string String specifying a description for the brand.



    Response JSON:

    {
       "dictionaryId": "e8b01170-1bc4-4d61-89f7-fc2f65733442",
       "accountId": 12,
       "terms":[
          {
          "source": "player",
          "comment": "comment"
          }
       ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account associated to the brand
    source string Name of the brand
    comment string Description for the brand.



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the brand is successfully updated
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Delete brand

    This call is used to delete a list of existing brands. The brands names needs to be provided in the json body.

    curl -XPUT -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{\
        "delete": [
           {
             "source": "play"
           },
           {
             "source": "player"
           }
         ]
    }' '"sdl-mt-api-root-url"/v4/accounts/12/brands'
    
    curl -XPUT -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" ^
    "{^
        \"delete\": [^
          {^
            \"source\": \"play\"^
          },^
          {^
            \"source\": \"play\"^
          }^
        ]^
    }" "sdl-mt-api-root-url"/v4/accounts/12/brands
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    PUT /v4/accounts/{accountId}/brands

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters



    Request JSON:

    {
       "delete":[
          {
             "source":"play"
          },
          {
             "source":"player"
          }
       ]
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    delete list yes List of brands to be deleted
    source string yes String specifying the name of the brand. Must be unique within the specified account (case insensitive).

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    When the brand is deleted successfully, no content is returned.



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the brand is deleted
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Delete all brands for the account

    This call is used to delete all brands for an account. The account id needs to be provided.

    curl -XDELETE -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" \
    '"sdl-mt-api-root-url"/v4/accounts/12/brands'
    
    curl -XDELETE -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" ^
    "sdl-mt-api-root-url"/v4/accounts/12/brands
    

    Access token type
    User credentials - Allowed User Roles: Admin

    HTTP Request
    DELETE /v4/accounts/{accountId}/brands

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    When the brands are deleted successfully no content is returned



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the brands are deleted
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Search brands in account

    This call should be used to search specific brands in account. You need to provide the account id as path params.
    Also in the request body the search criteria can be specified, see below. The search matches by prefix of any property specified in the search criteria. If multiple properties are specified for search, a reunion for all matched terms will be provided (ex: source: "a" and comment: "b" all terms with source prefix "a" and all terms with comment prefix "b" will be returned).

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'content-type: application/json' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -d '{
        "source": "p",
        "comment": "p"
    }' '"sdl-mt-api-root-url"/v4/accounts/12/brands/search'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "content-type: application/json"  -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
      \"source\": \"p\",^
      \"comment\": \"p\"^
    }" "sdl-mt-api-root-url"/v4/accounts/12/brands/search
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    POST /v4/accounts/{accountId}/brands/search

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Query Parameters

    Name Type Mandatory Default value Description
    pageNumber int no 1 Integer specifying the requested page number
    pageSize int no 10 Integer specifying the requested page size, limited to 100

    Request Parameters



    Request JSON:

    {
       "source": "p",
       "comment": "p"
    }
    

    Format
    JSON

    Name Type Mandatory Default value Description
    source string no Empty string String specifying the prefix of a source term for brand item (case insensitive).
    comment string no Empty string String specifying the prefix of the comment of brand item (case insensitive).



    Response JSON:

    {
      "totalCount": 2,
      "pageSize": 10,
      "pageNumber": 1,
      "accountId": 12,
      "terms": [
           {
              "comment": "english to french",
              "source": "play"
           },
           {
              "comment": "other",
              "source": "sometimes"
           }
      ]
    }
    

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    accountId integer Unique numeric identifier for the account associated to the brands
    terms list Brands list
    source string Source segment for the brand item
    comment string Comment for the brand item.
    totalCount integer Total number of terms matched by the search criteria in the specified dictionary
    pageNumber integer Requested page number
    pageSize integer Requested page size



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the brands were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Import brands

    This call is used to import brands from a .xlsx file. You need to provide the account id. File will have the following structure: First populated line will be a header which contains source on first column and comment on the second one --> | source | comment |

    After that, every line will contain source value on first column and comment value on the second.

    - source is mandatory

    - comment is optional

    If the file contains any errors the import call will return the first 10 errors but all valid terms will be imported.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' \
       -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
       -H "Content-type: multipart/form-data"  \
       -F 'content=@brands.xlsx' \
       -F overwriteDuplicates=true \
     '"sdl-mt-api-root-url"/v4/accounts/12/brands'
    
    curl -XPOST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhUk0TVRkQk5qZzRwczovL2F"^
        -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
        -H "Content-type: multipart/form-data"^
        -F "content=@\"brands.xlsx\""^
        -F "overwriteDuplicates=true"^
      "sdl-mt-api-root-url"/v4/accounts/12/brands
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist

    HTTP Request
    POST /v4/accounts/{accountId}/brands

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters

    Format
    multipart/form-data

    Name Type Mandatory Default value Description
    overwriteDuplicates boolean no false Value specifying that imported elements with same source will overwrite or not old values
    content file yes The binary content of the file. If the imported file contains terms with duplicated source, the last one will be added to the dictionary with the rules specified by "overwriteDuplicates".

    Response



    Error JSON:

    {
       "errors":[
            {
                "code": 18,
                "description": "source from line 4 parameter is missing or is empty."
            },
            {
                "code": 1023,
                "description": "Term already exists: das"
            }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    204 When the brands are successfully imported
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    Export brands

    This call should be used to retrieve in a file all the brands for the account. You need to provide the account id for which you want the info.

    curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
    '"sdl-mt-api-root-url"/v4/accounts/12/brands/export'
    
    curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
    "sdl-mt-api-root-url"/v4/accounts/12/brands/export
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator

    HTTP Request
    GET /v4/accounts/{accountId}/brands/export

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    BINARY

    The binary content of all brands for the account. Binary should be converted to .xlsx



    Error JSON:

    {
       "errors":[
          {
             "code":1002,
             "description":"account with id 12 does not exist"
          }
       ]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When brands for the account were returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error





    Input Formats

    Name File Extension MIME Type Description
    PLAIN .txt text/plain Plain text (UTF8)
    XLINE .xline text/x-line Plain text, one sentence per line
    HTML .htm, .html, .xhtml text/html HTML
    XML .xml text/xml XML
    SDLXML .sdlxml text/sdlxml Treats every closing XML tag in the input as the end of a segment. The XML format in contrast does not make this assumption.
    TMX .tmx text/x-tmx Translation Memory eXchange
    XLIFF .xliff application/x-xliff XML Localization Interchange File Format
    BCM .bcm application/x-json-bcm SDL Proprietary format
    PDF .pdf application/pdf Adobe Acrobat (PDF)
    RTF .rtf application/rtf Rich Text Format (RTF)
    DOCX .docx, .dotx, .docm, .dotm application/vnd.openxmlformats-officedocument.wordprocessingml.document Microsoft Word (Office Open XML)
    XLSX .xlsx, .xltx, .xlsm, .xltm, .xlam, .xlsb application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Microsoft Excel (Office Open XML)
    PPTX .pptx, .potx, .ppsx, .pptm, .potm, .ppsm application/vnd.openxmlformats-officedocument.presentationml.presentation Microsoft PowerPoint (Office Open XML)
    DOC .doc, .dot application/msword Microsoft Word (97-2003)
    XLS .xls, .xlt, .xla application/vnd.ms-excel Microsoft Excel (97-2003)
    PPT .ppt, .pot, .pps application/vnd.ms-powerpoint Microsoft PowerPoint (97-2003)
    ODT .odt application/vnd.oasis.opendocument.text OpenDocument Text
    ODS .ods application/vnd.oasis.opendocument.spreadsheet OpenDocument Spreadsheet
    ODP .odp application/vnd.oasis.opendocument.presentation OpenDocument Presentation
    GIF .gif image/gif Graphics Interchange Format (GIF)
    JPG .jpg, .jpeg image/jpeg JPEG
    PNG .png image/png Portable Network Graphics (PNG)





    Language Codes

    List of languages returned by Multi Language Detection API. The table describes the language name, language code code (according to ISO-639 for the majority of languages) and the IETF language tags in accordance with the BCP-47 standard.

    Name Three Letter Code IETF Language Tag
    Afrikaans afr af
    Albanian alb sq
    Amharic amh am
    Arabic ara ar
    Arabic (Arabizi) arz ar-arabizi
    Armenian arm hy
    Azerbaijani aze az
    Basque baq eu
    Belarusian bel be
    Bengali ben bn
    Bihari bih bh
    Bulgarian bul bg
    Catalan cat ca
    Cebuano ceb ceb
    Cherokee chr chr
    Chinese (Simplified) chi zh-Hans
    Chinese (Traditional) cht zh-Hant
    Croatian hrv hr
    Czech cze cs
    Danish dan da
    Dari fad prs-AF
    Dutch dut nl
    English eng en
    Estonian est et
    Finnish fin fi
    French fra fr
    French (Canadian) frc fr-CA
    Galician glg gl
    Ganda lug lg
    Georgian geo ka
    German ger de
    Greek gre el
    Gujarati guj gu
    Hausa hau ha
    Hebrew heb he
    Hindi hin hi
    Hmong hmn hmn
    Hungarian hun hu
    Icelandic ice is
    Indonesian ind id
    Inuktitut iku iu
    Irish gle ga
    Italian ita it
    Japanese jpn ja
    Javanese jav jv
    Kannada kan kn
    Kinyarwanda kin rw
    Korean kor ko
    Latvian lav lv
    Limbu lif lif
    Lithuanian lit lt
    Macedonian mac mk
    Malay may ms
    Malayalam mal ml
    Maltese mlt mt
    Marathi mar mr
    Nepali nep ne
    Norwegian nor no
    Oriya ori or
    Ossetian oss os
    Pashto pus ps
    Persian per fa
    Polish pol pl
    Portuguese por pt
    Portuguese (Brazil) ptb pt-BR
    Portuguese (Portugal) ptp pt-PT
    Romanian rum ro
    Russian rus ru
    Serbian srp sr
    Slovak slo sk
    Slovenian slv sl
    Somali som so
    Spanish spa es
    Sundanese sun su
    Swahili swa sw
    Swedish swe sv
    Syriac syr syr
    Tagalog tgl tl
    Tajik tgk tg
    Tamil tam ta
    Telugu tel te
    Thai tha th
    Turkish tur tr
    Ukrainian ukr uk
    Urdu urd ur
    Uzbek uzb uz
    Vietnamese vie vi
    Welsh wel cy
    Yiddish yid yi
    UNKNOWN unk





    Script Codes

    List of Script Codes returned by the Multi Language Detection API, that contain the four letter script code system defined by ISO-15924.

    Name ISO-15924 Code
    Afaka Afak
    Ahom Ahom
    Anatolian Hieroglyphs Hluw
    Arabic Arab
    Armenian Armn
    Avestan Avst
    Balinese Bali
    Bamum Bamu
    Bassa Vah Bass
    Batak Batk
    Bengali Beng
    Blissymbols Blis
    Book Pahlavi Phlv
    Bopomofo Bopo
    Brahmi Brah
    Braille Brai
    Buginese Bugi
    Buhid Buhd
    Canadian Aboriginal Cans
    Carian Cari
    Caucasian Albanian Aghb
    Chakma Cakm
    Cham Cham
    Cherokee Cher
    Cirth Cirt
    Code for Unwritten Documents Zxxx
    Common Zyyy
    Coptic Copt
    Cuneiform Xsux
    Cypriot Cprt
    Cyrillic Cyrl
    Cyrillic (Old Church Slavonic) Cyrs
    Deseret Dsrt
    Devanagari Deva
    Duployan Dupl
    Egyptian Demotic Egyd
    Egyptian Hieratic Egyh
    Egyptian Hieroglyphs Egyp
    Elbasan Elba
    Ethiopic Ethi
    Georgian Geok
    Georgian Geor
    Glagolitic Glag
    Gothic Goth
    Grantha Gran
    Greek Grek
    Gujarati Gujr
    Gurmukhi Guru
    Han Hani
    Han (Simplified) Hans
    Han (Traditional) Hant
    Hangul Hang
    Hanunoo Hano
    Hatran Hatr
    Hebrew Hebr
    Hiragana Hira
    Imperial Aramaic Armi
    Indus (Harappan) Inds
    Inherited Zinh
    Inscriptional Pahlavi Phli
    Inscriptional Parthian Prti
    Invalid Qaai
    Japanese Jpan
    Javanese Java
    Jurchen Jurc
    Kaithi Kthi
    Kannada Knda
    Katakana Kana
    Kayah Li Kali
    Kharoshthi Khar
    Khmer Khmr
    Khojki Khoj
    Khudawadi Sind
    Korean Kore
    Kpelle Kpel
    Lao Laoo
    Latin Latn
    Latin (Fraktur) Latf
    Latin (Gaelic) Latg
    Lepcha Lepc
    Limbu Limb
    Linear A Lina
    Linear B Linb
    Lisu Lisu
    Loma Loma
    Lycian Lyci
    Lydian Lydi
    Mahajani Mahj
    Malayalam Mlym
    Mandaic Mand
    Manichaean Mani
    Mathematical Notation Zmth
    Mayan Hieroglyphs Maya
    Meetei Mayek Mtei
    Mende Kikakui Mend
    Meroitic Cursive Merc
    Meroitic Hieroglyphs Mero
    Miao Plrd
    Modi Modi
    Mongolian Mong
    Moon Moon
    Mro Mroo
    Multani Mult
    Myanmar Mymr
    Nabataean Nbat
    Nakhi Geba Nkgb
    New Tai Lue Talu
    Nko Nkoo
    Nüshu Nshu
    Ogham Ogam
    Ol Chiki Olck
    Old Hungarian Hung
    Old Italic Ital
    Old North Arabian Narb
    Old Permic Perm
    Old Persian Xpeo
    Old South Arabian Sarb
    Old Turkic Orkh
    Oriya Orya
    Osmanya Osma
    Pahawh Hmong Hmng
    Palmyrene Palm
    Pau Cin Hau Pauc
    Phags Pa Phag
    Phoenician Phnx
    Psalter Pahlavi Phlp
    Rejang Rjng
    Rongorongo Roro
    Runic Runr
    Samaritan Samr
    Sarati Sara
    Saurashtra Saur
    Sharada Shrd
    Shavian Shaw
    Siddham Sidd
    SignWriting Sgnw
    Sinhala Sinh
    Sora Sompeng Sora
    Sundanese Sund
    Syloti Nagri Sylo
    Symbols Zsym
    Syriac Syrc
    Syriac (Eastern) Syrn
    Syriac (Estrangelo) Syre
    Syriac (Western) Syrj
    Tagalog Tglg
    Tagbanwa Tagb
    Tai Le Tale
    Tai Tham Lana
    Tai Viet Tavt
    Takri Takr
    Tamil Taml
    Tangut Tang
    Telugu Telu
    Tengwar Teng
    Thaana Thaa
    Thai Thai
    Tibetan Tibt
    Tifinagh Tfng
    Tirhuta Tirh
    Ugaritic Ugar
    Unknown Zzzz
    Vai Vaii
    Visible Speech Visp
    Warang Citi Wara
    Woleai Wole
    Yi Yiii





    Error codes and messages

    Note: {number} is a placeholder

    Code Error message
    4 Service timed out
    5 Client timed out
    6 Unknown language pair
    7 Unsupported input format.
    10 Pending Acknowledgement
    11 System not ready
    12 Empty Translation Result.
    13 Timed-out waiting for translation to complete.
    15 Invalid request parameters. Verify data with the documentation and try again.
    16 Invalid sync parameters. Verify data with the documentation and try again.
    17 The filter for the requested format is unavailable at this time.
    18 {0} parameter is missing or is empty.
    19 {0} must be between {1} and {2} (was {3})
    20 {0} parameter is invalid.
    21 Input characters number is greater than the maximum allowed for translation request.
    26 Xmt translation failed
    27 Internal Service Error
    37 Failed to filter document
    38 Failed to output document
    39 Invalid BCM/JSON
    41 Language detection failed
    42 Invalid requestId {0}
    43 Unknown status for requestId {0}
    44 Translation not found for requestId {0}
    45 Language pair {0} does not exist.
    46 No subscription for source language {0} target language {1}
    47 {0} language is not code 3 format or auto. (was {1})
    48 {0} language is not code 3 format. (was {1})
    49 Source language cannot be detected
    50 Language pair for source {0} and target {1} does not exist
    51 The request was rejected because its size ({0}) exceeds the configured maximum ({1})
    52 The field input exceeds its maximum permitted size of {0} bytes.
    54 Unable to generate the access token. Verify your credentials and try again.
    55 Invalid access token. The Token has expired.
    56 Invalid access token.
    57 Invalid or expired access token.
    58 Problem accessing content
    59 Invalid XML detected
    61 {0} parameter size must be between {1} and {2}
    62 Translation cancelled
    63 Cannot cancel translation, status is already: {0}
    64 File has copy protection
    1000 Failed to {0} {1}
    1001 {0} with id {1} already exists
    1002 {0} with id {1} does not exist
    1003 No account was found
    1004 {0} with email {1} already exists
    1005 Role: {0} does not exist
    1006 Email field cannot be updated
    1008 Action: {0} does not exist
    1013 {0} is required
    1015 Cannot create api credentials with name {0} for account {1}
    1016 Api credentials with name <{0}> already exists
    1018 user {0} not found
    1019 Error generating report. One of the following parameters must be empty: {0}, {1}
    1020 Cannot regenerate api credentials secret for clientId: {0} for account {1}
    1021 Parameter should be a positive integer: {0}
    1022 Maximum page size exceeded. Maximum page size is: {0}
    1023 Term already exists: {0}
    1024 Term not found: {0}
    1025 {0} with name: {1} already exists
    1026 Domain wildcard {0} already exists
    1027 Invalid domain wildcard {0}
    1029 Forbidden to translate on detected source language {0} and given target {1}
    1030 {0} parameter cannot be provided for source auto
    1031 Please provide just one operation between({0})

    Deprecated Endpoints

    These endpoints are deprecated and will be discontinued at the end of June 2020.

    Synchronous Language Identification

    Synchronous endpoints specific to language identification and multi language identification.

    1. Language identification for text

    Deprecated - please integrate the new asynchronous multi language detection api for text.
    This call will allow the user to identify the source language of a given input. The source content has to be in format plain text UTF8.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
    "input": "A mountain is generally steeper than a hill"}' \
    '"sdl-mt-api-root-url"/v4/language-identification'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
     \"input\": \"A mountain is generally steeper than a hill\"^
    }" "sdl-mt-api-root-url"/v4/language-identification
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/language-identification

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Request JSON:

    {
       "input": "A mountain is generally steeper than a hill"
    }
    

    Request Parameters

    Format
    JSON

    Name Type Mandatory Default value Description
    input string yes The source text for which we want to identify the language.



    Response JSON:

    {
       "language": "eng",
       "percent": 100
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    language string Three letters language code of the detected language
    percent int The percentage of the language represented in the text
    {
        "errors": [{
            "code": 41,
            "description": "Language detection failed"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the language was successfully detected and returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    2. Language identification for file

    Deprecated - please integrate the new asynchronous multi language detection api for file.
    This call will allow the user to identify the source language of a given input. The source content has to be in format plain text UTF8.

    curl -XPOST \
      -H "Content-Type:multipart/form-data" \
      -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" \
      -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" \
      -F "input=@\"./demo.txt\";filename=\"demo.txt\"" \
    '"sdl-mt-api-root-url"/v4/language-identification'
    
    curl -XPOST^
     -H "Content-Type:multipart/form-data"^
     -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI"^
     -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
     -F "input=@\"demo.txt\";filename=\"demo.txt\""^
     "sdl-mt-api-root-url"/v4/language-identification
    



    Request Body:

    (Request Body)
    ------------8cb4ac0ce53d926Content-Disposition: form-data; fileName="demo.txt"
    Content-Type: application/octet
    (Binary file)
    ---------8cb4ac0ce53d926-
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/language-identification

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters

    Format
    multipart/form-data

    Name Type Mandatory Default value Description
    input file yes The binary content of the file



    Response JSON:

    {
       "language": "eng",
       "percent": 100
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    language string Three letters language code of the detected language
    percent int The percentage of the language represented in the text
    {
        "errors": [{
            "code": 41,
            "description": "Language detection failed"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When the language was successfully detected and returned
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    3. Multi Language identification for text

    Deprecated - please integrate the new asynchronous multi language detection api for text. This call will allow the user to identify the source language of a given input.

    curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -H "Content-type: application/json" -d '{
    "input": "A mountain is generally steeper than a hill"}, \
    "inputFormat": "PLAIN"}' \
    '"sdl-mt-api-root-url"/v4/multi-language-identification'
    
    curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -H "Content-type: application/json" -d ^
    "{^
     \"content\": \"A mountain is generally steeper than a hill\",^
     \"inputFormat\": \"PLAIN\"^
    }" "sdl-mt-api-root-url"/v4/multi-language-identification
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/multi-language-identification

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client



    Request JSON:

    {
       "input": "A mountain is generally steeper than a hill",
       "inputFormat": "PLAIN"
    }
    

    Request Parameters

    Format
    JSON

    Name Type Mandatory Default value Description
    input string yes The source text for which we want to identify the language.
    inputFormat string no PLAIN Format of input content

    Text Input formats

    Name Description
    HTML HTML
    PLAIN Plain text (UTF8)
    XLINE Plain text, one sentence per line
    TMX Translation Memory eXchange
    XLIFF XML Localization Interchange File Format
    BCM SDL Proprietary format
    XML Extensible Markup Language
    SDLXML Treats every closing XML tag in the input as the end of a segment. The XML format in contrast does not make this assumption.



    Response JSON:

    {
      "encoding": "utf8",
      "languages": [
        {
          "code": "eng",
          "name": "English",
          "languageTag": "en",
          "score": 0.99
        }
      ],
      "scripts": [
        {
          "code": "Latn",
          "name": "Latin",
          "percent": 80.6
        },
        {
          "code": "Zyyy",
          "name": "Common",
          "percent": 19.4
        }
      ]
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    encoding string Source content encoding
    languages array Array of detected languages, sorted in descending order of their score
    code string Detected language code (See Languages Table)
    languageTag string Detected language tag
    name string Detected language full name (See Languages Table)
    score float A value between 0 and 1; the closer the value is to 1, the greater the association between the detected language and source content
    scripts array Array of scripts that constitute the input text, sorted in descending order of the percentage of characters using that script.
    code string ISO-15924 code of detected script (See Script Codes)
    name string Name of detected script
    percent float Percentage of source content using specific script
    {
        "errors": [{
            "code": 41,
            "description": "Language detection failed"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When languages are successfully detected
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error

    4. Multi Language identification for file

    Deprecated - please integrate the new asynchronous multi language detection api for file. This call will allow the user to identify the source language of a given file input.

    curl -XPOST \
      -H "Content-Type:multipart/form-data" \
      -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" \
      -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" \
      -F "input=@\"./demo.txt\";filename=\"demo.txt\"" \
      -F "inputFormat=PLAIN" \
    '"sdl-mt-api-root-url"/v4/multi-language-identification'
    
    curl -XPOST^
     -H "Content-Type:multipart/form-data"^
     -H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI"^
     -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
     -F "input=@\"demo.txt\";filename=\"demo.txt\""^
     -F "inputFormat=PLAIN"^
     "sdl-mt-api-root-url"/v4/multi-language-identification
    



    Request Body:

    (Request Body)
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="input"
    Content-Type: application/octet-stream
    Content-Length: 9
    
    doc 1
    --8MsmExZ-SgFlDSniddeMZOkUV90emq
    Content-Disposition: form-data; name="inputFormat"
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 10
    
    text/plain
    --8MsmExZ-SgFlDSniddeMZOkUV90emq--
    

    Access token type
    User credentials - Allowed User Roles: Admin, Linguist, Translator
    API credentials

    HTTP Request
    POST /v4/multi-language-identification

    Headers

    Name Value (example) Description
    Authorization Bearer asd0eXAi... Bearer token
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 Optional unique request identifier (UUID) provided by client

    Request Parameters

    Format
    multipart/form-data

    Name Type Mandatory Default value Description
    input file yes The binary content of the file
    inputFormat string no PLAIN Format of input content. See Input Formats.



    Response JSON:

    {
      "encoding": "utf8",
      "languages": [
        {
          "code": "eng",
          "name": "English",
          "languageTag": "en",
          "score": 0.99
        }
      ],
      "scripts": [
        {
          "code": "Latn",
          "name": "Latin",
          "percent": 80.6
        },
        {
          "code": "Zyyy",
          "name": "Common",
          "percent": 19.4
        }
      ]
    }
    


    Response

    Headers

    Name Value (example) Description
    BeGlobal-Request-ID dbbbc062-88a7-4783-8d52-dea795e517f4 Unique request identifier (UUID)
    Trace-ID 2c0c4dda-8333-4538-983e-e098de7cf555 The identifier provided in the request (UUID)

    Format
    JSON

    Name Type Description
    encoding string Source content encoding
    languages array Array of detected languages, sorted in descending order of their score
    code string Detected language code (See Languages Table)
    languageTag string Detected language tag
    name string Detected language full name (See Languages Table)
    score float A value between 0 and 1; the closer the value is to 1, the greater the association between the detected language and source content
    scripts array Array of scripts that constitute the input text, sorted in descending order of the percentage of characters using that script.
    code string ISO-15924 code of detected script (See Script Codes)
    name string Name of detected script
    percent float Percentage of source content using specific script
    {
        "errors": [{
            "code": 41,
            "description": "Language detection failed"
        }]
    }
    

    Error Response

    Format
    JSON

    Name Type Description
    errors list A list with the errors that occurred.
    code integer The code of the error.
    description string The description of the error.

    Returned HTTP Codes:

    Http Code Description
    200 When languages are successfully detected
    400 When the input data is not valid
    401 When the authentication process failed or the access token is not valid
    403 Forbidden to access resource
    500 Application internal error