PDF Generation

To generate a PDF with the Placid REST API:

  1. Create an API project or add the API integration to your project in Placid
  2. Create and design your template(s)
  3. Send your data and customizations to the API
  4. Poll the GET endpoint for status updates or use a webhook to get the generated PDF file

{info} 1 PDF page = 2 credits

Switch to test mode for free watermarked previews!

Example Call

// - POST to endpoint `https://api.placid.app/api/rest/pdfs`

{
    ...

    "pages": [
        {
            "template_uuid": "jxac36kja",
            "layers": {
                "name": {
                    "text": "Jonathan Doe"
                },
                "course": {
                    "text": "has completed the online course « Authentic Business Branding » taught by Frida Baumann on January 24, 2023."
                },
                "signature-instructor": {
                    "image": "https://growthacademy.com/assets/instructors/sig/baumann.png"
                },
                "labelsignature-instructor": {
                    "text": "Frida Baumann, instructor"
                }
            },
        },
    ],

    ...

    // Options for filename, size modifications, export,..
}

The PDF object

Properties

{
    "id": 1,
    "status": "queued",
    "pdf_url": null,
    "polling_url": null
}
Field Values
id Unique pdf id for internal reference
status queued The request has been put into the queue.
finished The pdf has been created successfully.
error There was an error.
pdf_url URL to created pdf or null
polling_url Endpoint that you can GET poll for status updates

Create a PDF

Create a new pdf by using the following endpoint and request structure. PDFs are generated from one or more templates used as pages, filling their layers with your data.

Endpoint

Method URI
POST https://api.placid.app/api/rest/pdfs 
{
  "webhook_success": "https://webhook.url",
  "passthrough": null,

  "pages": [
    {
        "template_uuid": "<template_uuid>",
        "layers": {
            "title": {
                "text": "Lorem Ipsum"
            },
            "logo": {
                "image": "https://imageurl.png"
            },
            "qr-code": {
                "value": "https://qr-code.url"
            }
            ...
        },
    },
    // ...
  ],

  "modifications": {
  },
  "transfer": {
  }
}
Field Values Description
webhook_success Webhook URL After the PDF is created Placid will POST the response to this Webhook URL
passthrough string or array Any data added to this parameter will be saved and sent in any subsequent webhooks and requests for this PDF (max-length is 1024 characters)
pages array of page objects Your desired pages/templates; Add multiple templates to get a merged PDF
transfer Additionally transfer the generated PDF to your storage

PDF content

The content of your PDF will be defined by an array of templates in your pages object.

Field Values Description
pages.*.template_uuid The ID of the template used for your page
pages.*.layers View Layer Properties Dynamically change the content and properties of your template layers

Get your {template_uuid} from the template overview in the Templates tab of your Placid API project.

https://placid.app/images/placid-template-id.jpg

  • The API allows you to create a pdf from one or more pages / templates, merged in the order you define

Export / transfer

To transfer the generated video to your storage use the transfer object.

Field Values
transfer.to s3
transfer.key, transfer.secret Your credentials (Placid never stores them)
transfer.bucket Your bucket name
transfer.visibility public or private
transfer.path File path (Define the full pdf path starting from the root directory of your bucket, including filename and file extension. Placid will overwrite existing files in the specified directory!)

File modifications

To modify the generated pdf use the modifications object. These modifications override the template defaults.

Field Values
modifications.filename Filename of the generated PDF
modifications.image_quality Set image quality level high (default), medium, low
modifications.dpi Define the output DPI of the PDF. Allowed values are 96(default), 150, 300
modifications.color_mode Set to rgb (default) or cmyk
modifications.color_profile Beta feature: We additionally offer the selection of color profiles as a beta feature. If you're interested in testing it, please contact us 💬


Set one of the following color profiles

none (default)

RGB:
rgb-profile-1 - sRGB IEC61966-2.1
rgb-profile-2 - Adobe RGB (1998)
rgb-profile-3 - ProPhoto RGB

CMYK:
cmyk-profile-1 - ISO Coated v2 (ECI)
cmyk-profile-2 - ISO Coated v2 300% (ECI v2)
cmyk-profile-3 - Coated FOGRA39 300%
cmyk-profile-4 - U.S. Web Coated (SWOP 2006) 3v2
cmyk-profile-5 - Japan Color 2cmyk-profile-3011 Coated

Retrieve a PDF

This endpoint allows you to retrieve a PDF by providing their unique id. Refer to the object at the top of this page to see which properties are included with PDF objects.

Endpoint

Method URI
GET https://api.placid.app/api/rest/pdfs/{id}

Delete a PDF

This endpoint allows you to delete a PDF by providing its unique id. Once deleted, the PDF cannot be retrieved or used.

Endpoint

Method URI
DELETE https://api.placid.app/api/rest/pdfs/{id}

Response

  • Success: On successful deletion, the API will return a 204 No Content status code.
  • Not Found: If the PDF with the specified id does not exist, the API will return a 404 Not Found error.