# Payload Jobs (PDF + Word)

This page documents the payload-based job creation endpoints and the required `channelIdentifiers` per task and add-on.

These endpoints allow clients to submit jobs by providing structured payload data and, depending on the workflow input source, an optional document file.

For the full request and response schema, see:

- [Create Payload PDF Job](/public-api-production/openapi/jobs/jobscontroller_createpayloadpdfjob)
- [Create Payload Word Job](/public-api-production/openapi/jobs/jobscontroller_createpayloadwordjob)


| Workflow input source | Endpoint | Behavior |
|  --- | --- | --- |
| `PAYLOAD_PDF` | `POST /jobs/payload-pdf` | Creates the job and returns a presigned URL to upload the PDF file. |
| `PAYLOAD_WORD` | `POST /jobs/payload-word` | Creates the job immediately using payload and template data. No file upload is required. |


## Create Payload PDF Flow

Use `POST /jobs/payload-pdf` when the workflow input source is `PAYLOAD_PDF`.

The endpoint stores the payload and returns a `fileUploadUrl`.

Upload the PDF using HTTP `PUT` to the returned `fileUploadUrl`, with the raw PDF binary as the request body.

The job remains in `AWAITING_FILE_UPLOAD` for up to 2 hours. If no file is uploaded during that period, the job expires.

The `filename` must end with `.pdf`. Other extensions return `415 Unsupported Media Type`.

## Create Payload Word Flow

Use `POST /jobs/payload-word` when the workflow input source is `PAYLOAD_WORD`.

The endpoint stores the payload and creates the job immediately. No file upload step is required.

The payload must include `templateData`, which is used to generate the final document.

## Workflow Requirements

The workflow must:

- exist;
- be enabled;
- be validated;
- be accessible for the caller’s departments;
- use the input source matching the endpoint.


| Workflow input source | Required endpoint |
|  --- | --- |
| `PAYLOAD_PDF` | `POST /jobs/payload-pdf` |
| `PAYLOAD_WORD` | `POST /jobs/payload-word` |


## File Extension Rules

For `POST /jobs/payload-pdf`, the `filename` must end with `.pdf`.

Other file extensions return:

```http
415 Unsupported Media Type
```

## Address Rules for Print Tasks

If the workflow contains a print task, either `EASY_PRINT` or `EASY_PRINT_FR`, payload workflows must provide structured address identifiers.

Unstructured address identifiers are not allowed for payload workflows.

The following identifier is not allowed for payload workflows:

| Identifier | Reason |
|  --- | --- |
| `ADDRESS` | Payload workflows require structured address identifiers instead. |


Missing required structured address identifiers returns:

```http
400 Bad Request
```

## Structured Address Validation

For structured address identifiers:

- empty structured address identifiers are ignored;
- structured fields have maximum length limits;
- `ADDRESS_COUNTRY_CODE` is uppercased.


## Required Payload Channel Identifiers per Task

The rules below apply to the `payload.channelIdentifiers` array.

When multiple identifiers are listed with `AND`, all listed identifiers are required.

When a group is described as “at least one of”, one valid option from the group is required.

### `EASY_PRINT`

Requires structured address identifiers.

See [Structured address requirements](#structured-address-requirements).

### `EASY_PRINT_FR`

Requires structured address identifiers.

See [Structured address requirements](#structured-address-requirements).

### `EMAIL`

Required identifier:

- `EMAIL_ADDRESS`


### `ERDS`

Required identifier:

- `EMAIL_ADDRESS`


### `QERDS`

Required identifiers:

- `EMAIL_ADDRESS`


And at least one of:

- `COMPANY_IDENTIFICATION_NUMBER`
- `FIRST_NAME`, `LAST_NAME`, and `BIRTH_DATE`


### `EBOX`

At least one of:

- `NATIONAL_REGISTER_NUMBER`
- `COMPANY_IDENTIFICATION_NUMBER` and `EBOX_RECIPIENT_PARTITION`


### `DOCCLE`

Required identifiers:

- `DOCCLE_TOKEN_SET_VALUE1`
- `DOCCLE_TOKEN_SET_VALUE2`


Optional identifiers for payload workflows:

- `EMAIL_ADDRESS`
- `DOCCLE_RECEIVER_ID`


### `PEPPOL`

`PEPPOL` is not supported for payload workflows.

## Structured Address Requirements

Structured address requirements apply only to:

- `EASY_PRINT`
- `EASY_PRINT_FR`


### Always Required

The following identifiers are always required:

| Identifier |
|  --- |
| `ADDRESS_POSTAL_CODE` |
| `ADDRESS_CITY` |
| `ADDRESS_COUNTRY_CODE` |


### Identity Group

At least one of the following identity options is required:

| Option | Required Identifiers |
|  --- | --- |
| Company | `ADDRESS_COMPANY_NAME` |
| Person | `ADDRESS_FIRST_NAME` AND `ADDRESS_LAST_NAME` |


### Location Group

At least one of the following location options is required:

| Option | Required identifiers |
|  --- | --- |
| Street address | `ADDRESS_STREET` AND `ADDRESS_STREET_NUMBER` |
| PO box | `ADDRESS_PO_BOX` |


## Add-Ons

## Payment Collection (POM)

When `hasPom` is `true`, the following identifiers are required:

| Identifier |
|  --- |
| `INVOICE_AMOUNT` |
| `INVOICE_DUE_DATE` |
| `INVOICE_COMMUNICATION` |


Notes:

- `INVOICE_DESCRIPTION` is optional for payload-based workflows.
- `INVOICE_DESCRIPTION` is not validated as a required field.
- `INVOICE_DUE_DATE` is always required when payment collection is enabled.


## Workflow Collection (Invoice Tracking)

When invoice tracking is enabled, the following identifiers are required:

| Identifier |
|  --- |
| `INVOICE_REFERENCE` |
| `INVOICE_AMOUNT` |
| `INVOICE_DUE_DATE` |
| `INVOICE_COMMUNICATION` |


## Encryption

All `channelIdentifiers` and `extraInfoIdentifiers` accept an optional `isEncrypted` flag.

The system encrypts values when:

- `isEncrypted` is set to `true`; or
- the identifier kind is `NATIONAL_REGISTER_NUMBER`.


`NATIONAL_REGISTER_NUMBER` is always encrypted, regardless of the value of `isEncrypted`.