How the resources fit together
If you read one page in this whole reference, make it this one. Once you see the relationships, the rest of the API becomes obvious.
Entity-relationship diagram
Legend
- Solid arrow: synchronous foreign-key relationship (the child belongs to the parent).
- Dashed arrow: asynchronous "emits an event" relationship (state change creates an Event record).
- Bold field: primary key.
- Blue field: foreign key.
Organization
Top-level tenant in the Flowie system. Holds plan, branding, and ownership of every other resource. You'll never CRUD an Organization through the public API — they're created at sign-up.
Company
A legal entity that can send/receive on Peppol. Full reference. Note that peppolId is auto-derived from vatNumber + country scheme; you can override with additionalIdentifiers[].
Partner
A counterparty (customer or supplier) of one of your companies. Stores defaults so you don't repeat them on every send. Partners are scoped to a single company.
Document
An invoice, credit note, debit note, or purchase order. Has three orthogonal status fields:
status: protocol-level — has it been validated, signed, sent.deliveryStatus: transport-level — has the recipient AP confirmed.lifecycleStatus: business-level — has the buyer approved, paid, or rejected.
You can have status=sent, deliveryStatus=delivered, lifecycleStatus=disputed. They're independent.
Lifecycle event
Append-only log of business-level transitions on a document. The current lifecycleStatus on a document is materialized from the latest entry.
Compliance report
One per (document, platform) pair where Flowie reported a status to a national authority (PPF for FR, SDI for IT). Updated on every retry. Belgium has no regulator-side report since the HERMES platform was decommissioned on 2025-12-31 — BE invoices don't create rows here. Historical HERMES rows from before that date are retained for audit.
API key
Three flavors (personal, platform, white-label) and an optional scope to a single Company. Full reference.
Webhook
Subscription to one or more event types. Optional company scoping. Failures auto-pause after 8 consecutive errors.
Event
Durable record of every state change worth notifying about. Webhook deliveries are derived from these. Available for replay through the Events API for 30 days.
Cardinality summary
| From | To | Cardinality | Note |
|---|---|---|---|
| Organization | Company | 1 : N | Platform orgs typically have N in the thousands. |
| Organization | API key | 1 : N | One per integration. |
| Organization | Webhook | 1 : N | Up to 100 active webhooks per org. |
| Company | Partner | 1 : N | Free, no upper limit. |
| Company | Document | 1 : N (as sender) | Or as receiver — direction stored on doc. |
| Document | Lifecycle event | 1 : N | One per status transition. |
| Document | Compliance report | 1 : N | One per (platform, retry). |
| Webhook | Event | N : N | Many webhooks consume; one event matches whoever subscribes. |