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.

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