Upload File

POST - /files-api/v2/projects/{projectId}/file

Uploads original source content to Smartling (50MB limit for .pptx; 25MB limit for .idml; 20MB limit for .doc, .docx; and 10MB limit for all others).

See Supported File Types for a list of accepted file types.

'Resource Locked' errors

Uploading files can take some time, especially if the file is very large, or if it contains a high number of strings. Attempting another API request related to the file, such as a Download or Status request, before upload is complete will return a 423 - Resource Locked error in order to prevent incorrect information being returned due to an incomplete upload. Smartling manages incoming requests intelligently to minimize the time that a file will be locked. However, if you work with large files, we recommend building wait/retry mechanisms into any processes that request recently uploaded files.


file (required)

The file contents to upload. This should be submitted via a multipart/form-data POST request.

fileUri (required)

Value that uniquely identifies the uploaded file. This ID can be used to request the file back. We recommend you use file path + file name, similar to how version control systems identify the file. Example: /myproject/i18n/ui.properties.

fileType (required)

Unique identifier for the file type. Permitted values: android, ios, gettext, html, javaProperties, yaml, xliff, xml, json, docx, pptx, xlsx, idml, qt, resx, plaintext, csv, stringsdict.

authorize (optional)

Determines whether content in the file is authorized (available for translation) in all locales upon submitting the file via the Smartling Dashboard. An error message will return if there are insufficient translation funds and authorized is set to true. If a string has been completely excluded for translation from all languages, or excluded from translation for a specific language, authorize will NOT authorize it. Note: to specify a limited list of locales to authorize, use the localeIdsToAuthorize[] parameter.

true Content will be available for translation in all locales on upload
false (default) Content will be added to the "Awaiting Authorization" queue on upload

localeIdsToAuthorize[] (optional)

array - This value, if set, authorizes strings for translation into specific locales. Use the project/locale/list call to get the list of locales for the project or see them in the dashboard on the API settings page. Use multiple localeIdsToAuthorize parameter pairs to authorize more than one locale. You can add languages by uploading the file again and indicating the language to authorize with localeIdsToAuthorize or all languages with authorize, or in the dashboard using the "Show Partially Authorized" filter option from the Awaiting Authorization list. If string has been completely excluded for translation from all languages, or excluded from translation for a specific language, localesIdsToAuthorize will NOT authorize it. Note: Do not set the authorize parameter to TRUE if you want to specify individual locales to authorize. Submitting an upload with both of these parameters set will result in a validation error.

smartling.namespace (optional)

For accounts created after July 31st 2015 only. Define a custom namespace for the file. This works for Application Resource Files only. For Business Documents, see Update File. Note: while this parameter shares the format of other file directives, it will not work as an inline directive and must be specified in the API call.

smartling.file_charset (optional)

Specifies a custom charset for text-format files. The value should be the name of the character set. See a full list of supported character sets here.

If this directive is not used, Smartling will use the Content-Type request header to determine if the content is encoded with UTF-16, UTF-16B or UTF-16LE. If there is no Content-Type header, Smartling will examine the file for UTF-16 characters. If none are detected, UTF-8 encoding will be used.

Note: Once this property has been set for a file, it cannot be changed. If you reupload the file, it will use the original charset, even if you change the directive. An error will be returned if this directive is used when uploading binary-format file types, such as Office or IDML files.

smartling.[command] (optional)

Provides custom parser configuration for supported file types. See Supported File Types for more details.

callbackUrl (optional)

A GET request that creates a callback to a URL when a file is 100% published for a locale. The callback gives the fileUri and locale with the format http[/s]://your.url?locale=xx-XX&fileUri=your.file. If you upload the file again, without a callbackUrl, it will remove any previous callbackUrl for that file. The RequestBin (http://requestb.in) service is a convenient way to test callback. RequestBin generates a short-lived disposable URL that displays all posted requests.

If a callback fails, Smartling will make multiple attempts to reach the designated URL, however, we do not keep retrying a failed callback indefinitely. Try to make sure your callback URL is as stable as possible and be aware that callbacks are not a 100% reliable way of being notified that a file is published.


A successful upload usually receives a 200 SUCCESS response, but if the upload is not complete after a minute, a 202 ACCEPTED response will be sent. See Response Format for more details.

  "response": {
    "code": "SUCCESS",
    "data": {
      "overWritten": "[true|false]",
      "stringCount": "[number]",
      "wordCount": "[number]"


Indicates whether the uploaded file has overwritten an existing file; either true or false.


The number of strings in the uploaded file.


The number of words in the uploaded file.