KUNDEN & ZUORDNUNG

Ein Kunde — ein Eagle-Doc-„Sub-Business“ — ist ein reines Zuordnungs-Label. Er hat keinen Login, keinen API-Schlüssel und keine eigene Rechnung. Sie ordnen eine Anfrage einem Kunden zu, indem Sie einen Zuordnungs-Header zusammen mit Ihrem Business-API-Schlüssel senden.

Die Zuordnung macht aus einer einzelnen Business-Integration eine mandantenfähige: Sie trennt Nutzung, Dokumente und gelernte RAG-Beispiele pro Kunde — während alles weiterhin in Ihrem einen Business-Abonnement zusammenläuft.

Zwei Zuordnungs-Header

Wählen Sie pro Anfrage genau einen Header. Beide verweisen auf dasselbe Konzept — einen Kunden —, unterscheiden sich aber darin, wem die Kennung gehört und was bei einem unbekannten Wert passiert.

Zero-Touch: x-sub-business-ref

Senden Sie Ihre eigene Kundennummer in x-sub-business-ref. Bei der ersten Nutzung legt Eagle Doc das Sub-Business automatisch für Sie an — Sie registrieren nie etwas vorab.

Der Name des neuen Kunden wird auf die Referenz selbst gesetzt, die Referenz wird als externalClientRef gespeichert, und die Beschreibung lautet „auto-created from x-sub-business-ref“. Sie können den Kunden später im Dashboard umbenennen, doch die Referenz bleibt der Auflösungsschlüssel.

Jede spätere Anfrage mit derselben Referenz wird demselben Kunden zugeordnet. Referenzen sind pro Business unter den aktiven Kunden eindeutig und sind nach dem Löschen eines Kunden erneut verwendbar.

Ordnen Sie eine Beleg-Extraktion mit Ihrer eigenen Kundennummer zu:

curl --location 'https://de.eagle-doc.com/api/receipt/v3/processing' \
  --header 'api-key: APIB-your-business-key' \
  --header 'x-sub-business-ref: A-1023' \
  --form 'file=@"receipt.jpeg"'

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());

Strikt: x-sub-business-id

Senden Sie die Eagle-Doc-Sub-Business-id in x-sub-business-id. Die ID muss bereits existieren und zu Ihrem Business gehören — Sie erhalten sie über die Kundenverwaltungs-API oder das Dashboard.

Eine fremde oder unbekannte ID schlägt genau wie ein ungültiger Schlüssel fehl: 403 — messageCode 3009 („API key invalid“). Das ist bewusst so — es wird nie preisgegeben, ob eine bestimmte ID existiert.

Ordnen Sie eine Beleg-Extraktion mit einer Eagle-Doc-Sub-Business-ID zu:

curl --location 'https://de.eagle-doc.com/api/receipt/v3/processing' \
  --header 'api-key: APIB-your-business-key' \
  --header 'x-sub-business-id: 66cc0f2a4b1e8a0012ab34cd' \
  --form 'file=@"receipt.jpeg"'

import requests

resp = requests.post(
    "https://de.eagle-doc.com/api/receipt/v3/processing",
    headers={
        "api-key": "APIB-your-business-key",
        "x-sub-business-id": "66cc0f2a4b1e8a0012ab34cd",   # an Eagle Doc sub-business id
    },
    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-id": "66cc0f2a4b1e8a0012ab34cd", // an Eagle Doc sub-business id
  },
  body: form,
});
console.log(await resp.json());

Wann die Zuordnung erlaubt ist

Zuordnungs-Header werden nur in einem Business-Kontext berücksichtigt:

Datentrennung pro Kunde

Sobald eine Anfrage zugeordnet ist, hält Eagle Doc die Daten dieses Kunden getrennt:

• Die Nutzung wird pro Kunde gezählt, sodass Sie jeden Kunden unabhängig abrechnen oder auswerten können — während das Kontingent weiterhin in Ihrem Business zusammenläuft.
• Dokumente und Datensätze werden mit dem Kunden markiert, der sie erzeugt hat.
• RAG-Beispiele sind pro Kunde abgegrenzt, sodass Korrekturen, die Sie für einen Kunden lehren, nie zu einem anderen übergehen.

Wie Sie das Modell pro Kunde trainieren, erfahren Sie im Leitfaden zu RAG & menschlichem Feedback.

Kundenverwaltungs-API (optional)

Die meisten Teams benötigen dies nie — die Zero-Touch-Zuordnung legt Kunden für Sie an. Die optionale Kundenverwaltungs-API richtet sich an Teams, die Kunden lieber vorab bereitstellen oder von Anfang an umbenennen.

POST

/api/business/{businessId}/sub-businesses

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. { "name": "Client A", "description": "", "externalClientRef": "CRM-1001" }

Responses

Code	Description
201	Created. Returns a Business whose id is the value you would pass as x-sub-business-id. { "id": "66cc0f2a4b1e8a0012ab34cd", "name": "Client A", "description": "", "parentBusinessId": "665f1c9d3a2b4e0011cd77ef", "billingMode": "STRIPE", "wrapsPersonalAccount": false, "externalClientRef": "CRM-1001", "createdAt": "2026-07-08T10:20:00.000Z", "updatedAt": "2026-07-08T10:20:00.000Z" }
400	messageCode 8010 (SUB_BUSINESS_REF_TAKEN) when externalClientRef is already used by a live sibling: “Client reference already in use”.
403	The caller is not a real user with role ADMIN or higher (for example an APIB-… business key).

GET

/api/business/{businessId}/sub-businesses

Parameters

Name	Description
api-key (header)	Real-user token with role MEMBER or higher (listing is available to any member). APIB-… business keys are rejected.
businessId (path)	The id of your business (the parent).

Responses

Code	Description
200	An array of your live (non-deleted) sub-businesses. [ { "id": "66cc0f2a4b1e8a0012ab34cd", "name": "Client A", "description": "", "parentBusinessId": "665f1c9d3a2b4e0011cd77ef", "billingMode": "STRIPE", "wrapsPersonalAccount": false, "externalClientRef": "CRM-1001", "createdAt": "2026-07-08T10:20:00.000Z", "updatedAt": "2026-07-08T10:20:00.000Z" } ]
403	The caller is not a real user with role MEMBER or higher, or an APIB-… business key was used (messageCode 3010).

PATCH

/api/business/{businessId}/sub-businesses/{subBusinessId}

Parameters

Name	Description
api-key (header)	Real-user token with role ADMIN or higher. APIB-… business keys are rejected.
businessId (path)	The id of your business (the parent).
subBusinessId (path)	The id of the client to update.
body (application/json)	All fields optional; only the ones you send are changed. { "name": "Client A (EU)", "description": "Renamed", "externalClientRef": "CRM-1001" }

Responses

Code	Description
200	Updated. Returns the sub-business Business object.
400	messageCode 8010 (SUB_BUSINESS_REF_TAKEN) when the externalClientRef is already used by a live sibling: “Client reference already in use”.
404	messageCode 8001 when the sub-business does not exist.

DELETE

/api/business/{businessId}/sub-businesses/{subBusinessId}

Parameters

Name	Description
api-key (header)	Real-user token with role ADMIN or higher. APIB-… business keys are rejected.
businessId (path)	The id of your business (the parent).
subBusinessId (path)	The id of the client to delete.

Responses

Code	Description
200	Soft-deleted. Historical usage keeps referencing the client, and its externalClientRef becomes reusable for a new client.
404	messageCode 8001 when the sub-business does not exist.

Fehlerreferenz

Jeder Fehler verwendet den standardmäßigen Eagle-Doc-Fehlerkörper; prüfen Sie messageCode, um präzise zu verzweigen:

{
  "httpCode": 400,
  "httpCodeName": "BAD_REQUEST",
  "messageCode": 8011,
  "message": "Conflicting sub-business headers",
  "messageDetails": ["Send either x-sub-business-id or x-sub-business-ref, not both."],
  "data": null
}

Support