Working with the Data Merge API

Data merge generates variations of a template document from data in a provided CSV file.

The Data Merge API 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.

The Data Merge API includes two components to complete the task: the data merge and the data merge tags.

Quickstart

The example below takes the data from Directory_Names.csv and creates different variations of dataMergeTemplate.indd. The output is a merged INDD file of all variations.

Merge data

This cURL command merges the data (from Directory_Names.csv into dataMergeTemplate.indd).

Copy
curl --location --request POST 'https://indesign.adobe.io/v3/merge-data' \
--header 'Authorization: Bearer {YOUR_OAUTH_TOKEN}' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "assets": [
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "dataMergeTemplate.indd"
    },
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "Directory_Names.csv"
    }
  ],
  "params": {
    "targetDocument": "dataMergeTemplate.indd",
    "outputMediaType": "application/x-indesign",
    "outputFolderPath": {OUTPUT_FOLDER_PATH},
    "outputFileBaseString": "merged",
    "dataSource": "Directory_Names.csv",
    "hyphenationSettings": {
      "afterFirst": 3,
      "beforeLast": 3,
      "wordsLongerThan": 6,
      "ladderLimit": 2,
      "zone": 0.15,
      "capitalizedWords": false,
      "lastWord": true,
      "acrossColumns": false,
      "dictionarySettings": [
        {
          "language": "English: USA",
          "wordList": ["~word1", "ex~word2"]
        },
        {
          "language": "English: UK",
          "wordList": ["~word3", "~word4"]
        }
      ]
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "{PUT-SIGNED_URL}"
      },
      "source": "{OUTPUT_FOLDER_PATH}/merged-1.pdf"
    }
  ]
}'
Copied to your clipboard
curl --location --request POST 'https://indesign.adobe.io/v3/merge-data' \
--header 'Authorization: Bearer {YOUR_OAUTH_TOKEN}' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "assets": [
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "dataMergeTemplate.indd"
    },
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "Directory_Names.csv"
    }
  ],
  "params": {
    "targetDocument": "dataMergeTemplate.indd",
    "outputMediaType": "application/x-indesign",
    "outputFolderPath": {OUTPUT_FOLDER_PATH},
    "outputFileBaseString": "merged",
    "dataSource": "Directory_Names.csv",
    "hyphenationSettings": {
      "afterFirst": 3,
      "beforeLast": 3,
      "wordsLongerThan": 6,
      "ladderLimit": 2,
      "zone": 0.15,
      "capitalizedWords": false,
      "lastWord": true,
      "acrossColumns": false,
      "dictionarySettings": [
        {
          "language": "English: USA",
          "wordList": ["~word1", "ex~word2"]
        },
        {
          "language": "English: UK",
          "wordList": ["~word3", "~word4"]
        }
      ]
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "{PUT-SIGNED_URL}"
      },
      "source": "{OUTPUT_FOLDER_PATH}/merged-1.pdf"
    }
  ]
}'

The raw data may include three parts:

• assets - Input assets for the request.
• params - Information about what to do with the input assets.
• outputs - Specify locations where the output assets are uploaded. Without an outputs parameter, the output assets are stored in a temporary repository, and a pre-signed URL will be shared for those assets, which will be valid for 24hrs.

Consult this skeleton cURL request for more details.

Multiline Records in Data Merge API

Multiline content can be included by enclosing field values in double quotes (""), and any line breaks within those values will be preserved during processing.

Here is a sample CSV file demonstrating multiline records compatible with the Data Merge API. Notice how line breaks within a field are preserved by enclosing the entire field value with double quotes:

Copy
Name,Address,Comments
Alice Smith,123 Main St,"First line of comment.
Second line of comment."
Bob Johnson,"456 Oak Ave
Suite 12
Riverside, CA","Single line comment."
Cara Lee,Newport,comment value
Copied to your clipboard
Name,Address,Comments
Alice Smith,123 Main St,"First line of comment.
Second line of comment."
Bob Johnson,"456 Oak Ave
Suite 12
Riverside, CA","Single line comment."
Cara Lee,Newport,comment value

• Each field containing actual line breaks is wrapped in double quotes.
• The Data Merge API correctly interprets newlines within quoted fields as part of the field value.
• Unquoted field values (such as Bob Johnson's "Single line comment.") will be treated as single-line.

When uploading this CSV to the Data Merge API, the merged output will preserve all newlines in the relevant fields.

UTF-8 encoded CSV file support

The Data Merge API now supports CSV files encoded in UTF-8. This enables you to work with documents containing special characters such as emojis and international text, improving compatibility across different languages and symbols.

When preparing your CSV, ensure it is saved as UTF-8 (with or without BOM), especially if your data includes non-English or special characters.

Example UTF-8 CSV file

Below is a sample CSV file containing special (UTF-8) characters:

Copy
Name,Message,Emoji
Juan Pérez,"¡Bienvenido a la demostración!",😊
Chloé Dubois,"Bonjour de Paris!","🌍"
李华,"你好，世界","🌏"
Miyuki Satō,"東京へようこそ!","🗾"
Copied to your clipboard
Name,Message,Emoji
Juan Pérez,"¡Bienvenido a la demostración!",😊
Chloé Dubois,"Bonjour de Paris!","🌍"
李华,"你好，世界","🌏"
Miyuki Satō,"東京へようこそ!","🗾"

• Fields like Name, Message, or Emoji may contain accented Latin characters or emoji, which are represented correctly in UTF-8 encoding.
• Save your file as UTF-8 in your text editor (for example, in VSCode: File > Save with Encoding > UTF-8).

When you upload this UTF-8 encoded CSV to the Data Merge API, the merged document will preserve these special characters and emojis in the output. Make sure applied font is available and have the required glyphs.

Output Path Variations in Data Merge API

When using the Data Merge API, the output file paths are determined by the outputFolderPath and outputFileBaseString parameters in the request. Here are the different scenarios and their corresponding output paths:

Case 1: Both Parameters Missing

When neither outputFolderPath nor outputFileBaseString is provided:

• Output is created in a temporary folder with a random number prefix (e.g. tmp0696)
• The output filename is derived from the original document filename

Example:

• Source: Template.indd
• Output: tmp0696/range1/Template.indd
• In case of multiple output documents/pdf:
  • tmp0696/range1/Template.indd
  • tmp0696/range2/Template.indd
  • tmp0696/range1/Template.pdf
  • tmp0696/range2/Template.pdf
• For PNG/JPEG outputs:
  • tmp0696/range1/Template.png
  • tmp0696/range1/Template2.png
  • tmp0696/range1/Template3.png

Case 2: Only outputFileBaseString Provided

When only outputFileBaseString is specified:

• Output is created in a temporary folder with a random number prefix (e.g. tmp0696)
• Filename uses the provided base string

Example:

• Source: Template.indd
• outputFileBaseString: "MergedOutput"
• Output: tmp0696/range1/MergedOutput.indd
• In case of multiple output documents/pdf:
  • tmp0696/range1/MergedOutput.indd
  • tmp0696/range2/MergedOutput.indd
  • tmp0696/range1/MergedOutput.pdf
  • tmp0696/range2/MergedOutput.pdf
• For PNG/JPEG outputs:
  • tmp0696/range1/MergedOutput.png
  • tmp0696/range1/MergedOutput2.png
  • tmp0696/range1/MergedOutput3.png

Case 3: Only outputFolderPath Provided

When only outputFolderPath is specified:

• Output is created in the specified folder
• Filename is derived from the original template

Example:

• Source: Template.indd
• outputFolderPath: "ResultFolder"
• Output: ResultFolder/range1/Template.indd
• In case of multiple output documents/pdf:
  • ResultFolder/range1/Template.indd
  • ResultFolder/range2/Template.indd
  • ResultFolder/range1/Template.pdf
  • ResultFolder/range2/Template.pdf
• For PNG/JPEG outputs:
  • ResultFolder/range1/Template.png
  • ResultFolder/range1/Template2.png
  • ResultFolder/range1/Template3.png

Case 4: Both Parameters Provided

When both parameters are specified:

• Output is created in the specified folder
• Filename uses the provided base string

Example:

• Source: Template.indd
• outputFileBaseString: "MergedOutput"
• outputFolderPath: "ResultFolder"
• Output: ResultFolder/range1/MergedOutput.indd
• In case of multiple output documents/pdf:
  • ResultFolder/range1/MergedOutput.indd
  • ResultFolder/range2/MergedOutput.indd
  • ResultFolder/range1/MergedOutput.pdf
  • ResultFolder/range2/MergedOutput.pdf
• For PNG/JPEG outputs:
  • ResultFolder/range1/MergedOutput.png
  • ResultFolder/range1/MergedOutput2.png
  • ResultFolder/range1/MergedOutput3.png

Note:

• When generating multiple documents or different output formats (PNG/JPEG), a subfolder is created for each range, such as range1, range2, range3, etc., to maintain organized and unique filenames.
• The rangeX subfolders (e.g. range1, range2, etc.) are created based on the pagesPerDocument value defined in the request. For example, if pagesPerDocument is set to 10 and the total number of records for the data merge is 20, then two folders—range1 and range2—will be generated. These will contain the output for record ranges 1–10 and 11–20, respectively.
• The number and type of output files within each rangeX folder depends on the selected outputMediaType:
  • If outputMediaType is application/x-indesign, or application/pdf, each rangeX folder will contain one InDesign document/pdf.
  • If outputMediaType is image/png or image/jpeg, each rangeX folder will contain multiple image files, corresponding to each record in that range (e.g., 10 images for 10 records).

Retrieve data merge tags

This cURL command retrieves the data merge tags from the document.

Copy
curl --location --request POST 'https://indesign.adobe.io/v3/merge-data-tags' \
--header 'Authorization: Bearer {YOUR_OAUTH_TOKEN}' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "assets": [
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "dataMergeTemplate.indd"
    },
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "batang.ttc"
    }
  ],
  "params": {
    "outputMediaType": "application/x-indesign",
    "targetDocument": "dataMergeTemplate.indd",
    "includePageItemIdentifiers": true
  }
}'
Copied to your clipboard
curl --location --request POST 'https://indesign.adobe.io/v3/merge-data-tags' \
--header 'Authorization: Bearer {YOUR_OAUTH_TOKEN}' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "assets": [
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "dataMergeTemplate.indd"
    },
    {
      "source": {
        "url": "{PRE-SIGNED_URL}",
        "storageType": "Azure"
      },
      "destination": "batang.ttc"
    }
  ],
  "params": {
    "outputMediaType": "application/x-indesign",
    "targetDocument": "dataMergeTemplate.indd",
    "includePageItemIdentifiers": true
  }
}'

Last updated 2/10/2026

Was this helpful?

Yes

No