Taxpayers & organisations

Two concepts underpin everything in this section, and mixing them up is the most common source of confusion when reading the rest of this API.

Organisation

Your SUMU account. One API key belongs to one organisation and can send on behalf of every taxpayer that organisation has onboarded — keys aren't scoped per taxpayer today (see the callout on Authentication). An organisation is the thing SUMU bills, rate-limits (Reference → Rate limits), and issues API keys to.

Taxpayer

A business being invoiced for — the entity whose name, VAT number, and address appear as the supplier block on an invoice, and whose taxpayer_id you pass as sender_id when sending. Onboarding one is the first thing any integration does; see Onboard a taxpayer.

How they relate

An organisation has one or more taxpayers under it. Which shape you end up with depends on which track you're on:

• Direct — one organisation, one taxpayer. You onboard your own business once and stop there; the org/taxpayer distinction is mostly invisible day to day.
• Platform — one organisation, many taxpayers. You're onboarding other businesses on their behalf, and every one of them shares your organisation's API key, rate limit, and webhook configuration unless you scope webhooks per taxpayer (see Webhooks).

The per-taxpayer lifecycle

Every taxpayer — whether it's your own business or someone else's — goes through the same three steps before it can send or receive:

1. Onboard — register the business's legal and VAT details. It can send immediately after this step, but nobody can send to it yet.
2. Register on Peppol — publish its receiving capabilities to the Peppol directory so other Access Points can find it.
3. Fawtara association — a manual, outside-the-API step: the taxpayer must be connected to your organisation's Service Provider account in the Oman Tax Authority's Fawtara portal before step 2 will succeed. Skipping it is what a 409 TAXPAYER_NOT_ASSOCIATED means. On the Platform track this is a real scaling bottleneck — plan for it as manual ops work per taxpayer, not a one-time setup cost.

Once all three are done, list what you've onboarded with List and retrieve taxpayers.