Smartling Jobs API

openapi: 3.0.0
info:
  contact:
    email: support@smartling.com
  description: 'Before you begin using the Smartling APIs, we recommend going through our [Developer documentation](https://help.smartling.com/hc/en-us/categories/1260801686149).

    '
  termsOfService: https://www.smartling.com/legal
  title: Smartling REST API Reference Account & Projects Jobs API
  version: 2.0.0
  x-logo:
    url: smartling_logo.png
servers:
- url: https://api.smartling.com
tags:
- name: Jobs
  description: 'A Smartling project (such as a mobile, web, files, or connector project)

    may contain one or more

    [jobs](https://help.smartling.com/hc/en-us/articles/1260805481390). You may

    have multiple projects, each containing multiple jobs. Each job contains

    strings, consisting of words or phrases.


    The Jobs feature allows you to group and prioritize your content by name,

    due date, description, and reference number (optional). It also enables

    you to monitor the progress of your translations throughout completion.


    The Jobs API allows you to create a job, add a file to a job, authorize a

    job, and cancel a job, among many other actions. You have full control via

    the API to manage your job(s).'
paths:
  /jobs-api/v3/accounts/{accountUid}/jobs:
    get:
      summary: List jobs within an account
      description: List / search the jobs within an account. By default, only the last 50 jobs are returned. Use the <code>limit</code> and <code>offset</code> parameters to return more than 50 jobs. <a href="https://help.smartling.com/hc/en-us/articles/1260805176869-Pagination" target="_blank">Learn more.</a>
      tags:
      - Jobs
      operationId: getJobsByAccount
      parameters:
      - name: accountUid
        description: A unique account identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - description: Used for searching jobs by `jobName`. Any entry is treated as a LIKE query on the name of the job.
        in: query
        name: jobName
        required: false
        schema:
          type: string
      - description: Used for searching jobs by `projectId`. Supports up to 500 `projectId`s.
        in: query
        name: projectIds
        required: false
        schema:
          items:
            type: string
          type: array
      - description: Used for searching jobs by their status.
        in: query
        name: translationJobStatus
        required: false
        schema:
          items:
            enum:
            - DRAFT
            - AWAITING_AUTHORIZATION
            - IN_PROGRESS
            - COMPLETED
            - CANCELLED
            - CLOSED
            - DELETED
            type: string
          type: array
      - name: withPriority
        description: If set to `true`, returns jobs only with priority.
        in: query
        required: false
        schema:
          type: boolean
      - description: The limit on the number of jobs returned.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: The offset to use when searching for jobs.
        in: query
        name: offset
        required: false
        schema:
          type: integer
      - description: The field to sort by.
        in: query
        name: sortBy
        required: false
        schema:
          enum:
          - createdDate
          - priority
          type: string
      - description: The direction to sort.
        in: query
        name: sortDirection
        required: false
        schema:
          enum:
          - ASC
          - DESC
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListJobsResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
                      data:
                        items:
                        - createdDate: '2015-11-21T11:51:17Z'
                          description: my job description
                          dueDate: '2015-11-21T11:51:17Z'
                          jobName: myJobName
                          jobNumber: SMTL-123
                          jobStatus: IN_PROGRESS
                          priority: 2
                          projectId: fd7244365
                          referenceNumber: myReferenceNumber1
                          targetLocaleIds:
                          - fr-FR
                          - es
                          translationJobUid: abc123abc
                        totalCount: 1
        '400':
          $ref: '#/components/responses/Error400ResponseDefinition'
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
      x-code-samples:
      - lang: curl
        source: 'curl -H "Authorization: Bearer $smartlingToken" https://api.smartling.com/jobs-api/v3/accounts/$smartlingAccountId/jobs

          '
  /jobs-api/v3/projects/{projectId}/jobs:
    get:
      summary: List jobs within a project
      description: List / search the jobs within a project. By default, only the last 50 jobs are returned. Use the <code>limit</code> and <code>offset</code> parameters to return more than 50 jobs. <a href="https://help.smartling.com/hc/en-us/articles/1260805176869-Pagination" target="_blank">Learn more.</a>
      tags:
      - Jobs
      operationId: getJobsByProject
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - description: Used for searching jobs by `jobName`. Any entry is treated as a LIKE query on the name of the job.
        in: query
        name: jobName
        required: false
        schema:
          type: string
      - description: Used for searching jobs by `jobNumber`. Search works by exact comparison.
        in: query
        name: jobNumber
        example: SMTL-123
        required: false
        schema:
          type: string
      - description: Used for searching jobs by `translationJobUid`. Supports up to 500 `translationJobUid`s.
        in: query
        name: translationJobUids
        required: false
        schema:
          items:
            type: string
          type: array
      - description: Used for searching jobs by their status.
        in: query
        name: translationJobStatus
        required: false
        schema:
          items:
            enum:
            - DRAFT
            - AWAITING_AUTHORIZATION
            - IN_PROGRESS
            - COMPLETED
            - CANCELLED
            - CLOSED
            - DELETED
            type: string
          type: array
      - description: The limit on the number of jobs returned.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: The offset to use when searching for jobs.
        in: query
        name: offset
        required: false
        schema:
          type: integer
      - description: The field to sort by.
        in: query
        name: sortBy
        required: false
        schema:
          enum:
          - createdDate
          - dueDate
          - jobName
          type: string
      - description: The direction to sort.
        in: query
        name: sortDirection
        required: false
        schema:
          enum:
          - ASC
          - DESC
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobsResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
                      data:
                        items:
                        - createdDate: '2015-11-21T11:51:17Z'
                          description: my job description
                          dueDate: '2015-11-21T11:51:17Z'
                          jobName: myJobName
                          jobNumber: SMTL-123
                          jobStatus: IN_PROGRESS
                          referenceNumber: myReferenceNumber1
                          targetLocaleIds:
                          - fr-FR
                          - es
                          translationJobUid: abc123abc
                        - createdDate: '2015-11-21T11:51:17Z'
                          description: my job description
                          dueDate: '2015-11-21T11:51:17Z'
                          jobName: myJobName2
                          jobNumber: SMTL-987
                          jobStatus: IN_PROGRESS
                          referenceNumber: myReferenceNumber1
                          targetLocaleIds:
                          - fr-FR
                          - de
                          translationJobUid: abc321xyz
                        totalCount: 2
        '400':
          $ref: '#/components/responses/Error400ResponseDefinition'
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
      x-code-samples:
      - lang: curl
        source: 'curl -H "Authorization: Bearer $smartlingToken" https://api.smartling.com/jobs-api/v3/projects/$smartlingProjectId/jobs

          '
    post:
      summary: Create job
      description: Creates a job within Smartling.
      tags:
      - Jobs
      operationId: addJob
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShallowJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
                      data:
                        translationJobUid: abc123abc
                        jobName: myJobName
                        jobNumber: SMTL-123
                        targetLocaleIds:
                        - fr-FR
                        callbackMethod: GET|POST
                        callbackUrl: https://www.callback.com/smartling/job
                        createdByUserUid: userUid123abc
                        createdDate: '2015-11-21T11:51:17Z'
                        description: my job description
                        dueDate: '2015-11-21T11:51:17Z'
                        jobStatus: IN_PROGRESS
                        firstCompletedDate: '2015-11-21T11:51:17Z'
                        firstAuthorizedDate: '2015-01-21T11:51:17Z'
                        lastCompletedDate: '2015-11-21T11:51:17Z'
                        lastAuthorizedDate: '2015-12-21T11:51:17Z'
                        modifiedByUserUid: userUid321abc
                        modifiedDate: '2015-11-21T11:51:17Z'
                        referenceNumber: myReferenceNumber1
                        customFields:
                        - fieldUid: rbrbn69wa1pa
                          fieldName: Department
                          fieldValue: Finance Dept
                        - fieldUid: 3rrwchzmjf27
                          fieldName: Adaptation Required
                          fieldValue: 'true'
                        issues:
                          sourceIssuesCount: 3
                          translationIssuesCount: 4
        '400':
          description: Validation error during job creation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
              examples:
                response:
                  value:
                    response:
                      code: VALIDATION_ERROR
                      errors:
                      - details:
                          field: jobName
                        key: null
                        message: There is already a job with that name. Please provide a unique name.
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
      x-code-samples:
      - lang: curl
        source: 'curl -X POST -H "Authorization: Bearer $smartlingToken" -H "Content-Type: application/json" -d "$smartlingJobJSON" https://api.smartling.com/jobs-api/v3/projects/$smartlingProjectId/jobs

          '
  /jobs-api/v3/projects/{projectId}/jobs/find-jobs-by-strings:
    post:
      summary: Search Jobs By Hashcodes And Locales
      description: 'Search Job(s), based on locales and hashcodes. We allow total 20000 records to be passed. Means it could be 10 locales * 2000 hashcodes or 1 locale * 20000 hashcodes or no locales and just 20000 hashcodes, etc

        '
      tags:
      - Jobs
      operationId: findJobsByStrings
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTranslationJobByLocalesAndHashcodesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTranslationJobByLocalesAndHashcodesResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
                      data:
                        totalCount: 2
                        items:
                        - translationJobUid: abc123abc
                          jobName: myJobName
                          dueDate: '2015-11-21T11:51:17Z'
                          hashcodesByLocale:
                          - localeId: fr-FR
                            hashcodes:
                            - hashcode1
                            - hashcode3
                          - localeId: de-DE
                            hashcodes:
                            - hashcode4
                            - hashcode3
                        - translationJobUid: abc456abc
                          jobName: myJobName2
                          dueDate: '2015-11-21T11:51:17Z'
                          hashcodesByLocale:
                          - localeId: ru-RU
                            hashcodes:
                            - hashcode1
                            - hashcode3
                          - localeId: uk-UA
                            hashcodes:
                            - hashcode4
                            - hashcode3
        '400':
          description: Validation error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
              examples:
                response:
                  value:
                    response:
                      code: VALIDATION_ERROR
                      errors:
                      - key: null
                        message: Limit 20,000 of total elements (hashcodes * locales) has been exceeded
                        details: null
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
  /jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/strings:
    get:
      summary: Get translation job strings.
      description: 'This gets translation job string hashcodes with locales

        '
      tags:
      - Jobs
      operationId: getStringsForTranslationJob
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - in: path
        name: translationJobUid
        required: true
        schema:
          type: string
      - in: query
        name: targetLocaleId
        required: false
        schema:
          type: string
        description: Target / translation locale id.
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          default: 1000
        description: Max amount of result items.
      - in: query
        name: offset
        required: false
        schema:
          type: integer
          default: 0
        description: Amount of items to skip.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocaleHashcodeResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
                      data:
                        totalCount: 3
                        items:
                        - targetLocaleId: uk-UA
                          hashcode: hashcode1
                        - targetLocaleId: es
                          hashcode: hashcode2
                        - targetLocaleId: es
                          hashcode: hashcode1
        '400':
          $ref: '#/components/responses/Error400ResponseDefinition'
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '404':
          description: Job not found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
              examples:
                response:
                  value:
                    response:
                      code: NOT_FOUND_ERROR
                      errors:
                      - key: null
                        message: Translation job is not found
                        details: null
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
  /jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/strings/add:
    post:
      summary: Add strings to job
      description: 'Adding strings to a job is useful if you don''t manage strings / content through files, but instead need to add strings by some other means other than files.


        When strings are successfully added to a job, a `200` status is returned. When the system can''t quickly add strings to the job, a `202` response status is returned. The response contains a link and `processUid` to check the progress of the request. When a `202` is received, the process of adding the content to the job will not be complete until the returned process has completed.

        '
      tags:
      - Jobs
      operationId: addStringsToJob
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - in: path
        name: translationJobUid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddStringsJobRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddContentSuccessFailCountJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
                      data:
                        failCount: 0
                        successCount: 100
        '202':
          description: ACCEPTED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncProcessJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: ACCEPTED
                      data:
                        message: This process will continue asynchronously and may take up to a few minutes.
                        url: https://api.smartling.com/jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/processes/{processUid}
        '400':
          description: Validation error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
              examples:
                response:
                  value:
                    response:
                      code: VALIDATION_ERROR
                      errors:
                      - key: null
                        message: Invalid locales [ad]
                        details:
                          field: targetLocaleIds
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
  /jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/strings/remove:
    post:
      summary: Remove strings from job
      description: 'Remove strings from a job. Any strings removed from the job will also be unauthorized within Smartling.


        If strings are successfully removed from a job, a `200` status will be returned. When the system can''t quickly add the strings to the job, a `202` response is returned. The response contains a link to check the progress of the request. When a `202` is received, the process of removing the content from the job will not be complete until the returned process has completed.

        '
      tags:
      - Jobs
      operationId: removeStringsFromJob
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - in: path
        name: translationJobUid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveStringsJobRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessFailCountJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
                      data:
                        failCount: 0
                        successCount: 100
        '202':
          description: ACCEPTED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncProcessJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: ACCEPTED
                      data:
                        message: This process will continue asynchronously and may take up to a few minutes.
                        url: https://api.smartling.com/jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/processes/{processUid}
        '400':
          $ref: '#/components/responses/Error400ResponseDefinition'
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
  /jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/close:
    post:
      summary: Close job
      description: This closes a completed job. In order for a job to be closed, it must be in a completed state. All content from the job will be removed when it is closed. Closing a job guarantees that no additional work will be done against the job.
      tags:
      - Jobs
      operationId: closeJob
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - in: path
        name: translationJobUid
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NullDataJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
        '400':
          description: Validation error when closing a job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
              examples:
                response:
                  value:
                    response:
                      code: VALIDATION_ERROR
                      errors:
                      - message: Only a job that is COMPLETE can be closed.
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
  /jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/cancel:
    post:
      summary: Cancel job
      description: 'This cancels a job. All content within the job will be removed from the job and the content will be unauthorized.


        If a job is successfully cancelled, a `200` response status will be returned. When the system can''t quickly cancel the job, a `202` response is returned. The response contains a link to check the progress of the request. When a `202` is received, the process of canceling and removing the content from the job will not be complete until the returned process has completed.

        '
      tags:
      - Jobs
      operationId: cancelJob
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - in: path
        name: translationJobUid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelJobRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NullDataJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
        '202':
          description: ACCEPTED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncProcessJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: ACCEPTED
                      data:
                        message: This process will continue asynchronously and may take up to a few minutes.
                        url: https://api.smartling.com/jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/processes/{processUid}
        '400':
          description: Validation error when cancelling a job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
              examples:
                response:
                  value:
                    response:
                      code: VALIDATION_ERROR
                      errors:
                      - message: Job can be cancelled only in DRAFT, AWAITING_AUTHORIZATION, or IN_PROGRESS statuses
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Response'
              examples:
                response:
                  value:
                    response:
                      code: AUTHENTICATION_ERROR
                      errors:
                      - details: {}
                        key: invalid_token
                        message: Invalid token
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
  /jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}/authorize:
    post:
      summary: Authorize job
      description: This authorizes all content within a job. A job can only be authorized when it has content and is in an AWAITING_AUTHORIZATION state.
      tags:
      - Jobs
      operationId: authorizeJob
      parameters:
      - name: projectId
        description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
        in: path
        required: true
        schema:
          type: string
      - in: path
        name: translationJobUid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeJobRequest'
        description: The payload to use when authorizing a job. If no target locales and workflows are provided, the empty body `{}` should be provided. Smartling will authorize the job for the default workflows for the given project.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NullDataJobResponse'
              examples:
                response:
                  value:
                    response:
                      code: SUCCESS
        '400':
          description: Validation error when authorizing a job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
              examples:
                response:
                  value:
                    code: VALIDATION_ERROR
                    errors:
                    - key: null
                      message: Job can be authorized only in AWAITING_AUTHORIZATION status(es).
                      details: null
        '401':
          $ref: '#/components/responses/Error401ResponseDefinition'
        '429':
          $ref: '#/components/responses/Error429ResponseDefinition'
        '500':
          $ref: '#/components/responses/Error500ResponseDefinition'
  /jobs-api/v3/projects/{projectId}/jobs/{translationJobUid}:
    get:
      summary: Get details of job
      description: This gets the details of a job such as job name, description, due date, and reference number.
      tags:
      - Jobs
      operationId: getJobDetails
     

# --- truncated at 32 KB (132 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smartling/refs/heads/main/openapi/smartling-jobs-api-openapi.yml