Request reference

Fields, response and status codes of a render request.

A render request is a POST with a JSON body, both with the npm client and with fetch. The applicationId is part of the URL.

POST {API_BASE_URL}/api/applications/{applicationId}/pdf-files

Request

FieldTypeRequiredDescription
applicationIdstringYesID of the application (part of the path).
payloadsarrayYesOne entry per document to render.
payloads[].idstringYesYour own ID for the document, echoed in the reply.
payloads[].templateIdstringYesID of the template to render.
payloads[].dataobjectYesTemplate variables, as a plain JSON object.
{
    "payloads": [
        {
            "id": "0f7c2d20-1f6e-4f3f-9c14-8d6d4c5f1a2b",
            "templateId": "8b9f0f4a-6f21-4a1e-9d7a-1c2f3e4d5a6b",
            "data": { "customerName": "Jane Doe", "total": "249.00" }
        }
    ]
}

data is an object, not a JSON string. Its keys are the template variables; values may be strings, numbers, booleans, arrays or nested objects. See Template syntax.

Response

201 Created with one entry per rendered document:

FieldTypeDescription
generatedDocumentsarrayOne entry per document of the request.
generatedDocuments[].idstringThe id you sent for that document.
generatedDocuments[].fileIdstringID the service gave the rendered file.
generatedDocuments[].templateIdstringThe template used for that document.
generatedDocuments[].urlstringEndpoint the PDF is served from.
{
    "generatedDocuments": [
        {
            "id": "0f7c2d20-1f6e-4f3f-9c14-8d6d4c5f1a2b",
            "fileId": "f2c1a0d4-7c2e-4e1a-9a9b-3d5f6c7b8a90",
            "templateId": "8b9f0f4a-6f21-4a1e-9d7a-1c2f3e4d5a6b",
            "url": "https://…/api/applications/3b7f1c9e-2d4a-4b8c-9e1f-0a2b3c4d5e6f/pdf-files/f2c1a0d4-7c2e-4e1a-9a9b-3d5f6c7b8a90"
        }
    ]
}

url is an endpoint of this service, not a public link. Requesting it needs your API key, see Download a PDF.

Status codes

StatusMeaning
201Every document of the request was rendered.
400Malformed applicationId, malformed request body or the payloads array is empty.
401No API key sent.
404Template is not found.
403Unknown or deleted API key.
500Rendering failed, e.g. the template has invalid Liquid syntax.

A batch is all-or-nothing: if one document fails, the request fails and no URLs are returned, not even for the documents that rendered fine.

Previous

Download a PDF

Next

Template syntax

On this page