API Reference Overview¶
Swagger documentation: https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Ingest%20Service%20v1
The Ingest API is a single set of endpoints that serves four Billtrust products: Collections, Invoicing, Open Balance, and CashApp AR. The endpoints are the same regardless of which products are active — what changes is which fields you populate on each request.
Base URL¶
https://ext.arc-aegis.billtrust.com/api/v1/ingest
| Lane | External (not arc-aegis platform host) |
| Auth header | X-API-Key: <external-api-key> |
| Key source | Platform Ext API Keys UI (btk_… keys with ingest scopes). Not created via the classic Authentication API. |
See Connect for the two-lane model. Wrong host or a platform-only key is the usual cause of 401s.
Authentication¶
Every Ingest request (except infrastructure health on the cluster network) must include an external API key:
X-API-Key: btk_…
The key is validated at ext-api-proxy. Ingest does not expose create/revoke key endpoints. Obtain and rotate keys through the Billtrust platform Ext API administration experience for your tenant (scoped for ingest).
The gateway also accepts the same external secret on header name X-Billtrust-Api-Key, but product docs and OpenAPI use X-API-Key.
Why Schemas Vary by Product¶
Each Billtrust product consumes data differently:
| Product | What it does with the data |
|---|---|
| Collections | Manages the AR collections workflow — reminders, escalations, dispute tracking. Needs contact details, custom workflow fields, and multi-currency balance info. |
| Invoicing | Generates and delivers invoice PDFs to customers. Needs billing addresses, delivery routing, line items, and optional Thick Billing data for Billtrust-generated PDFs. |
| Open Balance | Provides a real-time balance snapshot for portal display and payment facilitation. Needs current denomination and optional payment templates. |
| CashApp AR | Matches incoming customer payments to open invoices. Needs invoice_num (required) and up to 22 custom matching fields to handle remittance data. |
A field that is critical for one product may be completely ignored by another. For example:
languageis required for Collections (to translate reminder emails) but irrelevant to CashApp ARinvoice_numis required for CashApp AR (payment matching engine) but optional for Collections- Custom fields (
custom_fields.collections.*) are Collections-only and never processed by Invoicing or Open Balance - Thick Billing data elements only apply to Invoicing, specifically for Billtrust-generated PDFs
This means you only need to send the fields your active products actually use. Sending extra fields for inactive products is harmless — they are ignored — but the schemas document exactly which fields matter for each one.
Endpoints in This Section¶
| Endpoint group | Description |
|---|---|
| Accounts | Create, replace, update, and retrieve customer accounts. Top-level resource — all other resources attach to an account. |
| Documents | Submit invoices and credit notes, manage document status, close documents, and list PDF attachments. |
| Representatives | Manage internal contacts used as escalation recipients in Collections workflows. Collections only. |
| Contacts | Manage supplementary contact details for an account used in Collections outreach. Collections only. |
| PDF Push | Upload PDF invoice files directly to the PDF Ingestion API for delivery. |
Schema Reference¶
For the full field-level schema organized by product, see the Schemas section. Each product page lists only the fields relevant to that pipeline, so you can use it as a checklist when building your integration.
Rate Limiting¶
Rate limit exceeded — 1,000 requests/minute and 50,000 requests/hour by default. Check the Retry-After response header. Exceeding the limit gets you a 429 error.