Skip to content

Send fax

The service task “Send fax” delivers a document as a fax directly from a Pantarey process. Invoices, delivery notes or confirmations can be sent automatically to one or several fax numbers – without dedicated fax hardware and without a separate contract with a fax provider.

Activation required

Sending faxes is a paid add-on and has to be enabled for the tenant. Please contact Pantarey to request activation. Once enabled, the service task becomes available in the process designer.

Input parameters

{
  "document": {
    "referenceId": "ref-invoice-2026-04711"
  },
  "recipients": "0049530000000",
  "options": {
    "title": "Invoice 4711"
  },
  "test": false,
  "waitForResult": true,
  "pollMaxAttempts": 24,
  "pollIntervalMs": 30000,
  "skipGrayscaleConversion": false
}

Description:

  • document: The document to be sent. Two variants are supported:
    • { "referenceId": "..." } – reference to a file already stored in Pantarey.
    • { "content": "<base64>", "contentType": "application/pdf", "filename": "invoice.pdf" } – inline document.
  • recipients: One or more recipient fax numbers. Accepted formats:
    • a single number as a string: "0049530000000"
    • a single object: { "faxNumber": "0049...", "name": "...", "recipientReference": "..." }
    • an array of either form (mixed allowed). Maximum 10 recipients per job.
  • options (optional): Additional fax job options such as title, faxHeader, stationID.
  • test (optional, default false): When set to true, the sandbox system is used. No costs are charged and no real fax is delivered. Recommended for tests and development processes.
  • waitForResult (optional, default true): When true, the task waits until the fax job reaches a terminal status (finished, error, canceled). When false, it returns immediately after job creation.
  • pollMaxAttempts / pollIntervalMs (optional): Control the number and interval of status polls while waiting.
  • skipGrayscaleConversion (optional, default false): Controls the automatic grayscale conversion for PDFs (see the next section). When set to true, the original PDF is forwarded to the fax service unchanged.

Supported document types

Type MIME type
PDF application/pdf
TIFF image/tiff
PNG image/png
GIF image/gif
HTML text/html
Plain text/plain

Automatic grayscale conversion

Many fax services cannot process color PDFs correctly – the recipient receives black or empty pages. To avoid this, every PDF is automatically converted to a grayscale version before being sent.

The automatic conversion is applied only when all of the following conditions are met:

  • the document contentType is application/pdf
  • the document is supplied via referenceId (not as inline base64 content)
  • skipGrayscaleConversion is not set or set to false

The converted file is used solely for the fax delivery. The original remains untouched in storage. Images, HTML and plain text are not converted.

When should skipGrayscaleConversion: true be used?

When the PDF has already been converted in an earlier step (for example via Convert PDF to grayscale) or is already pure black and white. In those cases, skipping the redundant conversion saves processing time.

Output

When waitForResult: true, the result contains both the job ID and the final status including per-recipient details:

{
  "jobId": "0d139d2c-4a10-11f1-b04d-001851328a39",
  "status": "finished",
  "errorCode": null,
  "statistics": {
    "pages": 1,
    "recipientCount": 1,
    "recipientCountSuccessful": 1,
    "recipientCountError": 0
  },
  "recipients": [
    {
      "faxNumber": "0049530000000",
      "resultCode": 0,
      "resultText": "OK"
    }
  ]
}

Description:

  • jobId: Unique identifier of the fax job. This ID is required to query the status later (see Query fax status).
  • status: Final status of the job – finished, error or canceled. With waitForResult: false this may also be scheduling, scheduled or processing.
  • errorCode: null on success, otherwise an error code from the delivery service.
  • statistics: Number of pages and recipients (total, successful, failed).
  • recipients: Per-recipient delivery result. resultCode 0 and resultText "OK" indicate a successful single delivery. Note: a job status finished does not automatically mean every single delivery succeeded – the recipients list must be checked in addition.

JSONata examples

Single recipient from process data

{
  "document": {
    "referenceId": $.invoice.pdfRef.referenceId
  },
  "recipients": $.customer.faxNumber,
  "options": {
    "title": "Invoice " & $.invoice.number
  },
  "test": false
}

Multiple recipients with names

{
  "document": {
    "referenceId": $.dispatchNote.pdfRef.referenceId
  },
  "recipients": [
    { "faxNumber": $.customer.faxNumber,  "name": $.customer.name },
    { "faxNumber": $.warehouse.faxNumber, "name": $.warehouse.name }
  ],
  "options": {
    "title": "Dispatch note " & $.dispatchNote.number,
    "faxHeader": true
  }
}

Notes

  • Activation required: The service task is only available after the fax feature has been enabled for the tenant. Please contact Pantarey to request activation.
  • Sandbox vs. live: With test: true a test send is triggered without delivery cost. Test jobs are kept separate from live operations in the report and are not actually delivered.
  • Fax numbers: National (0530…) and international notations (0049530…, +49530…) are accepted. If no country prefix is given, the configured default dialling code is added automatically.
  • At most 10 recipients per job. For larger distributions, send multiple jobs.
  • Wait time: With waitForResult: true the task blocks for up to roughly 12 minutes waiting for the terminal status (default: 24 attempts × 30 seconds). If that is not enough, the most recent status is returned and the job can be re-checked later via Query fax status.

Tip

A common process combination:

  1. Generate PDF from Handlebars template – produces the document.
  2. Send fax – delivers the PDF to the recipient fax number.
  3. (Optional) Query fax status – when the result should be checked later, e.g. after a wait or timer event.