Ingest PDF Push¶
API Gateway Address:
https://ext.arc-aegis.billtrust.com/api/v1/pdf-ingestion
Overview¶
The Ingest API handles structured data (accounts, documents, financial records). PDFs are binary files uploaded through a separate PDF Ingestion API, then linked to the matching document by document number. Once uploaded, the PDF is picked up on the next file delivery run and bundled for delivery.
Your Ingest connection is automatically configured in api-push mode — Data Bridge does not try to pull PDFs from any external source. You push them as they are generated.
Pushing PDFs for an ERP connection instead?
This page covers Ingest connections only — the document must already exist in the
Ingest API and an unknown document_number returns 404.
If your connection syncs records from an ERP (Dynamics 365, Sage Intacct, Oracle JD Edwards)
and you push PDFs against those synced records, see PDF Push.
That API uses {entityType}/{erpUniqueId} instead of document_number, and a PDF that arrives
before the ERP record is synced is queued rather than rejected.
POST /pdf/{connectionId}/ingest_documents/{document_number}¶
Uploads a PDF and associates it with an existing document.
POST https://ext.arc-aegis.billtrust.com/api/v1/pdf-ingestion/pdf/{connectionId}/ingest_documents/{document_number}
Path Parameters¶
| Parameter | Description |
|---|---|
connectionId |
UUID of your Ingest connection. Available in the Data Bridge Admin UI under the connection details — also shown on the PDF Settings page for this connection. |
document_number |
The document number used when creating the document via the Ingest API. Must match exactly (e.g. INV-2026-001). |
Headers¶
| Header | Description |
|---|---|
Content-Type: application/pdf |
Required. Must be application/pdf. |
X-API-Key: <your-api-key> |
Required. Same key used for the Ingest API. See Authentication. |
Query Parameters¶
| Parameter | Description |
|---|---|
| (none) | Default — replaces any existing PDF for this document. Re-uploading the same document number overwrites the existing PDF — no duplicates are created. |
?append=true |
Appends the uploaded pages to the end of the existing PDF. Use this for supplemental files (e.g. Bill of Lading, Delivery Receipt) after the invoice PDF is already uploaded. |
Status Codes¶
| Status | Description |
|---|---|
| 200 | PDF accepted and stored. |
| 400 | Bad request (invalid header, empty body, or unsupported content type). |
| 403 | Connection is not configured for PDF ingestion (pdfIngestionType is not api-push). |
| 404 | Connection or document not found. See Errors for the distinction. |
| 413 | PDF exceeds the maximum allowed size (100 MB by default). |
| 500 | PDF stored but the record could not be written — retry the upload. |
Errors¶
Both failure modes return 404, but they mean different things:
| Body | Meaning |
|---|---|
{"error":"Connection not found"} |
The connectionId in the URL does not exist. |
{"error":"document_not_found","message":"No ingest document found with document number 'INV-2026-001'."} |
The connection exists, but no document with that document_number was ever created — create it first with PUT /documents/{document_number}. |
A document_not_found result also means the PDF is not queued: nothing is stored for an unknown document number, so the upload must be repeated after the document exists.
Example Requests¶
Upload (or replace) a PDF¶
curl -X POST \
-H "Content-Type: application/pdf" \
-H "X-API-Key: <your-api-key>" \
--data-binary @invoice.pdf \
"https://ext.arc-aegis.billtrust.com/api/v1/pdf-ingestion/pdf/{connectionId}/ingest_documents/INV-2026-001"
Append a supplemental document¶
curl -X POST \
-H "Content-Type: application/pdf" \
-H "X-API-Key: <your-api-key>" \
--data-binary @proof_of_delivery.pdf \
"https://ext.arc-aegis.billtrust.com/api/v1/pdf-ingestion/pdf/{connectionId}/ingest_documents/INV-2026-001?append=true"
How It Links to a Document¶
The document_number in the URL is the key that connects the PDF to the correct document record. No other mapping is needed — just use the same value you used in PUT /documents/{document_number}.
Controlling the Filename in Delivery¶
By default, the PDF is bundled in the delivery package as {document_number}.pdf. To use a different filename, set the optional pdf_name field on the document:
{
"pdf_name": "invoice-INV-2026-001.pdf"
}
pdf_name only affects the filename in the delivery ZIP — it has no effect on how the PDF is stored or linked.
Verifying Upload¶
Use the Ingest API attachment endpoints to confirm the PDF was received:
### List attachments for a document
curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-2026-001/attachments \
-H "X-API-Key: <your-api-key>"
### Download a specific attachment
curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-2026-001/attachments/{id} \
-H "X-API-Key: <your-api-key>" \
--output invoice.pdf
See Documents — PDF Attachments for full details.