Flowie Exchange API

Authentication

Every request must carry a bearer token. Flowie Exchange supports two kinds of credentials; pick whichever matches your caller.

Flowie JWT

If the caller is a Flowie dashboard user, pass the Auth0-issued JWT you already use elsewhere. The organization is resolved from the _permissions claim.

Switching organizations

JWTs typically grant access to multiple organizations (the user's _permissions claim is a dict of org_id → permissions). By default the API picks the first one in that dict. To act as a specific organization, pass the X-Flowie-Organization-Id header on every request:

curl https://back.p2p-flowie.com/exchange/v1/documents \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "X-Flowie-Organization-Id: 685a5670efafaa26ebf0128e"

The header is validated against the JWT's _permissions: passing an org the token doesn't grant returns 403. Organization-Id (the legacy name used by the AFNOR routes) is also accepted as an alias.

To list every org a caller can switch to, hit GET /v1/me. The Flowie docs auth widget uses this endpoint to render the org-picker dropdown next to your email.

API keys are bound to a single org at creation time and ignore this header.

Exchange API keys

For programmatic access, issue an Exchange API key from the dashboard or via the API. Keys are prefixed so you can tell them apart at a glance:

• flw_live_…Personal key

  Scoped to a single company. Use for server-to-server calls from your own stack.

• flw_plat_live_…Platform key

  Scoped to an organization that manages other companies. Combine with X-Flowie-Company to act on behalf of a tenant.

• flw_wl_live_…White-label key

  Same as a platform key, plus the ability to customize branding, quotas, and settings per tenant.

• flw_test_…Sandbox key

  Any of the above with _test_ in the prefix hits sandbox. No real Peppol delivery.

Scopes

Keys carry a list of scopes. Use * only for full-access keys you control end-to-end; prefer the narrowest set your workload needs.

Get caller identity + accessible orgs

Returns who the caller is, which organizations they can act as, and the active org for the current request. Works with both JWT and API-key auth. Used by the docs auth widget to render the organization-switcher dropdown.

Returns

{
  "authMethod":      "jwt",
  "userId":          "user_…",
  "email":           "alice@example.com",
  "keyType":         "jwt",
  "organizationId":  "org_685a5670efafaa26ebf0128e",
  "organizationIds": ["org_685a…", "org_72b1…"],
  "organizations": [
    { "id": "org_685a…", "name": "PMU",        "country": "FR", "vatNumber": "FR12345678901" },
    { "id": "org_72b1…", "name": "Subsidiary", "country": "FR", "vatNumber": "FR98765432109" }
  ],
  "scopes":     ["*"],
  "isTestMode": false
}

Idempotency

Network calls are imperfect. Any POST in this API accepts an Idempotency-Key header; if a request with that key has already completed in the last 24 hours, we return the original response byte-for-byte instead of acting again.

• Keys are strings, up to 255 characters. UUID v4 works great.
• Cache TTL is 24 hours. After that, a repeated key is treated as new.
• If you retry before the first response has finished processing, you'll get a 409 idempotency_in_progress. Retry in a moment.
• Mutating a request under the same key is never allowed. We compare the full body hash — mismatched retries return 422 idempotency_body_mismatch.

Pagination

All list endpoints are cursor-paginated. Don't hard-code offsets — the cursor is an opaque server-issued token and will change format without notice.

• limitintegeroptional

  Page size. Default 20, max 100.

• cursorstringoptional

  Pass the cursor value returned by the previous page. Omit to start at the first page.

Every list response has the same envelope:

{
  "data":    [ /* records */ ],
  "hasMore": true,
  "cursor":  "eyJpZCI6ImRvY19YLi4uIn0"
}

Rate limits & quotas

Rate limits are enforced with a 60-second sliding window per key. Quotas are enforced monthly per organization. Both depend on your plan:

Every response includes the current state:

• X-RateLimit-Limitinteger

  Requests allowed in the current 60-second window.

• X-RateLimit-Remaininginteger

  Requests left before you're throttled.

• X-RateLimit-Resetunix timestamp

  When the window rolls over.

• Retry-Afterseconds

  Present only on 429. How long to wait before retrying.

Errors

Every error response uses the same envelope (RFC 7807 + Flowie extensions). See the error catalog for a full list of codes and how to fix them.

Request inspector

Every response carries an X-Request-Id header (and a requestId field on errors). Pass it back to this endpoint to retrieve the full request trace: timing, intermediate upstream calls, validation diff, and final status. Mirrors what you see at requests.html.

Versioning

The API version is baked into the URL (/v1/…). We follow semantic versioning with these commitments:

• Breaking changes ship under a new path (/v2/…). Old paths stay alive for at least 12 months.
• Additive changes — new fields, new enum values, new endpoints — land in /v1/ without notice.
• Deprecations are announced in the changelog and flagged with the Sunset response header 6+ months before removal.

Sandbox mode

Use a flw_test_… key with the staging base URL. Sandbox behaves identically to live with these differences:

• Documents are not delivered to real Peppol access points — they're routed to an internal echo endpoint.
• Compliance reporting goes to a mock PPF/SDI that always accepts.
• Webhooks fire the same events with "livemode": false in the payload.
• There are no quotas; rate limits remain.

Bootstrap a sandbox key

Public, unauthenticated. Mints a fresh flw_test_* API key bound to a brand-new throwaway organization plus a Belgian sandbox company (BE0000000001, peppolId 0208:0000000001). Returns the key only once. Rate-limited per IP; meant for the docs Playground and CI smoke tests.

Body: { "label": "my-laptop", "email": "you@example.com", "keyType": "personal" | "platform" | "white_label" } — all optional. keyType defaults to personal (token prefix flw_test_); pass platform to mint a multi-tenant key (flw_plat_test_) that satisfies the platform-key gate on /v1/platform/* ops, or white_label for the branding-enabled variant (flw_wl_test_). See Sandbox · Key types.

Reset sandbox state

Wipes events, idempotency cache, and pending scheduled events for the calling organization. Body: {"confirm": "yes", "scope": "all" | "events" | "documents" | "idempotency"}. Test-mode key only.

Advance virtual clock

Move the company-scoped virtual clock forward — used to test 60-day overdue flows, retry escalations, etc. Body: {"companyId": "comp_sbx_…", "by": "60d" | "12h" | "5m"}. Wakes any scheduled events whose virtual fire-time is now in the past.

Reset virtual clock

Snap the virtual clock back to wall-clock time for a company. Body: {"companyId": "comp_sbx_…"}.

Force rate-limit

Make every subsequent request from this organization return 429 for durationSeconds (1 ≤ s ≤ 3600). Use to validate your client's retry/backoff path against a real Retry-After.

Flush idempotency cache

Drop the 24h idempotency cache for the calling key — useful when you want to re-issue a request that previously succeeded under the same Idempotency-Key.

Create a company

Registers a new company. Only vatNumber is strictly required — everything else is auto-enriched from the national registry (INSEE, KBO, Camera di Commercio, …) and the Peppol directory.

Request body

• vatNumberstringrequired

  Country prefix + number, e.g. BE0123456789. Pattern ^[A-Z]{2}[A-Z0-9]+$.

• namestringoptional

  Display name. Defaults to the enriched legal name.

• addressAddressoptional

  Overrides the auto-enriched address.

• additionalIdentifiersobject[]optional

  Extra routing identifiers. { "scheme": "0088", "value": "1234567890128" } for GLN, etc.

• capabilitiesobjectoptional

  {"send": ["invoice","credit-note"], "receive": ["invoice"]}. Default: full set.

• settingsobjectoptional

  Default currency, auto-compliance toggles, preferred contact.

• metadataobjectoptional

  Free-form key-value (max 40 keys, 500 chars each).

Returns

The company object with status 201. SMP registration happens asynchronously — listen for company.smp_registered via webhook.

List companies

Returns all companies you own or manage, most-recently created first.

Query parameters

• countryISO 3166-1 α-2optional

  Filter by country.

• statusstringoptional

  active, inactive, or suspended.

• searchstringoptional

  Full-text over name, legal name, VAT, and Peppol ID.

• limit / cursorpaginationoptional

  See Pagination.

Resolve by VAT / SIREN

Looks up any company, anywhere, by legal identifier — returns the same shape as the company object but synthesized from national registries and the Peppol directory. Use it to pre-fill forms, verify recipients, or check Peppol reachability.

Query parameters

• countryCodeISO 3166-1 α-2required
• vatNumberstringone of
• registrationNumberstringone of

  SIREN, KBO, CF, … depending on countryCode.

Search companies

Autocomplete over your managed companies. Optimized for < 80 ms response time. Use for dropdowns in UIs.

• qstringrequired

  Query fragment (min 2 chars).

• countryCodeISO 3166-1 α-2optional
• limitintegeroptional

  Default 10, max 50.

Retrieve a company

Returns the company object. The path parameter accepts three forms:

• comp_01HXYZ… — the canonical id
• vat:BE0123456789 — VAT-scoped lookup
• peppol:0208:0123456789 — Peppol-ID lookup

Update a company

Partial update. Any field in the company object that isn't a system-managed attribute (peppolId, status, timestamps, stats) can be updated. Merging rules:

• Top-level keys are replaced wholesale.
• metadata is shallow-merged. Set a key to null to delete it.
• Changing capabilities.send or capabilities.receive may trigger an SMP re-registration (you'll see a company.smp_registered event).

Deregister a company

Permanently removes the SMP record and marks the company inactive. Historical documents remain queryable. Returns 204 No Content.

Join requests

If a Flowie user wants to connect to an already-registered company, they hit POST /companies/{id}/join. The company's organization admins see pending requests via:

and accept or reject with:

Issue a join request as the calling user.

Send a document

Delivers a document over Peppol to the to participant. Always set Idempotency-Key — duplicate sends to SDI or PPF can create regulatory headaches.

Doubles as Flowie's inbound integration point. Wire any ERP / accounting system / iPaaS webhook directly here — see Inbound: ERP webhooks for the full matrix of payload shapes (structured JSON · UBL XML · PDF / Factur-X / image / proprietary file).

Body

• typeenumrequired
  invoicecredit-notedebit-notepurchase-ordersales-orderquoteevent
• formatenumoptional

  json (default) — we render UBL. ubl-xml — provide your own XML in xml. auto — supply a file; the server sniffs the bytes and routes to the right pipeline. raw — supply a file; the server stores it as-is on the document file API and returns deliveryStatus="stored" (no Peppol routing).

• fromstringrequired

  Your sender company. Accepts comp_…, vat:…, or peppol:….

• tostringrequired when type ≠ event

  Recipient Peppol participant identifier, e.g. 0208:0123456789. Optional (omit) when type=event — events are pure observability/audit records and have no recipient.

• documentDocumentBodyrequired when format=json

  See schema below.

  • numberstringrequired
  • issueDatedaterequired
  • dueDatedateoptional
  • currencyISO 4217optional

    Default EUR.

  • buyerReferencestringoptional

    Required by many public-sector buyers (e.g. Service Executant / Code Service in FR).

  • orderReferencestringoptional

    PO number.

  • notestringoptional
  • seller / buyerPartyoptional

    Overrides the auto-derived seller/buyer.

  • paymentPaymentInfooptional

    means, iban, bic, reference, discountTerms[].

  • deliveryobjectoptional
  • linesInvoiceLine[]required

    Each line: description, quantity, unit, unitPrice, vatRate, vatCategory, itemCode, period.

  • allowances / chargesarrayoptional

    Document-level discounts or surcharges.

  • attachmentsarrayoptional
  • totalsobjectoptional

    Pre-computed totals. If omitted, we derive them from lines + allowances.

• xmlstringrequired when format=ubl-xml

  Raw UBL 2.1 or CII XML. We validate against the Peppol BIS 3.0 schematron before delivery.

• fileFileAttachmentrequired when format=auto or raw

  Arbitrary file payload (PDF, image, ZIP, proprietary format). { content: <base64>, contentType?, filename? }. Max 5 MiB. With format=auto we sniff magic bytes — if the file is UBL XML it routes through the regular pipeline (deliveryStatus="pending"); otherwise the bytes are persisted on the document file API and the response carries deliveryStatus="stored", fileId, and storedFormat.

Returns

201 Created with the document object. For structured payloads deliveryStatus starts as pending; listen for document.delivered or document.failed. For raw uploads deliveryStatus="stored" and the response includes fileId + storedFormat.

Batch send

Submit up to 100 documents in one request. Results come back in the same order as the input; failures don't poison successful sends.

Validate without sending

Run full Peppol BIS schematron + recipient reachability checks without delivering anything. Handy as a CI step before switching a customer live.

List documents

Paginated list across both directions.

Query parameters

• directionenumoptional
  incomingoutgoing
• typeenumoptional
• status / deliveryStatusenumoptional
• from / todateoptional

  Filter by issueDate range.

• amountMin / amountMaxnumberoptional

  Gross amount bounds.

• companyIdstringoptional
• searchstringoptional

  Full-text over number, party names, references, note.

• limit / cursorpaginationoptional

Advanced search

Same filters as the list endpoint, but accepts a JSON body with compound expressions: AND, OR, NOT trees. Use when a query exceeds URL length limits or you need nested predicates.

Retrieve a document

Download XML

Returns the signed UBL XML with Content-Type: application/xml.

Download PDF

Returns a human-readable PDF rendering.

Structured view

Flat, scalar-only representation — perfect for pushing to a data warehouse or spreadsheet.

Document actions

Non-lifecycle operations: mark-read, mark-unread, archive, unarchive, tag, untag, assign, unassign, add-note, link.

• actionenumrequired
• tag / userId / note / relatedDocumentId—conditional

  Depends on action.

Retrieve lifecycle history

Full event log, current status, allowed transitions, and per-country compliance state.

Update lifecycle status

Body

• statusenumrequired
  under_reviewapprovedrejectedpartially_paidpaiddisputed
• reason / reasonCodestringoptional

  Required for rejected and disputed. Use the official Peppol reason codes.

• notestringoptional
• paymentDatedateconditional

  Required for paid / partially_paid.

• paymentAmount / paymentCurrency / remainingAmountnumber / ISO 4217conditional
• paymentReferencestringoptional

Batch lifecycle update

Up to 500 updates in one call. Atomic per document; failures are reported per item.

Search directory

• qstringoptional
• vatNumberstringoptional
• country / city / postalCodestringoptional
• naceCodesstring[]optional
• documentTypesstring[]optional

  Only return participants that can receive these types.

Lookup Peppol ID

Verify recipient

The recommended pre-flight check before every send. Tells you whether the recipient exists, can accept the document type, and returns the access point metadata.

Create a partner

At least one of peppolId or vatNumber is required.

• peppolIdstringconditional

  Pattern ^\d{4}:.+$.

• vatNumberstringconditional
• roleenumoptional
  supplierbuyerboth
• contactName / contactEmailstringoptional
• defaultsobjectoptional

  currency, paymentTermsDays, note, orderReference…

• tags / metadataarray / objectoptional

List partners

Filters: role, search, country, tags, hasActivity, peppolStatus, sortBy, order, limit, cursor.

Retrieve partner

Path accepts part_…, vat:…, or peppol:….

Update partner

Delete partner

Create a webhook

• urlhttps URLrequired
• eventsstring[]required
  document.receiveddocument.updated document.sentdocument.delivered document.failedlifecycle.updated company.smp_registered*
• secretstringoptional

  Auto-generated if omitted. Used for HMAC-SHA256 signing.

• companyIdstringoptional

  Scope events to a specific managed company.

List webhooks

Update webhook

Body: url, events, or rotateSecret: true.

Delete webhook

Events

Every webhook delivery has a durable twin in the Events API. If your endpoint was down, or you want a replay, poll /v1/events and acknowledge what you've processed.

List events

Filters: type, companyId, limit.

Acknowledge one event

Returns 204 No Content. Acked events are hidden from subsequent list calls.

Batch acknowledge

Body: {"eventIds": ["evt_…", "evt_…"]}.

Replay an event

Re-emits a delivered event onto every matching webhook subscription as if it had just happened. Useful for recovering from a downstream outage on your side without rewinding our delivery state. Returns {"replayed": <n>} with the count of webhook deliveries scheduled.

Compliance

France PPF and Italy SDI require that lifecycle state changes (accepted / rejected / paid) be reported to a national platform. Flowie does this for you. These endpoints surface the current state and the underlying report records. Belgium runs pure Peppol since 2026-01-01 (HERMES decommissioned 2025-12-31) — no regulator-side report fires for BE.

Compliance status

Filters: companyId, country.

Compliance reports

Every report record has documentId, reportedTo, platformResponse, and an error if the authority rejected.

Stats

Usage, quota, and rate-limit status for the current period. Filters: period (day, week, month, year), companyId.

Onboard a managed company

Registers a tenant, optionally creates a scoped API key and webhook, and registers on SMP — all in one call.

• vatNumberstringrequired
• name / address / metadata—optional
• receiveDocumentsbooleanoptional

  Default true.

• autoVerifybooleanoptional
• webhookobjectoptional

  Same shape as webhook create; created atomically.

• apiKeyobjectoptional

  { "name": "tenant-…", "scopes": ["send","documents.read"] }.

List managed companies

Create API key for tenant

• namestringrequired
• companyIdstringoptional

  Scopes the key to that tenant.

• scopes / expiresAt / rateLimit—optional

List platform API keys

Revoke a key

Usage breakdown

Query: period, groupBy (company, country, type). Returns total counters and a per-group array.

Update platform settings

Body: branding, defaults, customDomain.

Cross-tenant event stream

Returns the unified event stream across every tenant managed by this platform key. Same shape as /v1/events with an extra companyId on each row so you can fan out per-tenant. Filters: type, companyId, limit, cursor. Platform / white-label keys only.

API keys

Create API key

• namestringrequired
• companyIdstringoptional
• scopesstring[]optional

  See scopes list.

• expiresAttimestampoptional
• rateLimitintegeroptional

Response includes key exactly once. Store it in your secret manager immediately.

List API keys

Revoke API key

Immediate. Any request-in-flight bearing the revoked key finishes, but new requests 401.

Categorization

Tag documents, partners, or other objects. Tags live in groups (e.g. business-unit, project, cost-center). We also expose an AI suggest endpoint — feed it a document, get a ranked list of tags.

List tag groups

List tags in a group

Tags on an object

Assign tag

Body: {"tagId": "tag_…", "objectType": "document"}.

Remove tag

AI tag recommendation

Body: {"objectId":"doc_…", "objectType":"document", "context": {…}} → ranked list of recommended tags with confidence scores.

Payments

Document payment info

Record a payment

Body: {"amount": …, "date": "YYYY-MM-DD", "reference": "…"}. Automatically advances the lifecycle to partially_paid or paid.

Export ISO 20022 / SEPA

Generates a pain.001 SEPA credit-transfer file for a set of documents, ready for upload to your bank.

Submit a flow

Multipart: flowInfo (JSON) + file (binary). Returns 202 Accepted with a flowId.

• flowInfo.namestringrequired
• flowInfo.flowSyntaxenumrequired
  CIIUBLFactur-XCDARFRR
• flowInfo.trackingIdstring (≤36)optional
• flowInfo.processingRuleenumoptional
  B2BB2CB2G
• flowInfo.flowProfileenumoptional
  BasicCIUSExtended-CTC-FR
• flowInfo.sha256hexoptional

Search flows

Body is SearchFlowParams — updatedAfter, updatedBefore, processingRule[], flowType[], flowDirection[], trackingId, ackStatus. Filters are AND-combined; array values are OR-combined.

Retrieve a flow

Query: docType=Metadata|Original|Converted|ReadableView.

AFNOR webhooks

Same operations as Webhooks but under the AFNOR-shaped schema:

AFNOR directory (SIREN / SIRET / routing codes)

Search body: filters, sorting, fields, include, limit (1–100, default 50), ignore. Response envelope: search, totalNumberOfResults, results.

Directory-line search

Stub endpoint for directory-line queries — the AFNOR aggregate row that joins SIREN + SIRET + routing-code data into a single result row, used for OD ↔ PDP onboarding flows. Body schema mirrors routing-code/search; response is currently empty (returns the AFNOR search envelope with totalNumberOfResults: 0) until the PDP-PDP federation handshake is wired up.

Healthchecks

Public, unauthenticated. Returns { "status": "ok", "version": "1.0", "service": "flow-service|directory-service" }. Required by the AFNOR PDP certification suite.

PunchOut cart callback

The cXML PunchOut return endpoint. SAP Ariba, Coupa, Ivalua and friends POST the user's cart back here when they check out. We OCR the cXML into a Flowie request, then respond with an HTML page that redirects the user to the originating chat thread.

Authentication: no bearer — we validate the SharedSecret in the cXML header against a per-partner allow-list, plus BuyerCookie for org scoping.

Accepted bodies

• Content-Type: application/x-www-form-urlencoded with a cxml-urlencoded or cxml-base64 field.
• Content-Type: application/xml with the raw cXML PunchOutOrderMessage.

Response

An HTML <meta refresh> redirect — typically to {APP_URL}/{org_slug}/ai/chat/{thread_id} if the v2 BuyerCookie contains a thread hint, or {APP_URL}/{org_slug}/requests otherwise.

Health

Public, unauthenticated. Great for load balancers and synthetic monitors.

Liveness

Returns {"status":"ok"} as long as the process can serve requests.

Readiness

Includes circuit-breaker state for every upstream.

Contracts

Actively probes upstreams (SMP, national directories). Slower; don't call from a hot path.