---
title: "Data model"
description: "Entity-relationship diagram and field-level reference for every resource in Flowie Exchange."
canonical: "https://docs.get-flowie.com/reference/data-model"
source: "https://docs.get-flowie.com/reference/data-model.html"
---

# Data model

Data model

# 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

Organization id (org_…) name, brand plan (free|starter|pro|platform|wl) API key id (key_…) organizationId → companyId? → Company scopes[], keyType, expiresAt Company id (comp_…) organizationId → vatNumber, peppolId country, status, smpRegistered capabilities {send[], receive[]} compliance, settings, metadata createdAt, updatedAt Webhook id (wh_…) organizationId → companyId? → Company url, events[], secret Partner id (part_…) companyId → Company peppolId, vatNumber, role defaults, tags, contactEmail Document id (doc_…) senderCompanyId → Company receiverPeppolId type, direction, number status, deliveryStatus lifecycleStatus, currency grossAmount, document {…} Event id (evt_…) organizationId → type, createdAt, livemode data {…} (snapshot) Lifecycle event documentId → Document previous, current, at setBy, reason, payment {…} Compliance report documentId → Document platform (PPF|SDI) status, code, reportedAt 1 : N 1 : N 1 : N 1 : N 1 : N (sent) scopes scoped 1 : N 1 : N emits delivers

## 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](<index.html#companies>). 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](<index.html#authentication>).

## 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](<index.html#events>) 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.