Phrase Orders API

openapi: 3.0.3
info:
  title: Phrase Strings API Reference Accounts Orders API
  version: 2.0.0
  description: Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase Strings for your account.
  contact:
    name: Phrase Support
    url: https://developers.phrase.com/api/
    email: support@phrase.com
  x-logo:
    url: https://developers.phrase.com/images/phrase-logo.svg
    backgroundColor: '#03eab3'
    altText: Phrase Strings
  termsOfService: https://phrase.com/terms/
  license:
    name: MIT
    url: https://choosealicense.com/licenses/mit/
servers:
- url: https://api.phrase.com/v2
  description: EU production server
- url: https://api.us.app.phrase.com/v2
  description: US production server
security:
- Token: []
- Basic: []
tags:
- name: Orders
  description: "### List of categories [TextMaster]\n\nWhen ordering translations from TextMaster, you need to specify a category ID along with your order. See this list for information on the category ID and their equivalent description.\n\n<div class=\"table-responsive\">\n  <table class=\"basic-table\">\n    <thead>\n      <tr class=\"basic-table__row basic-table__row--header\">\n        <th class=\"basic-table__cell basic-table__cell--header\">Category ID</th>\n        <th class=\"basic-table__cell basic-table__cell--header\">Description</th>\n      </tr>\n    </thead>\n    <tbody>\n      <tr><td class=\"basic-table__cell\">C001</td><td class=\"basic-table__cell\">Agriculture</td></tr>\n      <tr><td class=\"basic-table__cell\">C002</td><td class=\"basic-table__cell\">Aerospace</td></tr>\n      <tr><td class=\"basic-table__cell\">C003</td><td class=\"basic-table__cell\">Animals/Pets/Plants</td></tr>\n      <tr><td class=\"basic-table__cell\">C004</td><td class=\"basic-table__cell\">Arts/Culture/Literature</td></tr>\n      <tr><td class=\"basic-table__cell\">C005</td><td class=\"basic-table__cell\">Automotive/Transportation</td></tr>\n      <tr><td class=\"basic-table__cell\">C006</td><td class=\"basic-table__cell\">Computers/Technology/Software</td></tr>\n      <tr><td class=\"basic-table__cell\">C007</td><td class=\"basic-table__cell\">Telecom</td></tr>\n      <tr><td class=\"basic-table__cell\">C008</td><td class=\"basic-table__cell\">Real Estate/Construction/Building</td></tr>\n      <tr><td class=\"basic-table__cell\">C009</td><td class=\"basic-table__cell\">Consumer Goods</td></tr>\n      <tr><td class=\"basic-table__cell\">C010</td><td class=\"basic-table__cell\">Education</td></tr>\n      <tr><td class=\"basic-table__cell\">C011</td><td class=\"basic-table__cell\">Entertainment</td></tr>\n      <tr><td class=\"basic-table__cell\">C012</td><td class=\"basic-table__cell\">Ecology/Environment</td></tr>\n      <tr><td class=\"basic-table__cell\">C013</td><td class=\"basic-table__cell\">Health/Biotechnology/Pharma</td></tr>\n      <tr><td class=\"basic-table__cell\">C014</td><td class=\"basic-table__cell\">Internet</td></tr>\n      <tr><td class=\"basic-table__cell\">C015</td><td class=\"basic-table__cell\">Policy/Government/Public</td></tr>\n      <tr><td class=\"basic-table__cell\">C016</td><td class=\"basic-table__cell\">Publishing/Media/Communication</td></tr>\n      <tr><td class=\"basic-table__cell\">C017</td><td class=\"basic-table__cell\">Religion</td></tr>\n      <tr><td class=\"basic-table__cell\">C018</td><td class=\"basic-table__cell\">Food/Beverages</td></tr>\n      <tr><td class=\"basic-table__cell\">C019</td><td class=\"basic-table__cell\">Retail</td></tr>\n      <tr><td class=\"basic-table__cell\">C020</td><td class=\"basic-table__cell\">Fashion/Luxury/Textiles</td></tr>\n      <tr><td class=\"basic-table__cell\">C021</td><td class=\"basic-table__cell\">Travel/Tourism</td></tr>\n      <tr><td class=\"basic-table__cell\">C022</td><td class=\"basic-table__cell\">Natural Resources/Energy</td></tr>\n      <tr><td class=\"basic-table__cell\">C023</td><td class=\"basic-table__cell\">Banking/Financial Services/Insurance</td></tr>\n      <tr><td class=\"basic-table__cell\">C024</td><td class=\"basic-table__cell\">Legal Affairs/Tax/Law</td></tr>\n      <tr><td class=\"basic-table__cell\">C025</td><td class=\"basic-table__cell\">Raw Materials/Industrial Goods</td></tr>\n      <tr><td class=\"basic-table__cell\">C026</td><td class=\"basic-table__cell\">Lifestyle/Leisure/Hobbies</td></tr>\n      <tr><td class=\"basic-table__cell\">C027</td><td class=\"basic-table__cell\">Sports</td></tr>\n      <tr><td class=\"basic-table__cell\">C028</td><td class=\"basic-table__cell\">Home/Family/Friends/Children</td></tr>\n      <tr><td class=\"basic-table__cell\">C029</td><td class=\"basic-table__cell\">Economy/Financial Markets</td></tr>\n      <tr><td class=\"basic-table__cell\">C030</td><td class=\"basic-table__cell\">Science</td></tr>\n      <tr><td class=\"basic-table__cell\">C031</td><td class=\"basic-table__cell\">Human Resources/Employment</td></tr>\n      <tr><td class=\"basic-table__cell\">C032</td><td class=\"basic-table__cell\">Adult (Pornography, Violence, etc.)</td></tr>\n    </tbody>\n  </table>\n</div>\n"
paths:
  /projects/{project_id}/orders:
    get:
      summary: List orders
      description: List all orders for the given project.
      operationId: orders/list
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/X-PhraseApp-OTP'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - description: specify the branch to use
        example: my-feature-branch
        name: branch
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/translation_order'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            Link:
              $ref: '#/components/headers/Link'
            Pagination:
              $ref: '#/components/headers/Pagination'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      x-code-samples:
      - lang: Curl
        source: "curl \"https://api.phrase.com/v2/projects/:project_id/orders?branch=my-feature-branch\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
      - lang: CLI v2
        source: 'phrase orders list \

          --project_id <project_id> \

          --branch my-feature-branch \

          --access_token <token>'
      x-cli-version: '2.5'
    post:
      summary: Create a new order
      description: Create a new order. Access token scope must include `orders.create`.
      operationId: order/create
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/X-PhraseApp-OTP'
      - $ref: '#/components/parameters/project_id'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/translation_order'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      x-code-samples:
      - lang: Curl
        source: "curl \"https://api.phrase.com/v2/projects/:project_id/orders\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X POST \\\n  -d '{\"branch\":\"my-feature-branch\",\"name\":\"Welcome message translations\",\"lsp\":\"textmaster\",\"source_locale_id\":\"abcd1234abcd1234abcd1234abcd1234\",\"target_locale_ids\":[\"1234abcd1234abcd1234abcd1234abcd\",\"abcd1234abcd1234abcd1234abcd1234\"],\"translation_type\":\"premium\",\"tag\":\"my-awesome-feature\",\"message\":\"Please make everything sound really nice :)\",\"styleguide_id\":\"1234abcd1234abcd1234abcd1234abcd\",\"category\":\"C021\"}' \\\n  -H 'Content-Type: application/json'"
      - lang: CLI v2
        source: 'phrase orders create \

          --project_id <project_id> \

          --data ''{"branch":"my-feature-branch", "name":"Welcome message translations", "lsp":"textmaster", "source_locale_id":"abcd1234abcd1234abcd1234abcd1234", "target_locale_ids": "1234abcd1234abcd1234abcd1234abcd,abcd1234abcd1234abcd1234abcd1234", "translation_type":"premium", "tag":"my-awesome-feature", "message": "Please make everything sound really nice :)", "styleguide_id":"1234abcd1234abcd1234abcd1234abcd", "category":"C021"}'' \

          --access_token <token>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              title: order/create/parameters
              required:
              - name
              - lsp
              properties:
                branch:
                  description: specify the branch to use
                  type: string
                  example: my-feature-branch
                name:
                  description: 'the name of the order, default name is: Translation order from ''current datetime'''
                  type: string
                  example: Welcome message translations
                lsp:
                  description: Name of the LSP that should process this order. Can be one of gengo, textmaster.
                  type: string
                  example: textmaster
                source_locale_id:
                  description: Source locale for the order. Can be the name or id of the source locale. Preferred is id.
                  type: string
                  example: abcd1234abcd1234abcd1234abcd1234
                target_locale_ids:
                  description: List of target locales you want the source content translate to. Can be the name or id of the target locales. Preferred is id.
                  type: array
                  items:
                    type: string
                  example:
                  - 1234abcd1234abcd1234abcd1234abcd
                  - abcd1234abcd1234abcd1234abcd1234
                translation_type:
                  description: 'Name of the quality level, availability depends on the LSP. Can be one of:  standard, pro (for orders processed by Gengo) and one of regular, premium, enterprise (for orders processed by TextMaster)'
                  type: string
                  example: premium
                tag:
                  description: Tag you want to order translations for.
                  type: string
                  example: my-awesome-feature
                message:
                  description: Message that is displayed to the translators for description.
                  type: string
                  example: Please make everything sound really nice :)
                styleguide_id:
                  description: Style guide for translators to be sent with the order.
                  type: string
                  example: 1234abcd1234abcd1234abcd1234abcd
                unverify_translations_upon_delivery:
                  description: Unverify translations upon delivery.
                  type: boolean
                  example: null
                include_untranslated_keys:
                  description: Order translations for keys with untranslated content in the selected target locales.
                  type: boolean
                  example: null
                include_unverified_translations:
                  description: Order translations for keys with unverified content in the selected target locales.
                  type: boolean
                  example: null
                category:
                  description: Category to use (required for orders processed by TextMaster).
                  type: string
                  example: C021
                quality:
                  description: Extra proofreading option to ensure consistency in vocabulary and style. Only available for orders processed by TextMaster.
                  type: boolean
                  example: null
                priority:
                  description: Indicates whether the priority option should be ordered which decreases turnaround time by 30%. Available only for orders processed by TextMaster.
                  type: boolean
                  example: null
      x-cli-version: '2.5'
  /projects/{project_id}/orders/{id}:
    get:
      summary: Get a single order
      description: Get details on a single order.
      operationId: order/show
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/X-PhraseApp-OTP'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/id'
      - description: specify the branch to use
        example: my-feature-branch
        name: branch
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/translation_order'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      x-code-samples:
      - lang: Curl
        source: "curl \"https://api.phrase.com/v2/projects/:project_id/orders/:id?branch=my-feature-branch\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
      - lang: CLI v2
        source: 'phrase orders show \

          --project_id <project_id> \

          --id <id> \

          --branch my-feature-branch \

          --access_token <token>'
      x-cli-version: '2.5'
    delete:
      summary: Cancel an order
      description: Cancel an existing order. Must not yet be confirmed.
      operationId: order/delete
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/X-PhraseApp-OTP'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/id'
      - description: specify the branch to use
        example: my-feature-branch
        name: branch
        in: query
        schema:
          type: string
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      x-code-samples:
      - lang: Curl
        source: "curl \"https://api.phrase.com/v2/projects/:project_id/orders/:id\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X DELETE \\\n  -d '{\"branch\":\"my-feature-branch\"}' \\\n  -H 'Content-Type: application/json'"
      - lang: CLI v2
        source: 'phrase orders delete \

          --project_id <project_id> \

          --id <id> \

          --branch my-feature-branch \

          --access_token <token>'
      x-cli-version: '2.5'
  /projects/{project_id}/orders/{id}/confirm:
    patch:
      summary: Confirm an order
      description: Confirm an existing order and send it to the provider for translation. Same constraints as for create.
      operationId: order/confirm
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/X-PhraseApp-OTP'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/translation_order'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      x-code-samples:
      - lang: Curl
        source: "curl \"https://api.phrase.com/v2/projects/:project_id/orders/:id/confirm\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X PATCH \\\n  -d '{\"branch\":\"my-feature-branch\"}' \\\n  -H 'Content-Type: application/json'"
      - lang: CLI v2
        source: 'phrase orders confirm \

          --project_id <project_id> \

          --id <id> \

          --data ''{"branch":"my-feature-branch"}'' \

          --access_token <token>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              title: order/confirm/parameters
              properties:
                branch:
                  description: specify the branch to use
                  type: string
                  example: my-feature-branch
      x-cli-version: '2.5'
components:
  responses:
    '429':
      description: Rate Limiting
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/X-Rate-Limit-Limit'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/X-Rate-Limit-Remaining'
        X-Rate-Limit-Reset:
          $ref: '#/components/headers/X-Rate-Limit-Reset'
    '204':
      description: The resource was deleted successfully.
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/X-Rate-Limit-Limit'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/X-Rate-Limit-Remaining'
        X-Rate-Limit-Reset:
          $ref: '#/components/headers/X-Rate-Limit-Reset'
    '404':
      description: Not Found
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/X-Rate-Limit-Limit'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/X-Rate-Limit-Remaining'
        X-Rate-Limit-Reset:
          $ref: '#/components/headers/X-Rate-Limit-Reset'
    '400':
      description: Bad request
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/X-Rate-Limit-Limit'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/X-Rate-Limit-Remaining'
        X-Rate-Limit-Reset:
          $ref: '#/components/headers/X-Rate-Limit-Reset'
  headers:
    X-Rate-Limit-Reset:
      description: Timestamp of end of current time period as UNIX timestamp, see [Rate Limiting](/en/api/strings/pagination#rate-limiting)
      schema:
        type: integer
    X-Rate-Limit-Remaining:
      description: The number of remaining requests in the current period
      schema:
        type: integer
    X-Rate-Limit-Limit:
      description: The number of allowed requests in the current period
      schema:
        type: integer
    Link:
      description: 'Links to related resources, in the format defined by

        [RFC 5988](https://tools.ietf.org/html/rfc5988#section-5).

        This will include a link with relation type `next` to the

        next page, if there is a next page.'
      schema:
        type: string
    Pagination:
      description: Pagination details for navigating through a collection of resources, provided in JSON format.
      schema:
        type: object
        properties:
          total_count:
            description: Total count of items in the collection.
            type: integer
            example: 10
          total_pages_count:
            description: Total number of pages available for the collection.
            type: integer
            example: 2
          current_page:
            description: The current page number.
            type: integer
            example: 1
          current_per_page:
            description: Number of items currently displayed per page.
            type: integer
            example: 5
          previous_page:
            description: Page number of the previous page, if available.
            type: integer
          next_page:
            description: Page number of the next page, if available.
            type: integer
            example: 2
  schemas:
    styleguide_preview:
      type: object
      title: styleguide_preview
      properties:
        id:
          type: string
        title:
          type: string
      example:
        id: abcd1234cdef1234abcd1234cdef1234
        title: My Style Guide
    locale_preview:
      type: object
      title: locale_preview
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
      example:
        id: abcd1234cdef1234abcd1234cdef1234
        name: English
        code: en-GB
    translation_order:
      type: object
      title: translation_order
      properties:
        id:
          type: string
        name:
          type: string
        lsp:
          type: string
        amount_in_cents:
          type: integer
        currency:
          type: string
        message:
          type: string
        state:
          type: string
        translation_type:
          type: string
        progress_percent:
          type: integer
        source_locale:
          $ref: '#/components/schemas/locale_preview'
        target_locales:
          type: array
          items:
            $ref: '#/components/schemas/locale_preview'
        tag:
          type: string
        styleguide:
          $ref: '#/components/schemas/styleguide_preview'
        unverify_translations_upon_delivery:
          type: boolean
        quality:
          type: boolean
        priority:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        id: 30AB4884
        lsp: gengo
        amount_in_cents: 1152
        currency: usd
        message: Please make everything sound really nice :)
        state: confirmed
        translation_type: pro
        progress_percent: 50
        source_locale:
          id: abcd1234cdef1234abcd1234cdef1234
          name: en
          code: en-GB
        target_locales:
        - id: abcd1234cdef1234abcd1234cdef1234
          name: de
          code: de-DE
        - id: abcd1234cdef1234abcd1234cdef1234
          name: fr
          code: fr-FR
        tag: latest-upload
        styleguide:
          id: abcd1234cdef1234abcd1234cdef1234
          title: My Styleguide
        unverify_translations_upon_delivery: true
        quality: true
        priority: true
        created_at: '2015-01-28T09:52:53Z'
        updated_at: '2015-01-28T09:52:53Z'
  parameters:
    X-PhraseApp-OTP:
      in: header
      name: X-PhraseApp-OTP
      description: Two-Factor-Authentication token (optional)
      required: false
      allowEmptyValue: false
      schema:
        type: string
    id:
      in: path
      name: id
      description: ID
      required: true
      schema:
        type: string
    page:
      in: query
      name: page
      description: Page number
      required: false
      allowEmptyValue: false
      schema:
        type: integer
      example: 1
    per_page:
      in: query
      name: per_page
      description: Limit on the number of objects to be returned, between 1 and 100. 25 by default
      required: false
      allowEmptyValue: false
      schema:
        type: integer
      example: 25
    project_id:
      in: path
      name: project_id
      description: Project ID
      required: true
      schema:
        type: string
  securitySchemes:
    Token:
      type: apiKey
      in: header
      name: Authorization
      description: Enter your token in the format `token TOKEN`
    Basic:
      type: http
      scheme: basic
x-tagGroups:
- name: Core Resources
  tags:
  - Projects
  - Locales
  - Keys
  - Translations
  - Uploads
  - Tags
  - Custom Metadata Properties
  - Blacklisted Keys
  - Versions / History
- name: Workflows
  tags:
  - Spaces
  - Jobs
  - Job Comments
  - Job Locales
  - Job Templates
  - Job Template Locales
  - Organization Job Templates
  - Organization Job Template Locales
  - Comments
  - Comment Reactions
  - Comment Replies
  - Branches
- name: Quality
  tags:
  - Glossaries
  - Glossary Terms
  - Glossary Term Translations
- name: Integrations
  tags:
  - Webhooks
  - Distributions
  - Releases
  - Release Triggers
- name: Ordering
  tags:
  - Orders
  - Style guides
- name: User management
  tags:
  - Authorizations
  - Users
  - Accounts
  - Members
  - Invitations
- name: Screenshots
  tags:
  - Screenshots
  - Screenshot Markers
- name: Misc
  tags:
  - Formats
- name: Figma Attachments
  tags:
  - Figma attachments
  - Key's Figma attachments