openapi: 3.2.0
info:
  description: Firefly Service's RESTful InDesign API offers resources to automate tedious, time-consuming design tasks through scalable cloud services, encouraging more personalization at scale, creative automation, and faster content delivery.
  version: ''
  title: Firefly Services - InDesign Data Merge API
  termsOfService: https://www.adobe.com/content/dam/cc/en/legal/terms/enterprise/pdfs/PSLT-AdobeCreativeAPI-WW-2024v2.pdf
  contact:
    email: idservices@adobe.com
servers:
- url: https://indesign.adobe.io
security:
- AccessToken: []
  X-Api-Key: []
tags:
- name: Data Merge
  description: Create document variations from CSV data and InDesign templates. Supports UTF-16BE encoding for CSV files, which is necessary for languages or characters requiring multi-byte representation. For plain English characters, the CSV will function correctly even without this encoding.
paths:
  /v3/merge-data:
    post:
      summary: Perform a data merge
      description: 'Creates InDesign documents or PDFs by merging CSV data with InDesign templates. Supports multiple output formats: JPEG (`image/jpeg`), PNG (`image/png`), PDF (`application/pdf`), and InDesign (`application/x-indesign`).'
      operationId: dataMerge
      tags:
      - Data Merge
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeDataRequest'
        description: This job request object specifies parameters for merging the data with the given template.
        required: true
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/merge-data-tags:
    post:
      summary: Get data merge tags
      description: Retrieves the data merge tags from a document.
      operationId: dataMergeTags
      tags:
      - Data Merge
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeDataTagsRequest'
        description: This job request object specifies parameters for retrieving the data merge tags.
        required: true
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The format of the content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Retry-After:
          schema:
            type: integer
          description: The number of seconds until the user should try again.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    Accepted:
      description: The job has been accepted for processing.
      content:
        application/json:
          schema:
            properties:
              jobId:
                type: string
                description: The job ID.
              statusUrl:
                type: string
                description: The status URL.
      headers:
        link:
          schema:
            type: string
          description: The status URL for a retry.
        retry-after:
          schema:
            type: integer
          description: The number of seconds until the user should try again.
        Content-Type:
          schema:
            type: string
          description: The type of content that is returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    BadParams:
      description: Bad Parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
  schemas:
    BaseJobRequest:
      description: The base job request for any job.
      required:
      - assets
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/InputAsset'
          description: Information about the assets, which will be used to process the job.
        params:
          type: object
          properties:
            generalSettings:
              description: General settings.
              type: object
              properties:
                fonts:
                  description: Settings related to fonts. It is recommended to include fonts to avoid missing fonts warnings when processing the job.
                  type: object
                  properties:
                    fontsDirectories:
                      description: This lists the font directories for the input InDesign documents. "Document Fonts" in parallel to the document will continue to work even without specifying them.  <br></br> If none are specified, a temporary base directory (working directory) will be considered as a font directory.
                      type: array
                      items:
                        type: string
                        description: This provides a path to a directory relative to a temporary base directory (working directory) where the fonts can be found. It cannot go up using '..' or '/'. Should be a valid path. For specifying a working directory, mention '.'.
                links:
                  description: Settings related to links.
                  type: object
                  properties:
                    replaceLinks:
                      type: array
                      items:
                        type: object
                        required:
                        - targetDocument
                        - mapping
                        properties:
                          targetDocument:
                            description: The document in which the relinking is to be done. Relinking of assets is required to ensure that there are no missing links in the output document.
                            type: string
                          mapping:
                            type: array
                            items:
                              type: object
                              required:
                              - newAssetRelativePath
                              properties:
                                newAssetRelativePath:
                                  type: string
                                  description: This provides a path relative to a temporary base directory (working directory) where the asset to be linked to can be found. It cannot go up using '..' or '/'. Should be a valid file name.
                                currentURI:
                                  type: string
                                  description: The existing URI of the link that needs relinking. If multiple links with this URI are found, all will be relinked. If `linkID` is provided, this attribute will be ignored. Either `currentURI` or `linkID` should be present.
                                linkID:
                                  type: integer
                                  description: The ID of the link which is to be relinked. If `currentURI` is also provided, it will be ignored. Either `currentURI` or `linkID` should be present.
                appLogs:
                  description: Describes parameters regarding application logs.
                  type: object
                  properties:
                    logsRelativePath:
                      type: string
                      description: This provides a path to a file, relative to the temporary base directory (working directory). This file is where the application's logs are to be dumped.
    HyphenationLanguage:
      type: string
      description: Supported hyphenation dictionary languages.
      enum:
      - Arabic
      - Bengali (India)
      - Bulgarian
      - Burmese (Myanmar [Burma])
      - Catalan
      - Croatian
      - Czech
      - Danish
      - 'Dutch: 2005 Reform'
      - 'Dutch: Old Rules'
      - 'English: Canadian'
      - 'English: UK'
      - 'English: USA'
      - 'English: USA Legal'
      - 'English: USA Medical'
      - Estonian
      - Finnish
      - French
      - 'French: Canadian'
      - 'German: 1996 Reform'
      - 'German: 2006 Reform'
      - 'German: Austria 2006 Reform'
      - 'German: Old Rules'
      - 'German: Swiss'
      - 'German: Swiss 2006 Reform'
      - Greek
      - Gujarati (India)
      - Hebrew
      - Hindi (India)
      - Hungarian
      - Indonesian (Indonesia)
      - Italian
      - Kannada (India)
      - Khmer (Cambodia)
      - Lao (Laos)
      - Latvian
      - Lithuanian
      - Malayalam (India)
      - Marathi (India)
      - 'Norwegian: Bokmål'
      - 'Norwegian: Nynorsk'
      - Oriya (India)
      - Polish
      - Portuguese
      - 'Portuguese: Brazilian'
      - 'Portuguese: Orthographic Agreement'
      - Punjabi (India)
      - Romanian
      - Russian
      - Sinhala (Sri Lanka)
      - Slovak
      - Slovenian
      - Spanish
      - Swedish
      - Tamil (India)
      - Telugu (India)
      - Thai
      - Turkish
      - Ukrainian
      - Vietnamese
    BaseJobRequestWithOutput:
      allOf:
      - $ref: '#/components/schemas/BaseJobRequest'
      - description: The base job request for any job with the option to specify output URLs.
        type: object
        properties:
          outputs:
            type: array
            items:
              $ref: '#/components/schemas/OutputAsset'
    MergeDataTagsRequest:
      allOf:
      - $ref: '#/components/schemas/BaseJobRequest'
      - description: Filters according to which the information related to data merge tags would be retrieved.
        type: object
        required:
        - params
        properties:
          params:
            type: object
            required:
            - targetDocument
            properties:
              targetDocument:
                description: The target document that will have its tags extracted.
                type: string
              dataSource:
                description: The data source file to be used for extracting and matching the tags.
                type: string
              filter:
                description: The filter applied for tags. Accepts multiple values.
                type: array
                example:
                - text
                - image
                default:
                - all
                items:
                  type: string
                  enum:
                  - all
                  - text
                  - image
                  - qr
              includePageItemIdentifiers:
                type: boolean
                description: If true, the information for associated page items is added to the tags extracted from the document.
                default: false
    MergeDataRequest:
      allOf:
      - $ref: '#/components/schemas/BaseJobRequestWithOutput'
      - description: Inputs for the data merge request.
        type: object
        required:
        - params
        properties:
          params:
            type: object
            required:
            - targetDocument
            - dataSource
            properties:
              targetDocument:
                description: The tagged document to be used as the template for merging.
                type: string
              dataSource:
                description: The data source files to be used.
                type: string
              outputMediaType:
                description: The type of output.
                type: string
                enum:
                - image/jpeg
                - image/png
                - application/pdf
                - application/x-indesign
                default: application/x-indesign
              exportSettings:
                type: object
                description: The settings corresponding to the output format.
                properties:
                  jobOptionsFile:
                    type: string
                    description: File path reference to a `.joboptions` file (Adobe PDF preset file) containing custom PDF export settings. This file must be included as part of the input assets. It defines detailed PDF output configurations such as compression, color management, and security settings. When provided, this takes precedence over the `pdfPreset` attribute. Only applicable when generating PDF output.
                    default: PDF preset `High Quality Print` will be used if not provided.
                  pdfPreset:
                    type: string
                    description: The PDF export style to be used. This is relevant if `outputMediaType` is `application/pdf`.
                    default: High Quality Print
                    enum:
                    - High Quality Print
                    - PDF/X-1a:2001
                    - PDF/X-3:2002
                    - PDF/X-4:2008
                    - Press Quality
                    - Smallest File Size
                  quality:
                    type: string
                    description: Defines the quality of the output for JPEG and PNG formats.
                    default: medium
                    enum:
                    - low
                    - medium
                    - high
                    - maximum
                  linkImages:
                    description: If `true`, links images to the target document. If `false`, embeds linked images already referred in the target document.  Only relevant if `outputMediaType` is `application/x-indesign`.
                    type: boolean
                    default: false
              recordRange:
                description: The ranges of records to process for this job. Value can be `All`, along with numeral ranges. For example, '1-2, 5'.
                type: string
                default: All
              allowMultipleRecordsPerPage:
                description: If `true`, will show as many records as will fit on a page.
                type: boolean
                default: false
              multipleRecordLayoutOptions:
                description: The options to be used when `allowMultipleRecordsPerPage` is set to `true`.
                type: object
                properties:
                  arrangeBy:
                    description: 'The order that records will be arranged in the target document.

                      * `rows_first` - Arranges records by row.

                      * `columns_first` - Arranges records by column.

                      '
                    type: string
                    default: rows_first
                    enum:
                    - rows_first
                    - columns_first
                  bottomMargin:
                    description: The offset value of the bottom margin in the target document. The values can be specified like `1 pt`, `1 pica`, `1`, etc. If a number is mentioned in the string, it will be used as a value in pica.
                    type: string
                  topMargin:
                    description: The offset value of the top margin in the target document.  The values can be specified like `1 pt`, `1 pica`, `1`, etc. If a number is mentioned in the string, it will be used as a value in pica.
                    type: string
                  leftMargin:
                    description: The offset value of the left margin in the target document. The values can be specified like `1 pt`, `1 pica`, `1`, etc. If a number is mentioned in the string, it will be used as a value in pica.
                    type: string
                  rightMargin:
                    description: The offset value of the right margin in the target document. The values can be specified like `1 pt`, `1 pica`, `1`, etc. If a number is mentioned in the string, it will be used as a value in pica.
                    type: string
                  columnSpacing:
                    description: The amount of spacing between columns of records in the target document.  The values can be specified like `1 pt`, `1 pica`, `1`, etc. If a number is mentioned in the string, it will be used as a value in pica.
                    type: string
                  rowSpacing:
                    description: The amount of spacing between rows of records in the target document.  The values can be specified like `1 pt`, `1 pica`, `1`, etc. If a number is mentioned in the string, it will be used as a value in pica.
                    type: string
              imagePlacementOptions:
                description: These are the options for image placement which will be used while merging images in the document.
                type: object
                properties:
                  centerImage:
                    description: If true, this centers the image in the frame while preserving the frame size as content size and proportions. If the content is larger than the frame, content around the edges is obscured by the bounding box of the frame. <br></br> This won't work when `fittingOption` is `Content_Aware_Fit`.
                    type: boolean
                    default: false
                  fittingOption:
                    description: 'The method of fitting content in a frame.

                      * `content_aware_fit` - Selects best crop region of the content for the frame based on Adobe Sensei. This preserves frame size but it might scale the content size. If this fitting is set, the `centerImage` property is turned-off.

                      * `fill_proportional` - Resizes content to fill the frame while preserving the proportions of the content. If the content and frame have different proportions, some of the content is obscured by the bounding box of the frame.

                      * `fit_content_to_frame` - Resizes content to fit the frame. Content that is a different size than the frame appears stretched or squeezed.

                      * `fit_frame_to_content` - Resizes the frame so it fits the content.

                      * `honor_existing_style` - Applies the frame fitting based on existing settings applied on the original frame.

                      * `preserve_sizes` - Preserves the original sizes of the frame and the content. Content that is larger than the frame is obscured around the edges.

                      * `proportional` - Resizes content to fit the frame while preserving content proportions. If the content and frame have different proportions, an empty space occurs in the frame.

                      '
                    type: string
                    default: proportional
                    enum:
                    - content_aware_fit
                    - fill_proportional
                    - fit_content_to_frame
                    - fit_frame_to_content
                    - honor_existing_style
                    - preserve_sizes
                    - proportional
                  linkImages:
                    description: This applies to the images being brought in the document while merging. If true, this links images to the target document. If false, it embeds images in the target document.
                    type: boolean
                    default: false
              hyphenationSettings:
                description: Hyphenation settings to control word breaking and hyphenation behavior during merge.
                type: object
                properties:
                  afterFirst:
                    type: integer
                    description: Minimum number of characters at the start of a word before a hyphen may be inserted.
                  beforeLast:
                    type: integer
                    description: Minimum number of characters at the end of a word after a hyphen.
                  wordsLongerThan:
                    type: integer
                    description: Minimum word length for hyphenation to apply.
                  ladderLimit:
                    type: integer
                    description: Maximum allowed consecutive hyphenated lines.
                  zone:
                    type: number
                    description: Whitespace ratio allowed at the end of a line before hyphenation begins (0–1).
                  capitalizedWords:
                    type: boolean
                    description: If true, allows hyphenation of capitalized words.
                  lastWord:
                    type: boolean
                    description: If true, allows hyphenation of the last word in a paragraph.
                  acrossColumns:
                    type: boolean
                    description: If true, allows hyphenation across columns.
                  dictionarySettings:
                    type: array
                    description: Special hyphenation definitions by language.
                    items:
                      type: object
                      required:
                      - language
                      - wordList
                      properties:
                        language:
                          $ref: '#/components/schemas/HyphenationLanguage'
                        wordList:
                          type: array
                          description: List of special hyphenation definitions (use `~` to mark break points, e.g., `Know~how`, `check~in`. Put `~` at the beginning of the word to exclude it from hyphenation, e.g., `~Wallstreet`, `~Starbucks`).
                          items:
                            type: string
              pagesPerDocument:
                description: The maximum number of pages per document.
                type: integer
                default: By default this would not be applicable.
              removeBlankLines:
                description: If true, removes blank lines caused by empty fields.
                type: boolean
                default: false
              convertUrlToHyperlink:
                description: If true, all URLs in the merged document are converted into hyperlinks.
                type: boolean
                default: true
              outputFileBaseString:
                type: string
                description: The name of the output file.
                default: It is derived from the original document filename.
              outputFolderPath:
                type: string
                description: The path of the output folder.
                default: A unique temporary folder name would be created.
    OutputAsset:
      description: The URL where the output assets are to be posted after the job is processed.
      type: object
      required:
      - destination
      - source
      properties:
        destination:
          type: object
          required:
          - url
          properties:
            url:
              type: string
              description: The URL of the asset.
            storageType:
              type: string
              description: This is an optional parameter, however IT IS RECOMMENDED to provide this information.
              enum:
              - Azure
              - Dropbox
              - AWS
        source:
          type: string
          description: This provides a path relative of the output where the resource would be generated. It cannot go up using '..' or '/'. Should be a valid file name.
    InputAsset:
      type: object
      description: The URL where the asset will be fetched.
      required:
      - source
      properties:
        source:
          type: object
          required:
          - url
          properties:
            url:
              type: string
              description: The pre-signed URL of the input asset. This is the URL of the asset that will be downloaded and acted upon during the job.
        destination:
          type: string
          description: This provides a path relative to a temporary base directory (working directory) where the resource would be downloaded. This would be used to identify the assets within the parameters. It cannot go up using '..' or '/'. Should be a valid file name.
    Error:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: string
      required:
      - message
      - error_code
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
      description: The Adobe-generated access token, S2S format.
    X-Api-Key:
      type: apiKey
      name: x-api-key
      in: header
      description: The client ID for authentication.