Skip to main content
cURL
Try it live: PDF to E-Invoice API Tester. Submit a conversion request from your browser.

POST /v1/pdf/convert/to/e-invoice

This endpoint embeds customer-provided invoice XML into a source PDF, converts the document to PDF/A-3, and validates the result with veraPDF and Mustang. The XML determines the detailed conformance level, attachment metadata and embedded XML filename. The endpoint does not generate invoice XML or compare invoice amounts in the XML with the visual PDF content.

Quick start

Provide the source PDF URL, a matching invoice XML URL, and the profile family. Use exactly facturx or zugferd for profile.
Request body
Both profile families use the XML guideline identifier to select the supported conformance level. The recognized levels are MINIMUM, BASIC WL, BASIC, EN16931 and EXTENDED. An unknown guideline identifier does not silently fall back to BASIC. Both families currently use factur-x.xml as the embedded filename.
See URL input and request limits for source PDF and request limits. Invoice XML has a separate 5 MiB limit.

Asynchronous only

This endpoint has no synchronous mode and no async parameter. Every request runs in the background, and the first response returns a jobId rather than the PDF or report URL.
An accepted job follows these stages unless input inspection, conversion or validation fails:
  1. PDF.co accepts the request and returns its jobId.
  2. The invoice XML is inspected and embedded during PDF/A-3 conversion.
  3. veraPDF, Mustang and attachment-integrity checks validate the output.
  4. The job is finalized and returns the terminal result.
Retrieve the final result through Background Job Check, or provide a callback URL. See Webhooks & Callbacks. Only working means check again; success, failed and aborted are terminal. A polling timeout does not cancel the job. Keep its ID to resume checking later.

Request body

Attributes are case-sensitive and should be inside JSON for POST request. for example: { "url": "https://example.com/file1.pdf" } There are no query parameters.
string
required
URL of the source PDF. The URL must be reachable by PDF.co. Use httpusername and httppassword if the URL requires HTTP authentication. A temporary or presigned URL is also supported.
string
required
Supported invoice XML formats: Factur-X or ZUGFeRD.Provide the URL of your XML file as the value. Use a public or temporary presigned XML URL. The source PDF HTTP credentials do not apply to this URL. XML is limited to 5 MiB and must be a supported CrossIndustryInvoice document without DTD or entity declarations. Malformed XML, missing or duplicate guideline identifiers, and unsupported profiles are rejected. The XML determines the detailed profile, conformance level, and canonical embedded filename.
string
required
profile selects the invoice family. It is distinct from the profiles configuration parameter used by other endpoints.
Invoice profile family. Use exactly facturx or zugferd. This value identifies the expected family; the detailed conformance level is derived from the XML and is not silently defaulted.The XML may use any of these supported conformance profiles: MINIMUM, BASIC WL, BASIC, EN16931, or EXTENDED.
string
HTTP authentication username for the source PDF URL only. This does not unlock a password-protected PDF or apply to xml_url.
string
HTTP authentication password for the source PDF URL only. This does not unlock a password-protected PDF or apply to xml_url.
string
Callback URL notified when the asynchronous job finishes. See Webhooks & Callbacks.
string
Output file name. The endpoint appends .pdf when needed. If omitted, it derives the name from url when possible.
integer
default:"60"
Number of minutes before the temporary output URL expires. After this period, generated files are deleted from PDF.co Temporary Files Storage. The maximum retention depends on your subscription plan. To store permanent input files (e.g. re-usable images, pdf templates, documents) consider using PDF.co Built-In Files Storage.

Responses

The initial response confirms that the job was accepted, returns its jobId, and assigns the planned output file names. It does not guarantee that these files will be produced. Both file links are available when conversion and all required validation succeed. Job IDs, timing, versions and balances in the examples are illustrative.
Submission response
name and validationReportName are assigned when the job is accepted, so you can record the planned output file names before the job finishes. The matching url and validationReportUrl are not known at this point and are returned only if the corresponding files are produced.
When conversion and all required validation succeed, Background Job Check and the callback payload return the converted PDF, validation summary and report, as shown below. Fields can be absent when inspection, conversion or validation fails before the corresponding result is available.
Final job result
Submission errors and failed jobs are different. HTTP 200 from job-check can contain status: failed. Read the job status and message. The response panel shows submission HTTP responses. Error messages summarize the shared Response Codes; actual message text may differ by failure.

Understanding the validation result

Input rejection or failure before validation

Missing required request fields or an unsupported profile value can be rejected before a job is created. An accepted job can also fail later because the source PDF is signed or encrypted, the XML cannot be downloaded or parsed, or conversion cannot complete. These failures can return neither the converted PDF nor a validation report. Read the terminal message and stop polling once the job is failed or aborted.

Compliant output

Use the result as an e-invoice only when status is success and isCompliant is true. The service checks PDF/A conformance, Mustang PDF/XML/overall results and embedded-attachment integrity. It does not compare business values between the visible PDF and the XML.

Non-compliant output or validation error

If the combined result is non-compliant, the e-invoice job ends with status: failed. A validator that cannot complete also leaves a failed job, with compliance unknown. This differs from ordinary PDF/A conversion, which can return a non-compliant output with status: success. Do not rely on an artifact returned for diagnosis as a valid e-invoice. Failure responses can omit file links and validation details. Check whether validationReportUrl is available before attempting to download it.

Detailed validation report

Download the JSON report from validationReportUrl to inspect its components.veraPDF and components.Mustang evidence. The job-check response contains the summary rather than the report’s components object. Mustang can include advisory notices even when its overall status is valid. A successful validation result does not establish compliance with every legal, market or trading-partner requirement. Make sure the customer-provided XML matches the invoice shown in the PDF.

Charges and refunds

The processing charge is 100 credits per asynchronous submission, regardless of page count. See Credits per API Function. Completion, callbacks, internal retries and recovery do not add processing charges. A new submission is a new billable API call. Normal job-check polling fees are separate. A refundable terminal failure returns the processing debit once. The first failed job-check response can therefore report credits: -100; later checks do not refund the same processing debit again. Polling fees already charged while the job was working are separate.

Conversion warnings

The terminal response and callback can include a warnings array. Each notice has a stable code and a plain message, with additional fields where relevant. Examples include: Font, layer, OCR and attachment corrections and Ghostscript warnings remain conversion notices. Routine CMYK color-space and CropBox preservation are recorded only in internal logs. Warnings do not prove or disprove validation success, and they do not describe every possible change.
The public response uses warnings, including for stored jobs from the earlier details format. Validation-report evidence is separate.

Forms, JavaScript, metadata and signatures

Conversion rewrites the source PDF and has these input-handling limits:
  • Forms: Editable fields may be flattened into page content. The formFieldsChanged warning reports a reduced field count. Review the displayed values in the output; there is no automatic visual comparison or guarantee that every field appearance is preserved.
  • JavaScript and calculated values: JavaScript actions are removed. The saved display is preserved on a best-effort basis. Conversion does not run calculation scripts, recalculate values or correct stale field appearances. If calculations matter, recalculate and update the displayed values in a PDF editor, then save before submitting.
  • Metadata: Creation and modification dates can change, and custom metadata fields can be lost. Preservation of every custom field is not guaranteed.
  • Password protection: Encrypted PDF input is not supported, including owner-password PDFs that open without a prompt. Remove encryption before conversion. Supplying a PDF password to this endpoint does not enable processing of protected input.
  • Digital signatures: Digitally signed source PDFs are rejected before conversion because rewriting cannot preserve the original signature on the converted PDF. Empty, unsigned signature fields are allowed. Keep the signed original and submit an unsigned PDF. There is no option to remove signatures during conversion or automatically attach the original.
  • OCR text and clipping: A source PDF is rejected when the same recognized glyphless OCR font is used for invisible text and text clipping. This combination can change the page appearance during conversion. Ordinary OCR text and clipping with a different font remain supported. The failure reports a clear error, produces no converted PDF, and follows the existing failed-job refund rules.
An asynchronous submission can return a jobId before input inspection. For a signed input, the terminal job-check result or callback reports failure with a clear signature error. No converted PDF or validation report is produced for this rejection. The existing failed-job refund rules apply. These limits concern the source PDF. This endpoint does not verify that the displayed invoice amounts match the XML amounts. Both the output PDF URL and the JSON report URL are temporary. The expiration field controls retention in minutes, subject to the subscription plan and a maximum of seven days. Check outputLinkValidTill and validationReportLinkValidTill when present. Download both files before expiry if you need a lasting record. Do not send your PDF.co API key when downloading files from their returned storage URLs.

References