Upload File (/v1/file/upload)

This v1 API method is scheduled for deprecation October 1, 2017. Where possible, use File API v2

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

'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.


apiKey (required)

The API Key for your account. Available in the Smartling dashboard at Project Settings>API.

projectId (required)

The unique ID for your project. Available in the Smartling dashboard at Project Settings>API.

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.

approved (optional)

Determines whether content in the file is authorized (available for translation) upon submitting the file via the Smartling Dashboard. An error message will return if there are insufficient translation funds and approved is set to true.If string has been completely excluded for translation from all languages, or excluded from translation for a specific language, approved will NOT authorize it.

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

localesToApprove (optional)

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 localesToApprove parameter pairs to authorize more than one locale. You can add languages by uploading the file again and indicating the language to authorize with localesToApprove or all languages with approved, 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, localesToApprove will NOT authorize it. Note: Do not set the approved parameter to TRUE if you want to specify individual locales to approve. Submitting an upload with both of these parameters set will result in a validation error.

fileType (required)

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

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.

   "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.