> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pdf.co/llms.txt
> Use this file to discover all available pages before exploring further.

# PDF to E-Invoice

> Embed customer-provided Factur-X or ZUGFeRD XML into a PDF/A-3 document and validate the result.

> [!NOTE]
>
> **Try it live:** [PDF to E-Invoice API Tester](https://developer.pdf.co/api-tester/pdf-to-e-invoice.md). 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`.

```json Request body theme={null}
{
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample.pdf",
  "xml_url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample-document-services-invoice.xml",
  "profile": "facturx"
}
```

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.

> [!NOTE]
>
> See [URL input and request limits](https://developer.pdf.co/api/url-input-and-request-limits.md) for source PDF and request limits. Invoice XML has a separate 5 MiB limit.

## Asynchronous only

> [!WARNING]
>
> 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](https://developer.pdf.co/api/job-check.md), or provide a `callback` URL. See [Webhooks & Callbacks](https://developer.pdf.co/api/webhooks.md). 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

> [!NOTE]
>
> 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.

**url** `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.

**xml\_url** `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.

**profile** `string` *required*

> [!NOTE]
>
> `profile` selects the invoice family. It is distinct from the [`profiles` configuration parameter](https://developer.pdf.co/api/profiles) 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`.

**httpusername** `string`

HTTP authentication username for the source PDF URL only. This does not unlock a password-protected PDF or apply to `xml_url`.

**httppassword** `string`

HTTP authentication password for the source PDF URL only. This does not unlock a password-protected PDF or apply to `xml_url`.

**callback** `string`

Callback URL notified when the asynchronous job finishes. See [Webhooks & Callbacks](https://developer.pdf.co/api/webhooks.md).

**name** `string`

Output file name. The endpoint appends `.pdf` when needed. If omitted, it derives the name from `url` when possible.

**expiration** `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](https://developer.pdf.co/api/file-upload/overview.md). 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](https://app.pdf.co/tools/files).

## 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.

```json Submission response theme={null}
{
  "pageCount": 1,
  "error": false,
  "status": 200,
  "duration": 120,
  "jobId": "EXAMPLEJOBID0123456789ABCDEFGHIJ--167-300",
  "credits": 100,
  "remainingCredits": 9900
}
```

| Field | Type | Description |
| - | - | - |
| `error` | boolean | `false` when submission is accepted. |
| `status` | integer | Submission HTTP status. This is separate from the string background-job status. |
| `jobId` | string | Background job identifier. Use it with [Background Job Check](https://developer.pdf.co/api/job-check.md). |
| `pageCount` | integer | Always `1` in the submission response, even for multi-page PDFs. This value is a submission placeholder and does not represent the actual number of pages in the output PDF. The actual output page count is returned in the final [Background Job Check](https://developer.pdf.co/api/job-check.md) or callback result. |
| `name`, `validationReportName` | string | Planned PDF and report filenames. These do not guarantee that the files will be produced. |
| `credits`, `remainingCredits` | integer | Submission processing charge and remaining account balance. |
| `duration` | integer | Submission request duration in milliseconds, excluding background processing. |

> [!NOTE]
>
> `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](https://developer.pdf.co/api/job-check.md) 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.

```json Final job result theme={null}
{
  "status": "success",
  "message": "Success",
  "url": "https://example.com/output/invoice-e-invoice.pdf",
  "pageCount": 1,
  "validationStatus": "completed",
  "isCompliant": true,
  "pdfaProfile": "PDF/A-3B",
  "failedRules": 0,
  "failedChecks": 0,
  "validator": "veraPDF+Mustang",
  "validatorVersion": "1.30.1+2.26.0",
  "validationReportUrl": "https://example.com/output/invoice-e-invoice-pdfa-validation.json",
  "validationReportName": "invoice-e-invoice-pdfa-validation.json",
  "warnings": [
    {
      "code": "documentModified",
      "message": "The PDF was rewritten for PDF/A. Change details are reported where available."
    }
  ],
  "jobId": "EXAMPLEJOBID0123456789ABCDEFGHIJ--167-300",
  "credits": 2,
  "remainingCredits": 9898,
  "duration": 100
}
```

| Field | Type | Description |
| - | - | - |
| `status` | string | Background job status: `working`, `success`, `failed` or `aborted`. |
| `message` | string | Result or failure message. |
| `jobId` | string | Background job identifier. |
| `url`, `pageCount` | string, integer | Converted PDF URL and output page count, when available. |
| `outputLinkValidTill` | string | Output-link expiry timestamp, when available. |
| `validationStatus` | string | `completed` when the combined validation succeeds; `error` when it fails or cannot finish. |
| `isCompliant` | boolean or null | `true` only when veraPDF, Mustang PDF/XML/overall checks and attachment-integrity checks all pass. Null or absent when compliance could not be determined. |
| `pdfaProfile` | string | PDF/A profile reported by veraPDF, such as `PDF/A-3B`. |
| `failedRules`, `failedChecks` | integer | Failed veraPDF rule and check counts. Mustang or attachment checks can fail even when these counts are zero. |
| `validator`, `validatorVersion` | string | Combined validator identity, currently `veraPDF+Mustang`, and the versions used. |
| `validatedAt` | string | Validation timestamp, when available. |
| `validationReportUrl`, `validationReportName` | string | Temporary JSON report URL and report filename, when a report is available. |
| `validationReportLinkValidTill` | string | Report-link expiry timestamp, when available. |
| `warnings` | array | Conversion notices, separate from the validation result. See [Conversion warnings](#conversion-warnings). |
| `credits` | integer | Charge reported by the status check. A negative value can represent the processing refund on the first terminal failure check. |
| `remainingCredits` | integer | Remaining account balance. |
| `duration` | integer | Duration of the job-status request in milliseconds, not the conversion duration. |

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](https://developer.pdf.co/api/response-codes.md); 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](https://developer.pdf.co/api/pdf-to-pdfa.md), 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](https://developer.pdf.co/api/credits-per-api-function.md). 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:

| Code | Meaning |
| - | - |
| `documentModified` | Conversion rewrote the PDF. Change details are reported where available. |
| `nonEmbeddedFonts` | The source references fonts that are not embedded. Font substitution can affect appearance. Carries `fontNames`. |
| `formFieldsChanged` | The converted PDF has fewer interactive form fields. Review displayed values. |
| `attachmentMetadataRepaired` | Attachment metadata changed during conversion. Review the reported changes and retained attachments. |

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.

> [!NOTE]
>
> 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.

## Link expiry and retention

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.

**Sample request**

```bash cURL theme={null}
curl --request POST \
  --url 'https://api.pdf.co/v1/pdf/convert/to/e-invoice' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample.pdf",
    "xml_url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample-document-services-invoice.xml",
    "profile": "facturx"
  }'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.pdf.co/v1/pdf/convert/to/e-invoice", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    url: "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample.pdf",
    xml_url: "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample-document-services-invoice.xml",
    profile: "facturx",
  }),
});

console.log(await response.json());
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.pdf.co/v1/pdf/convert/to/e-invoice",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample.pdf",
        "xml_url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample-document-services-invoice.xml",
        "profile": "facturx",
    },
)

print(response.json())
```

```csharp C# theme={null}
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var payload = JsonSerializer.Serialize(new
{
    url = "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample.pdf",
    xml_url = "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample-document-services-invoice.xml",
    profile = "facturx",
});

var response = await client.PostAsync(
    "https://api.pdf.co/v1/pdf/convert/to/e-invoice",
    new StringContent(payload, Encoding.UTF8, "application/json")
);

Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```java Java theme={null}
OkHttpClient client = new OkHttpClient();

String jsonPayload = "{\"url\": \"https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample.pdf\", \"xml_url\": \"https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample-document-services-invoice.xml\", \"profile\": \"facturx\"}";

Request request = new Request.Builder()
    .url("https://api.pdf.co/v1/pdf/convert/to/e-invoice")
    .addHeader("x-api-key", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .post(RequestBody.create(MediaType.parse("application/json"), jsonPayload))
    .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}
```

```php PHP theme={null}
<?php
$payload = json_encode([
    "url" => "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample.pdf",
    "xml_url" => "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-e-invoice/sample-document-services-invoice.xml",
    "profile" => "facturx",
]);

$curl = curl_init("https://api.pdf.co/v1/pdf/convert/to/e-invoice");
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        "x-api-key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $payload,
]);

echo curl_exec($curl);
curl_close($curl);
```

```json 200 theme={null}
{
  "pageCount": 1,
  "error": false,
  "status": 200,
  "duration": 120,
  "jobId": "EXAMPLEJOBID0123456789ABCDEFGHIJ--167-300",
  "credits": 100,
  "remainingCredits": 9900
}
```

```json 400 theme={null}
{
  "errorCode": 400,
  "error": true,
  "message": "Bad request. Typically due to bad input parameters or unreachable input URLs (e.g., access restrictions like login or password)."
}
```

```json 401 theme={null}
{
  "status": "error",
  "errorCode": 401,
  "error": true,
  "message": "Unauthorized. Authentication is required and has failed or has not yet been provided."
}
```

```json 402 theme={null}
{
  "status": "error",
  "errorCode": 402,
  "error": true,
  "message": "Not enough credits."
}
```

```json 403 theme={null}
{
  "status": "error",
  "errorCode": 403,
  "error": true,
  "message": "Access forbidden for input URL."
}
```

```json 404 theme={null}
{
  "errorCode": 404,
  "error": true,
  "message": "The requested resource could not be found."
}
```

```json 429 theme={null}
{
  "error": true,
  "message": "Too many requests in a given time period."
}
```

```json 500 theme={null}
{
  "errorCode": 500,
  "error": true,
  "message": "Something went wrong. Please try again or contact support."
}
```

## References

* [Zapier: Convert PDF to E-Invoice](https://developer.pdf.co/integrations/zapier/pdf-to-e-invoice.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.