A client — an Eagle Doc “sub-business” — is a pure attribution label. It has no login, no API key and no separate bill. You attribute a request to a client by sending one attribution header alongside your business API key.
Attribution is what turns a single business integration into a multi-client one: it separates usage, documents and learned RAG examples per client, while everything still rolls up to your one business subscription.
🏷️
One header, sent with a business key
Send exactly one of x-sub-business-ref or x-sub-business-id, together with an APIB-… business key (or a wrapped personal key). Everything else about the request stays identical.
Two attribution headers
Pick exactly one header per request. Both point at the same concept — a client — but they differ in who owns the identifier and what happens when the value is unknown.
x-sub-business-id strict
x-sub-business-ref zero-touch
Value you send
An Eagle Doc sub-business id you obtained earlier (from the management API or the dashboard).
Your own client number — any identifier your system already uses.
Must exist first
Yes — the client must already exist.
No — auto-created on first use.
Unknown value
Rejected like a bad key: 403 “API key invalid”.
Creates the client, then proceeds with the request.
Best for
Catching integration bugs and keeping explicit control over which clients exist.
Frictionless onboarding — no state to store, no pre-registration.
🚫
Never send both headers at once
Sending x-sub-business-id and x-sub-business-ref in the same request returns 400 — messageCode 8011 (SUB_BUSINESS_HEADER_CONFLICT): “Send either x-sub-business-id or x-sub-business-ref, not both.”
✅
Recommended default
Prefer x-sub-business-ref for most integrations: it needs no pre-provisioning and no stored Eagle Doc ids. Reach for x-sub-business-id when you want strict, fail-fast control.
Zero-touch: x-sub-business-ref
Send your own client number in x-sub-business-ref. On first use, Eagle Doc auto-creates the sub-business for you — you never pre-register anything.
The new client’s name is set to the ref itself, the ref is stored as externalClientRef, and the description reads “auto-created from x-sub-business-ref”. You can rename the client later in the dashboard, but the ref stays the resolution key.
Every later request with the same ref resolves to the same client. Refs are unique per business among live clients, and become reusable again after a client is deleted.
Attribute a receipt extraction with your own client number:
import requests
resp = requests.post(
"https://de.eagle-doc.com/api/receipt/v3/processing",
headers={
"api-key": "APIB-your-business-key",
"x-sub-business-ref": "A-1023", # your own client number
},
files={"file": open("receipt.jpeg", "rb")},
)
print(resp.json())
import fs from "node:fs";
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("receipt.jpeg")]), "receipt.jpeg");
const resp = await fetch("https://de.eagle-doc.com/api/receipt/v3/processing", {
method: "POST",
headers: {
"api-key": "APIB-your-business-key",
"x-sub-business-ref": "A-1023", // your own client number
},
body: form,
});
console.log(await resp.json());
⚠️
An empty ref is rejected
Sending an empty x-sub-business-ref returns 400 — messageCode 8007. Send a non-empty value or omit the header entirely.
Strict: x-sub-business-id
Send the Eagle Doc sub-business id in x-sub-business-id. The id must already exist and belong to your business — obtain it from the client management API or the dashboard.
A foreign or unknown id fails exactly like an invalid key: 403 — messageCode 3009 (“API key invalid”). This is deliberate — it never leaks whether a given id exists.
Attribute a receipt extraction with an Eagle Doc sub-business id:
import fs from "node:fs";
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("receipt.jpeg")]), "receipt.jpeg");
const resp = await fetch("https://de.eagle-doc.com/api/receipt/v3/processing", {
method: "POST",
headers: {
"api-key": "APIB-your-business-key",
"x-sub-business-id": "66cc0f2a4b1e8a0012ab34cd", // an Eagle Doc sub-business id
},
body: form,
});
console.log(await resp.json());
When attribution is allowed
Attribution headers are only honoured in a business context:
🔐
Where attribution works
Valid with an APIB-… business key, or with the key of a wrapped personal account.
Sending either header with a plain (non-wrapped) personal API-… key returns 400 — messageCode 8002 (SUB_BUSINESS_NOT_ALLOWED): “Sub-business not allowed.”
Per-client data isolation
Once a request is attributed, Eagle Doc keeps that client’s data separate:
Usage is counted per client, so you can bill or report on each one independently — while the quota still rolls up to your business.
Documents and records are tagged with the client that produced them.
RAG examples are scoped per client, so corrections you teach for one client never bleed into another.
Most teams never need this — zero-touch attribution creates clients for you. The optional client management API is for teams that prefer to pre-provision clients or rename them up front.
👤
Real-user token required
These endpoints require a real-user token — a personal API-… key or a dashboard session. Creating, updating and deleting clients requires role ADMIN or higher; listing requires MEMBER or higher. They reject APIB-… business keys with 403 “API key not permitted” (code 3010).
Parameters
Name
Description
api-key (header)
Real-user token: a personal API-… key with role ADMIN or higher. APIB-… business keys are rejected.
businessId (path)
The id of your business (the parent).
body (application/json)
name is required; description and externalClientRef are optional.
