Skip to content

Generate a PDF from a template

POST
/templates/{id}/versions/{version}/generate
curl --request POST \
--url https://necodoc.example.com/api/v1/templates/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/versions/latest/generate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "data": {}, "filename": "example", "async": false, "output": { "pdfa": "2b", "pdfua": true, "certify": true, "lang": "example" }, "subject": "example", "response": "pdf", "signing": true }'

Validates data against the version’s fields (422 with every field error), then renders it. output.lang makes the PDF in another language than the template’s: formatting, the template’s translations and text direction follow it.

id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
version
required
Any of:
string
Allowed value: latest

A version number, or latest.

Media typeapplication/json

Data for a published template version.

object
data
object
key
additional properties
filename
string
>= 1 characters <= 200 characters
async

Answer 202 with the generation id at once instead of waiting.

boolean
output

Overrides the version’s output settings. lang makes the PDF in that language (formatting, translations, text direction).

object
pdfa
Any of:
string
Allowed values: 2b 2u
pdfua

Tagged PDF/UA-1. HTML renders only: overlays and packets have no structure to tag.

boolean
certify

Certify with the server’s certificate (PAdES, DocMDP: form filling and signing stay allowed).

boolean
lang

The document language (BCP 47): date, number and currency formatting, translations, text direction, and the PDF language.

string
/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/
subject

Who the document is about (an email, a customer number), for erasure.

string
>= 1 characters <= 200 characters
response

pdf returns the bytes; json returns the generation and a link.

string
default: pdf
Allowed values: pdf json
signing
Any of:
boolean

Rendered. response: pdf (default) returns the bytes; response: json returns the generation. With signing, the signing package.

string format: binary
X-Generation-Id
string

The generation log entry.

X-Page-Count
integer

Pages in the PDF.

Still queued or running (async, or the wait ran out). Poll the generation.

Media typeapplication/json
object
generationId
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
status
required
string
Allowed values: queued running success error cancelled

Example

{
"status": "queued"
}

Missing, unknown, revoked or expired key, or the key’s account is disabled.

Media typeapplication/json
object
error
required
string
code
required
string
fieldErrors
object
key
additional properties
Array<string>
generationId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example generated

{
"error": "example",
"code": "example",
"fieldErrors": {
"additionalProperty": [
"example"
]
},
"generationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

The key lacks the scope, role, template or source address this call needs.

Media typeapplication/json
object
error
required
string
code
required
string
fieldErrors
object
key
additional properties
Array<string>
generationId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example generated

{
"error": "example",
"code": "example",
"fieldErrors": {
"additionalProperty": [
"example"
]
},
"generationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

Not found, or not yours.

Media typeapplication/json
object
error
required
string
code
required
string
fieldErrors
object
key
additional properties
Array<string>
generationId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example generated

{
"error": "example",
"code": "example",
"fieldErrors": {
"additionalProperty": [
"example"
]
},
"generationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

The template is archived.

Media typeapplication/json
object
error
required
string
code
required
string
fieldErrors
object
key
additional properties
Array<string>
generationId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example generated

{
"error": "example",
"code": "example",
"fieldErrors": {
"additionalProperty": [
"example"
]
},
"generationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

Invalid request or data; fieldErrors lists each.

Media typeapplication/json
object
error
required
string
code
required
string
fieldErrors
object
key
additional properties
Array<string>
generationId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example generated

{
"error": "example",
"code": "example",
"fieldErrors": {
"additionalProperty": [
"example"
]
},
"generationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

Rate limit exceeded.

Media typeapplication/json
object
error
required
string
code
required
string
fieldErrors
object
key
additional properties
Array<string>
generationId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example generated

{
"error": "example",
"code": "example",
"fieldErrors": {
"additionalProperty": [
"example"
]
},
"generationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}
Retry-After
integer

Seconds until the key may call again.