---
title: "Create translation job"
method: POST
path: "/job-batches-api/v2/projects/{projectId}/jobs"
tags: ["Job Batches V2"]
---

# Create translation job

`POST /job-batches-api/v2/projects/{projectId}/jobs`

## Request

- Base URL: `https://api.smartling.com`
- URL: `https://api.smartling.com/job-batches-api/v2/projects/{projectId}/jobs`
- Auth: HTTP bearer

Creates a new translation job or fetches an existing one based on the specified criteria.

**Purpose**: This endpoint simplifies the common workflow where you need to obtain a translation job for file uploads
without managing the full complexity of job creation. It's particularly useful in automation scripts (e.g., bash scripts)
and integration scenarios where you have a desired job name and simply need to get a `translationJobUid` to proceed
with file uploads. The job can be reviewed and configured later through the Smartling dashboard.

**When to use this endpoint**:
- You need a simple "get or create" job operation by name
- You're building file upload workflows and need a job quickly
- You're writing automation scripts or integrations

**When to use the standard Jobs API instead**: If you require full control over job creation with all available
parameters (custom fields, reference numbers, due dates, etc.), please use the
[Jobs API Create Job endpoint](#operation/addJob).
This endpoint intentionally provides a simplified interface focused on the most common use case.

**Dynamic job naming**: The `nameTemplate` parameter supports date pattern placeholders using Java `DateTimeFormatter`
syntax (e.g., `{yyyy}`, `{QQQ}`). These patterns are evaluated at request time using the specified `timeZoneName`.

**Job creation behavior** depends on the `mode` parameter:

- **REUSE_EXISTING**: Returns an existing job if one matches the evaluated name template. If the matching job is
  closed, creates a new job with a unique name using the specified `salt` strategy.
- **CREATE_NEW**: Attempts to create a new job with the evaluated name. If a job with that name already exists,
  appends a unique identifier using the specified `salt` strategy to ensure creation succeeds.

**Examples**:

1. **Quarterly localization job**:
   ```json
   {
     "nameTemplate": "Q{QQQ} {yyyy} Localization",
     "timeZoneName": "America/New_York",
     "mode": "REUSE_EXISTING"
   }
   ```
   Evaluates to: "Q1 2025 Localization" (when called in Q1 2025)

2. **Daily content updates**:
   ```json
   {
     "nameTemplate": "Daily Update {yyyy-MM-dd}",
     "timeZoneName": "Europe/London",
     "mode": "REUSE_EXISTING"
   }
   ```
   Evaluates to: "Daily Update 2025-10-08"

3. **Always unique jobs**:
   ```json
   {
     "nameTemplate": "Feature Release {yyyy}",
     "mode": "CREATE_NEW",
     "salt": "TIMESTAMP"
   }
   ```
   Creates: "Feature Release 2025 2025-10-08 02:34:15 PM" (if job already exists)

4. **Job reuse with salt suffix**:
   **First request** - Creates initial job:
   ```json
   POST /job-batches-api/v2/projects/abc123/jobs
   {
     "nameTemplate": "Daily Report {yyyy-MM-dd}",
     "mode": "REUSE_EXISTING",
     "salt": "RANDOM_ALPHANUMERIC",
     "targetLocaleIds": ["fr-FR", "de-DE"]
   }
   ```
   Response: `{"jobName": "Daily Report 2025-12-09", "translationJobUid": "job001"}`

   **After job is completed and closed...**

   **Second request** - Creates job with salt (original is closed):
   ```json
   POST /job-batches-api/v2/projects/abc123/jobs
   {
     "nameTemplate": "Daily Report {yyyy-MM-dd}",
     "mode": "REUSE_EXISTING",
     "salt": "RANDOM_ALPHANUMERIC",
     "targetLocaleIds": ["fr-FR", "de-DE"]
   }
   ```
   Response: `{"jobName": "Daily Report 2025-12-09 a7x9k", "translationJobUid": "job002"}`

   **Third request** - Reuses job with salt (prevents duplicate):
   ```json
   POST /job-batches-api/v2/projects/abc123/jobs
   {
     "nameTemplate": "Daily Report {yyyy-MM-dd}",
     "mode": "REUSE_EXISTING",
     "salt": "RANDOM_ALPHANUMERIC",
     "targetLocaleIds": ["fr-FR", "de-DE"]
   }
   ```
   Response: `{"jobName": "Daily Report 2025-12-09 a7x9k", "translationJobUid": "job002"}` (same job)

   **Key behavior**: The third request reuses the job with salt suffix instead of creating another duplicate,
   preventing multiple jobs with different salts for the same day.

## Path parameters

- `projectId` string, required: Unique identifier of a Smartling project — 9 lowercase alphanumeric characters.

## Request body

- JobBatchCreateJobRequest: The payload to use when creating a translation job.
  - `nameTemplate` string, required: The name template for the job, used to identify or create the job. Must be a non-empty string. **Dynamic date patterns**: The template supports date pattern placeholders enclosed in curly braces `{}`, which are evaluated at request time using Java `DateTimeFormatter` syntax. Patterns are replaced with actual date/time values based on the specified `timeZoneName` (or server time if not specified). **Common pattern examples**: - `{yyyy}` - Four-digit year (e.g., "2025") - `{yy}` - Two-digit year (e.g., "25") - `{QQQ}` - Quarter of year (e.g., "Q1", "Q2") - `{QQQQ}` - Full quarter text (e.g., "1st quarter") - `{MM}` - Month as two digits (e.g., "01", "12") - `{MMM}` - Short month name (e.g., "Jan", "Dec") - `{dd}` - Day of month (e.g., "08", "25") - `{yyyy-MM-dd}` - ISO date format (e.g., "2025-10-08") **Examples**: - `"Q{QQQ} {yyyy} Localization"` → evaluates to "Q1 2025 Localization" (in Q1 2025) - `"Daily Update {yyyy-MM-dd}"` → evaluates to "Daily Update 2025-10-08" - `"Release {yyyy}"` → evaluates to "Release 2025" For complete pattern syntax, refer to the [Java DateTimeFormatter documentation](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html).
  - `description` string: Optional description for the job.
  - `targetLocaleIds` LocaleId[]: List of target locale IDs for the job.
  - `mode` 'CREATE_NEW' | 'REUSE_EXISTING': Determines job creation behavior. - **REUSE_EXISTING** (default): Returns an existing job if one matches the evaluated `nameTemplate`. If the matching job is closed or completed (final state), automatically creates a new job with a unique name by appending a salt identifier. This mode is ideal for workflows where you want to reuse active jobs but ensure work continues when previous jobs are closed. - **CREATE_NEW**: Attempts to create a new job with the evaluated `nameTemplate`. If a job with that exact name already exists, automatically appends a salt identifier to create a job with a unique name. If no job exists with that name, creates the job without salt modification.
  - `salt` 'RANDOM_ALPHANUMERIC' | 'TIMESTAMP': Determines the format of the unique identifier appended to job names when necessary to avoid conflicts. Salt is applied based on the `mode` parameter behavior. **When salt is applied**: - With **REUSE_EXISTING**: Salt is appended when an existing job with the evaluated name is in a closed state, ensuring a new unique job is created. - With **CREATE_NEW**: Salt is appended when a job with the evaluated name already exists, regardless of status. **Salt formats**: - **RANDOM_ALPHANUMERIC** (default): Appends a space and 5 random alphanumeric characters to the job name (e.g., "My Job aB3x9"). - **TIMESTAMP**: Appends a space and formatted timestamp in "yyyy-MM-dd hh:mm:ss a" format, evaluated using the specified `timeZoneName` (e.g., "My Job 2025-10-08 02:34:15 PM").
  - `timeZoneName` string: Time zone name for the job, either an abbreviation such as "PST", a full name such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". For complete pattern syntax, refer to the [Java TimeZone documentation](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/TimeZone.html)

## Response `200`

OK

- JobBatchCreateJobResponse: Info about created or fetched translation job.
  - `response` object, required
    - `code` 'SUCCESS', required: Indicates whether the response was successful or what error has occurred.
    - `data` object
      - `translationJobUid` string: Translation job unique identifier — 12 lowercase alphanumeric characters.
      - `jobName` string: The name of the job.
      - `jobNumber` string: The job number.
      - `dueDate` string: The due date of the job in ISO 8601 format.
      - `targetLocaleIds` LocaleId[]: List of target locale IDs for the job.
      - `createdDate` string: The creation date of the job in ISO 8601 format.
      - `jobStatus` string: The current status of the job.
      - `referenceNumber` string: The reference number for the job.
      - `description` string: The description of the job.

## Other responses

- `400`: Validation error
- `401`: Provided credentials are not valid.
- `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/jobs/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)