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.
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 & API Keys. |
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). |
| 404 | Connection or document not found. |
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.