Working with the Data Merge API

Data Merge

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).

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:

Consult this skeleton cURL request for more details.

Variable File Naming Support in Data Merge API

The Data Merge API supports variable file naming, allowing you to dynamically assign output file names using values from your input data.

How it works

Note: Only one variable file name column is allowed. If multiple columns have ‘&’ prefix the job will fail.

File Name Constraints

Certain special characters or words are not supported by the platform and are automatically normalized.

Here is a sample CSV file demonstrating a column header with prefix ‘&’. Records

Example of input payload which is same as it is currently.

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": "FileNames.csv"
    }
  ],
  "params": {
    "targetDocument": "dataMergeTemplate.indd",
    "outputMediaType": "image/png",
    "outputFolderPath": {OUTPUT_FOLDER_PATH},
    "outputFileBaseString": "merged",
    "dataSource": "FileNames.csv",
    "recordRange": "All"
    "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}/{outputs}"
    }
  ]
}'

When file naming is NOT supported

outputMediaType
params
JPEG (image/jpeg)
allowMultipleRecordsPerPage set to true
PNG (image/png)
allowMultipleRecordsPerPage set to true
PDF (application/pdf)
pagesPerDocument ≠ 1 and recordRange = "All"
pagesPerDocument ≠ 1 and recordRange = "1-2, 5"
allowMultipleRecordsPerPage set to true
InDesign (application/x-indesign)
pagesPerDocument ≠ 1 and recordRange = "All"
pagesPerDocument ≠ 1 and recordRange = "1-2, 5"
allowMultipleRecordsPerPage set to true

Why: Variable file naming gives each data row a single output file name via the & column, so it only applies when the merge job has a clear one row–to–one name mapping. If allowMultipleRecordsPerPage is true, several records can share a page, so row-level names are ambiguous. If pagesPerDocument is not 1, records are merged into multi-page output documents (and for PDF and InDesign you typically get one file per range folder), so many rows contribute to the same file and per-row file names are no longer meaningful. In those situations, variable file naming is not available for the affected output types.

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:

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

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:

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

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:

Example:

Case 2: Only outputFileBaseString Provided

When only outputFileBaseString is specified:

Example:

Case 3: Only outputFolderPath Provided

When only outputFolderPath is specified:

Example:

Case 4: Both Parameters Provided

When both parameters are specified:

Example:

Note:

Retrieve data merge tags

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

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
  }
}'