REST API

Overview of the API

Smartling provides RESTful APIs for many of the actions available through the Smartling UI, allowing you to automate your translation process.

API categories

The table below provides an overview of the available public APIs.

Translation

For submitting content for translation and downloading completed translations. These are the most commonly used APIs for integrating with Smartling.

https://api-reference.smartling.com/#tag/Files
https://api-reference.smartling.com/#tag/Jobs
https://api-reference.smartling.com/#tag/Job-Batches-V1
https://api-reference.smartling.com/#tag/Job-Batches-V2
https://api-reference.smartling.com/#tag/Context
https://api-reference.smartling.com/#tag/Strings

Translation management

For managing aspects of the translation management process.

https://api-reference.smartling.com/#tag/Estimates 
https://api-reference.smartling.com/#tag/Issues
https://api-reference.smartling.com/#tag/Tags
https://api-reference.smartling.com/#tag/Vendors
https://api-reference.smartling.com/#tag/Reports
https://api-reference.smartling.com/#tag/Attachments
https://api-reference.smartling.com/#tag/Translation-quality-checks
https://api-reference.smartling.com/#tag/Issue-Webhooks

Account management

For managing your Smartling account.

https://api-reference.smartling.com/#tag/Account-and-Projects
https://api-reference.smartling.com/#tag/Locales
https://api-reference.smartling.com/#tag/People

GDN

Related to the Smartling Global Delivery Network product.

https://api-reference.smartling.com/#tag/GDN-url-management

Authentication

For authenticating to the API. Required for using any of the other APIs.

https://api-reference.smartling.com/#tag/Authentication

 

API URL

Hostname

The API hostname is:

api.smartling.com

Path

The path to specific API endpoints is structured as follows:

  /<service>-api/<version>/<authorization root>/<resources-and-optional-parameters>

The authorization root is generally either 'accounts' followed by an account ID, or 'projects' followed by a project ID.

For example:

  https://api.smartling.com/accounts-api/v2/accounts/677dfe99/projects
  https://api.smartling.com/files-api/v2/projects/453a3d5a2/file/status?fileUri=xyz

Request format

The REST API is accessed by sending HTTP requests to the required API endpoints, and processing the resulting HTTP responses.

All requests, except for authentication and token refresh, must include a valid access token in an HTTP header as well as an appropriate content-type header. In general, POST and PUT requests use Content-Type: application/json.

API parameters are included in the request URI, the query parameters, the request body, or some combination of these, depending on the endpoint being called.

Array query parameters

In most cases, arrays in query parameters should be specified without square brackets. Instead, simply repeat the parameter:

/projects/{projectId}/resource?foo=bar&foo=qux

However, some legacy APIs may still use square brackets:

/projects/{projectId}/resource?foo[]=bar&foo[]=qux

Refer to the API reference documentation to determine which one is required.

Responses

Responses to successful requests contain JSON content in this format:

{
   "response": {
      "code": "SUCCESS",
      "data": {
      }
   }
}

The contents of the data node in the response varies depending on the endpoint and the results of the request, and may in some cases by null.

Errors

Error responses have a 4xx or 5xx HTTP status code. When this happens, the response bodies look like the following:

{
     "response": {
         "code": "ERROR_CODE",
         "errors": [
               {
                    “key”: “error.key”,
                    “message”: “Error message”,
                    “details”: {
                          “field”:”value”
                    }
               } 
        ]
     }
}

The structure of the details node varies depending on the endpoint, and in some cases may be null.

For more information, see Error Handling.

Date formats

All dates are represented as strings using the ISO-8601 date standard in UTC.

Pattern:

yyyy-MM-dd'T'HH:mm:ss'Z'

Example:

2020-11-21T01:51:17Z

Authentication

To use the API, you must first authenticate by sending a user ID and secret to the authentication endpoint. This will return an access token and a refresh token. The access token is then included in a header in subsequent requests. The access token expires and must be refreshed periodically using the refresh endpoint. For more details, see Authentication.

Rate limits

To maintain service availability, two kinds of limits are applied to API usage: a maximum request rate and a maximum number of concurrent requests. Counting can be per user, project and/or account, depending on which endpoint is being accessed, and the maximum values vary by endpoint.

When a rate limit is hit by an API client, the server sends an HTTP 429 MAX_OPERATIONS_LIMIT_EXCEEDED response, along with details of the specific limit. If this happens, the client should pause requests for a time, and then retry. For more details, see Rate Limits.

Pagination

List-type endpoints that result in a large result set (for example, ‘list all jobs within an account’) divide the response data into pages and return a single page per response. The caller specifies which page to send by using the limit and offset API parameters. For more details, see Pagination.

Asynchronous processes

For requests that take a long time to process, such as processing a large file upload, the API returns a 202 ACCEPTED response, meaning that the work has started but not completed. To know when such a process is complete, the client must poll a separate status endpoint. For some common situations, such as adding files to a job, helper APIs that handle some of the status checking are available (e.g., job batches).

Webhooks

Webhooks can be configured via API for various events, such as ‘translation completed’. When these events occur, a Smartling service sends an HTTP request to the configured callback URL. GET and POST requests are supported, in addition to signed requests. For more details, see Webhooks and Callbacks.

SDKs

We are currently reassessing our SDK offering and will have additional information on this soon.

Was this article helpful?