Sample request
cURL
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"
}'
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());
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())
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());
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
$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);
{
"pageCount": 1,
"error": false,
"status": 200,
"duration": 120,
"jobId": "EXAMPLEJOBID0123456789ABCDEFGHIJ--167-300",
"credits": 100,
"remainingCredits": 9900
}
{
"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)."
}
{
"status": "error",
"errorCode": 401,
"error": true,
"message": "Unauthorized. Authentication is required and has failed or has not yet been provided."
}
{
"status": "error",
"errorCode": 402,
"error": true,
"message": "Not enough credits."
}
{
"status": "error",
"errorCode": 403,
"error": true,
"message": "Access forbidden for input URL."
}
{
"errorCode": 404,
"error": true,
"message": "The requested resource could not be found."
}
{
"error": true,
"message": "Too many requests in a given time period."
}
{
"errorCode": 500,
"error": true,
"message": "Something went wrong. Please try again or contact support."
}
cURL
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"
}'
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());
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())
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());
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
$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);
{
"pageCount": 1,
"error": false,
"status": 200,
"duration": 120,
"jobId": "EXAMPLEJOBID0123456789ABCDEFGHIJ--167-300",
"credits": 100,
"remainingCredits": 9900
}
{
"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)."
}
{
"status": "error",
"errorCode": 401,
"error": true,
"message": "Unauthorized. Authentication is required and has failed or has not yet been provided."
}
{
"status": "error",
"errorCode": 402,
"error": true,
"message": "Not enough credits."
}
{
"status": "error",
"errorCode": 403,
"error": true,
"message": "Access forbidden for input URL."
}
{
"errorCode": 404,
"error": true,
"message": "The requested resource could not be found."
}
{
"error": true,
"message": "Too many requests in a given time period."
}
{
"errorCode": 500,
"error": true,
"message": "Something went wrong. Please try again or contact support."
}
PDF Conversion
PDF to E-Invoice
Embed customer-provided Factur-X or ZUGFeRD XML into a PDF/A-3 document and validate the result.
Sample request
cURL
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"
}'
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());
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())
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());
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
$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);
{
"pageCount": 1,
"error": false,
"status": 200,
"duration": 120,
"jobId": "EXAMPLEJOBID0123456789ABCDEFGHIJ--167-300",
"credits": 100,
"remainingCredits": 9900
}
{
"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)."
}
{
"status": "error",
"errorCode": 401,
"error": true,
"message": "Unauthorized. Authentication is required and has failed or has not yet been provided."
}
{
"status": "error",
"errorCode": 402,
"error": true,
"message": "Not enough credits."
}
{
"status": "error",
"errorCode": 403,
"error": true,
"message": "Access forbidden for input URL."
}
{
"errorCode": 404,
"error": true,
"message": "The requested resource could not be found."
}
{
"error": true,
"message": "Too many requests in a given time period."
}
{
"errorCode": 500,
"error": true,
"message": "Something went wrong. Please try again or contact support."
}
cURL
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"
}'
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());
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())
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());
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
$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);
{
"pageCount": 1,
"error": false,
"status": 200,
"duration": 120,
"jobId": "EXAMPLEJOBID0123456789ABCDEFGHIJ--167-300",
"credits": 100,
"remainingCredits": 9900
}
{
"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)."
}
{
"status": "error",
"errorCode": 401,
"error": true,
"message": "Unauthorized. Authentication is required and has failed or has not yet been provided."
}
{
"status": "error",
"errorCode": 402,
"error": true,
"message": "Not enough credits."
}
{
"status": "error",
"errorCode": 403,
"error": true,
"message": "Access forbidden for input URL."
}
{
"errorCode": 404,
"error": true,
"message": "The requested resource could not be found."
}
{
"error": true,
"message": "Too many requests in a given time period."
}
{
"errorCode": 500,
"error": true,
"message": "Something went wrong. Please try again or contact support."
}
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 exactlyfacturx or zugferd for profile.
Request body
{
"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"
}
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.- PDF.co accepts the request and returns its
jobId. - The invoice XML is inspected and embedded during PDF/A-3 conversion.
- veraPDF, Mustang and attachment-integrity checks validate the output.
- The job is finalized and returns the terminal result.
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.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.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 selects the invoice family. It is distinct from the profiles configuration parameter used by other endpoints.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.HTTP authentication username for the source PDF URL only. This does not unlock a password-protected PDF or apply to
xml_url.HTTP authentication password for the source PDF URL only. This does not unlock a password-protected PDF or apply to
xml_url.Callback URL notified when the asynchronous job finishes. See Webhooks & Callbacks.
Output file name. The endpoint appends
.pdf when needed. If omitted, it derives the name from url when possible.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 itsjobId, 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
{
"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. |
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 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. |
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.Final job result
{
"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. |
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. |
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 unsupportedprofile 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 whenstatus 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 withstatus: 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 fromvalidationReportUrl 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 reportcredits: -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 awarnings 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. |
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
formFieldsChangedwarning 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.
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. Theexpiration 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
Was this page helpful?