Preview designs with data

Last updated on August 22, 2025
•
3 minutes to read

The endpoints POST /api/atoms/v1/designs/render-proof and POST /api/atoms/v1/designs/render-preview allows you to preview the resulting designs. To apply variable data printing, their request body must include a variableData array with the updated field values.

Obtaining a list of variables

You may want to verify the variables before rendering. To do so, get the list of variable fields by using the endpoint GET /api/atoms/v1/designs/{id}/variables.

This endpoint will return all design fields created with the <VAR> marker in Adobe software, isVariable property in the Design Editor, and Variable field toggle in the Template Editor. The response contains an array of design items.

{
    "name": "string",  // The name of the variable field, e.g., "Job title"
    "value": "string", // The value of the variable field, e.g., "junior copywriter"
    "type": "string"   // The type of the variable field, one of "Text", "InString", "ImagePlaceholder", "Image"
}

Defining values for variables

To change the data in the rendered design copies, use the same variable item model, where the name and type are case-sensitive strings. The type can be one of "Image", "ImagePlaceholder", "Text", or "InString".

The value for text types is a plain string, and for image types, it contains a path to an image. You can specify paths to images located in the following sources:

Public images uploaded to the Assets > Images:

"public:folder-path/file-name.jpg"
User images upload to their private storage:

"user:folder-path/file-name.jpg"
Images in an external system:

"https://example.com/image.jpg"

Providing the endpoint parameters

To render private designs, you must specify a designId and ownerId (the user who created the design). To populate text and images, provide a variableData array defining field values. You need also to specify the rendering config in the request body:

{
  "designId": "6698b073306ecea21de39b11",
  "ownerId": "crisford",
  "variableData": [
    {
      "name": "Company Name",
      "type": "Text",
      "value": "CA Printing Inc."
    },
    {
      "name": "CompanyLogo",
      "type": "Image",
      "value": "https://example.com/logos/company.png"
    }
  ],
  "renderingConfig": {
    "surfaceIndex": 0,
    "width": 300,
    "height": 300,
    "fileFormat": "Jpeg"
  }
}

When renderingConfig.surfaceIndex is undefined, the response will contain the first design page for the "Jpeg", "Png", and "Tiff" formats and all the pages for "Pdf".

Making a call

Now, let's generate a preview with the provided parameters.

curl -X \
POST "https://api.customerscanvashub.com/api/atoms/v1/designs/render-preview" \
-H  "accept: application/octet-stream" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d '{
  "designId": "6698b073306ecea21de39b11",
  "ownerId": "crisford",
  "variableData": [
    {
      "name": "Company Name",
      "type": "Text",
      "value": "CA Printing Inc."
    },
    {
      "name": "CompanyLogo",
      "type": "Image",
      "value": "https://example.com/logos/company.png"
    }
  ],
  "renderingConfig": {
    "surfaceIndex": 0,
    "width": 300,
    "height": 300,
    "fileFormat": "Jpeg"
  }
}'

POST https://api.customerscanvashub.com/api/atoms/v1/designs/render-preview
Content-Type: application/json
{
  "designId": "6698b073306ecea21de39b11",
  "ownerId": "crisford",
  "variableData": [
    {
      "name": "Company Name",
      "type": "Text",
      "value": "CA Printing Inc."
    },
    {
      "name": "CompanyLogo",
      "type": "Image",
      "value": "https://example.com/logos/company.png"
    }
  ],
  "renderingConfig": {
    "surfaceIndex": 0,
    "width": 300,
    "height": 300,
    "fileFormat": "Jpeg"
  }
}

// Define request body as JSON string
var body = """
{
  "designId": "6698b073306ecea21de39b11",
  "ownerId": "crisford",
  "variableData": [
    {
      "name": "Company Name",
      "type": "Text",
      "value": "CA Printing Inc."
    },
    {
      "name": "CompanyLogo",
      "type": "Image",
      "value": "https://example.com/logos/company.png"
    }
  ],
  "renderingConfig": {
    "surfaceIndex": 0,
    "width": 300,
    "height": 300,
    "fileFormat": "Jpeg"
  }
}
""";

// Send request
var preview = await designAtomsServiceApiClient.RenderDesignPreviewAsync(body: body);

// Define request body
const body = {
    designId: "6698b073306ecea21de39b11",
    ownerId: "crisford",
    variableData: [
        { name: "Company Name", type: "Text", value: "CA Printing Inc." },
        { name: "CompanyLogo", type: "Image", value: "https://example.com/logos/company.png" }
    ],
    renderingConfig: {
        surfaceIndex: 0,
        width: 300,
        height: 300,
        fileFormat: "Jpeg"
    }
};

// Send request
const preview = _designAtomsServiceApiClient.renderDesignPreview(null, null, body);

// Define request body
$data = [
    'designId' => '6698b073306ecea21de39b11',
    'ownerId' => 'crisford',
    'variableData' => [
        [
            'name' => 'Company Name',
            'type' => 'Text',
            'value' => 'CA Printing Inc.'
        ],
        [
            'name' => 'CompanyLogo',
            'type' => 'Image',
            'value' => 'https://example.com/logos/company.png'
        ]
    ],
    'renderingConfig' => [
        'surfaceIndex' => 0,
        'width' => 300,
        'height' => 300,
        'fileFormat' => 'Jpeg'
    ]
];

// Send request
$response = $designAtomsServiceApi->designAtomsServiceRenderDesignPreview(null, null, json_encode($data));

Preview designs with data

Obtaining a list of variables

Defining values for variables

Providing the endpoint parameters

Making a call

Was this page helpful?