Developers

API quick start

Auto-generate personalized PDFs, images, and 3D previews.

PDFs

Personalia Content generation service enables PDF generation with dynamic content.

Javascript example

var data = {

  "TemplateId": YOUR_TEMPLATE_ID,

  "Fields": {

    "First Name": "Peter",

    "Machine": "AK-2000",

    "Color": "Brown"

 },

  "Output": {

    "Format": "PDF",

    "Quality": "Display"

  }

}

fetch('https://api.personalia.io/v1/content', {

  method: 'POST',

  body: JSON.stringify(data),

  headers: {

    'Content-Type' : 'application/json',

    'Authorization' : 'ApiKey ${YOUR_API_KEY}'

  }

})

PDF generation is done by sending a POST request (endpoint POST) with a template ID and a list of fields and values. These values can control the text, images, style and more.

The POST API responds with a request ID that is used by the GET API (endpoint GET) for fetching the request status. In addition, the GET API returns a single PDF file URL when the request is complete which includes all the pages.

Important: The URL is valid for 15 minutes.

For the API call, use your API key (see Personalia dashboard) & the specific Template ID with its input fields (see Templates and CPKGs).

Images

Personalia Content generation service enables image generation with dynamic content.

Javascript example

var data = {

  "TemplateId": YOUR_TEMPLATE_ID,

   "Fields": {

    "Product": "iron",

    "Offer": "20%",

    "Price": "$25",

    "Color": "blue",

    "Switch Sides": "1"

   },

  "Output": {

    "Format": "JPG",

    "Resolution": 150

  }

}

fetch('https://api.personalia.io/v1/content', {

  method: 'POST',

  body: JSON.stringify(data),

  headers: {

    'Content-Type' : 'application/json',

    'Authorization' : 'ApiKey ${YOUR_API_KEY}'

  }

})

Image generation is done by sending a POST request (endpoint POST) with a template ID and a list of fields and values. These values can control the text, images, style and more.

The POST API responds with a request ID that is used by the GET API (endpoint GET) for fetching the request status. In addition, the GET API returns a list of JPG or PNG URLs when the request is complete. The number of URLs depends on the number of pages in the template. A separate URL is generated per page.

Important: The list of URLs is valid for 15 minutes.

For the API call, use your API key (see Personalia dashboard) & the specific Template ID with its input fields (see Templates and CPKGs).

Field data type references

Personalia templates created in InDesign with uCreate are configured with input fields of different types (text, number, date, Boolean) that expect to receive values in a particular format:

  • Text - any text string including foreign characters.

  • Number - no comma separator, only 1 period (optional). Numbers can be positive or negative (e.g., 1000.50 or -2000). Maximum number of digits is 15. If longer numbers are required, the InDesign template should be set up with an input field type of text instead of number.

  • Date - in the format yyyy-mm-dd (e.g., 2023-10-30).

  • Boolean – valid values are 0 and 1 where 0 represents false and 1 represents true.

API reference

Personalia APIs are used to auto-generate personalized PDFs, images, and 3D previews.

Personalia's comprehensive API-first architecture allows rapid integration into almost any system, platform or process through simple APIs calls to create unique digital assets when required and on demand.

There are two types of content-generation APIs: POST and GET.

The create content API call (POST) submits a request for the creation of a personalized image or PDF document for a specific template. The API call receives the template's ID and field names with their values (which can be copied from the template preview page). It then returns a request ID to be used by the GET content API to retrieve the status and result of the request.

The get content API (GET) retrieves the status and eventually the result of a specific request to the create content API call. When the output is ready a URL containing the generated content is created.

APIs receive and return JSON objects. The "Content-Type" header with the "application/JSON" value should be added to all requests.

Additional APIs

Several other APIs are available for the developer, to assist in integration of Personalia.

API key validation API

Submits a request to validate that the API key exists. This is particularly useful for automation platforms (e.g., Zapier) which require validation of an API key before use. Please note that this API will only validate that the API key exists and not that it is valid for use against a specific template.

Fields list API

Provides the list of field names and their types of a single template. These are needed when using Personalia APIs from a 3rd party platform/system.

3D Previews

Personalia 3D visualizer service enables 3D previews with dynamic content.

Website

<html>

<head>

<meta charset="utf-8">

<title>3D Preview</title>

<!-- Call Personalia with your API Key -->

<script src="https://api.personalia.io/v1/visualizers/3d/standuppouch?apikey=YOUR-API-KEY"></script>

</head>

<body>

...

<!-- Show the model and pass optional display parameters -->

<x-visualizer-standuppouch id="sample" width="70vw" height="50vh" rotate-speed="5" tilt="{rX: 1, rY: 0, rZ: 0}" ambient-color="FFFFFF" ambient-light-brightness="2" add-surrounding-lights="true" camera-pos="{rX: 20, rY:270, rZ: 0}" src="../assets/StandUpPouch/StandUpPouch-chocolate.jpg"></x-visualizer-standuppouch>

...

</body>

</html>

To present your product (which is not one of the out-of-the-box models) in 3D, you need:

For the API call, use your API key (see Personalia dashboard) in the HTML snippet.

More topics

API documentation

Watch a video

Basic website integration

Salesforce integration