Skip to content

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"

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.