--- title: "Upload file to a batch" method: POST path: "/job-batches-api/v2/projects/{projectId}/batches/{batchUid}/file" tags: ["Job Batches V2"] --- # Upload file to a batch `POST /job-batches-api/v2/projects/{projectId}/batches/{batchUid}/file` ## Request - Base URL: `https://api.smartling.com` - URL: `https://api.smartling.com/job-batches-api/v2/projects/{projectId}/batches/{batchUid}/file` - Auth: HTTP bearer This endpoint is actually a proxy for Upload File in the Files API, and it works with these two differences: 1. It additionally gets `batchUid` as a path parameter. 2. It doesn't relay `localeIdsToAuthorize` to Files Api, therefore the file stays unauthorized. Instead, `localeIdsToAuthorize` are saved just for this batch session and are used when a file is being attached to a job. Upload is only possible if the file was declared in the `Create Batch` request or added with `REGISTER_FILE` action. When the first file is uploaded to the new batch, the batch status changes to `ADDING_FILES`. Adds original source content to a Job batch in Smartling. The provided curl example will upload your Java properties file directly to a Smartling project, identified by the `projectId`, and attaches it to a Job linked to `batchUid`. The response is returned right after the content of a file is accepted by the Files API. After that, the Batch service controls whether the file upload finished. Content is parsed, all strings are ingested, and the file is then attached to the Job which is linked to the batch for locales, described in `localeIdsToAuthorize`. Endpoint returns response as soon as a file is uploaded to job batches server. File is uploaded to FILE API asynchronously. **Common issues**: * Each file must include the `fileUri` registered with the batch, upon upload. For example, if you have created a batch with the single file URI `test1.xml` and you attempt to upload this with the file URI `test2.xml` it will fail, and you will get an error. But you can always use `REGISTER_FILE` action. * File URI's must be unique per batch, even if you want to authorize it to two or more locales. For example, if you have file `test1.xml` that should be authorized for `es` and `de`, and you attempt to upload it twice (`fileUri=test1.xml` + `localeIdsToAuthorize[]=es` and `fileUri=test1.xml` + `localeIdsToAuthorize[]=de`), it will fail and you will get an error. The second upload will be rejected and file will be authorized only for `es` locale. You must always pass all desired locales with the registered fileUri (`fileUri=test1.xml` + `localeIdsToAuthorize[]=es,de`). ## Path parameters - `projectId` string, required: Unique identifier of a Smartling project — 9 lowercase alphanumeric characters. - `batchUid` string, required ## Request body `multipart/form-data` - object - `file` string, binary, required: The file contents to upload. - `fileUri` string, required: A value that uniquely identifies the uploaded file. This ID can be used to request the file back. We recommend that you use file path and file name, similar to how version control systems identify the file. Example: `/myproject/i18n/ui.properties` **Validation**: Must not be blank and must not exceed 512 characters. - `fileType` 'android' | 'arb' | 'asciidoc' | 'csv' | 'dita' | 'ditaZip' | 'doc' | 'docm' | 'docx' | 'flare' | 'fluent' | 'freemarker' | 'gettext' | 'html' | 'idml' | 'imageJpg' | 'imagePng' | 'imageWebp' | 'indd' | 'ios' | 'javaProperties' | 'json' | 'madcap' | 'markdown' | 'mdx' | 'pdf' | 'plainText' | 'ppt' | 'pptx' | 'pres' | 'qt' | 'resx' | 'rtf' | 'srt' | 'stringsdict' | 'svg' | 'vsdm' | 'vsdx' | 'vtt' | 'xcstrings' | 'xliff' | 'xliff2' | 'xls' | 'xlsx' | 'xlsxTemplate' | 'xml' | 'yaml', required: A unique identifier for the file type. - `authorize` boolean: Ignored Endpoint accepts this field to be consistent with `File Upload` but it doesn't relay it to File Api - `localeIdsToAuthorize[]` LocaleId[], required: This value declares locales list which should be used when file is attached to a job. **Note**: File will not be authorized for these locales once it is uploaded. Authorization happens only when a job is authorized. - `smartling.namespace` string: This is only for accounts created after July 31st, 2015. Define a custom [namespace](https://help.smartling.com/hc/en-us/articles/360008143833) for the 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` string: 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]` string: Provides custom parser configuration for supported file types. See [Supported File Types](https://help.smartling.com/hc/en-us/articles/360007998893) for more details. - `callbackUrl` string, uri: 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. If the upload has begun but is taking more than a minute to complete, it responds with status `202`. ## Response `202` ACCEPTED - EmptyResponse - `response` object, required - `code` 'SUCCESS', required: Indicates whether the response was successful or what error has occurred. - `data` object: Always null. ## Other responses - `400`: Provided request parameters are invalid. - `401`: Provided credentials are not valid. - `404`: Batch provided in path is not found - `429`: Too many simultaneous API requests. - `500`: Unexpected error ## Changes - **2026-10-17** `2cd7a8215799`: 1 info - endpoint added [Operation history](https://skmtc.dev/smartling/apis/smartling-rest-api-reference/changes/job-batches-api/v2/projects/:projectId/batches/:batchUid/file/post.md) --- [API](https://skmtc.dev/smartling/apis/smartling-rest-api-reference.md) - [All operations](https://skmtc.dev/smartling/apis/smartling-rest-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/smartling/apis/smartling-rest-api-reference/revisions/e63066e7f5e9?raw)