Taxpayers
Onboard a taxpayer
Register the business you're sending on behalf of.
A taxpayer is a business you send on behalf of. Create one before sending its first document. The details here become the supplier block on every invoice it issues, so they must match the business's VAT registration.
POST
/v1/api/taxpayersRequest fields
| Field | Type | Description | |
|---|---|---|---|
| name | string | required | Registered legal name, as it appears on the VAT certificate |
| vat_id | string | required | Oman VAT identifier, OM plus 10 digits |
| cr_number | string | required | Commercial Registration number |
| country_code | string | required | ISO 3166-1 alpha-2. OM for Omani taxpayers |
| address_line_1 | string | required | Street or building |
| address_line_2 | string | required | Area or district. Required by Oman rules, not optional as in base Peppol |
| address_line_3 | string | optional | Wilayat or further detail |
| city | string | required | City |
| post_code | string | required | Postal code |
| country_subdivision | string | optional | Governorate |
| phone | string | required | Contact number |
| string | optional | Billing contact address | |
| contact_point | string | optional | Department name shown on invoices |
| currency | string | optional | Default invoicing currency. Defaults to OMR |
| trade_name | string | optional | Trading name, when it differs from the legal name |
| tax_id | string | optional | Tax identifier, where it differs from vat_id |
| legal_info | string | optional | Free-text legal/registration detail shown where the format doesn't have a dedicated field |
| electronic_address | string | optional | Overrides the Peppol identifier. Defaults to vat_id when omitted |
| electronic_address_scheme | string | optional | 4-digit Peppol EAS code for electronic_address. Defaults to 0248 (Oman VAT scheme) when omitted |
Response fields
| Field | Type | Description | |
|---|---|---|---|
| taxpayer_id | uuid | — | Use this as sender_id when sending on this taxpayer's behalf |
| cr_number | string | — | Echoes the Commercial Registration number you sent |
| peppol_id | string | — | Network address, derived as 0248:<vat_id>. This is how other parties reach them |
| peppol_status | enum | — | not_registered · registered · failed · removed |
| capabilities | array | — | Document types this taxpayer can receive. Empty until registered |
| capabilities[].key | string | — | Same value you'd pass to Register on Peppol — null for a capability published through the arbitrary-document-type route, which has no catalogue key |
| capabilities[].label | string | — | Human-readable name |
| capabilities[].document_type_id | string | — | Scheme-qualified identifier — see Register on Peppol |
| capabilities[].process_id | string | — | The Peppol process this capability is published under |
| capabilities[].published_at | datetime | — | When it was published |
| created_at | datetime | — | When the taxpayer was created |
Not registered yet
Creating a taxpayer does not put it on the Peppol network. It can send immediately, but nobody can send to it until you call Register on Peppol.
Not idempotent on vat_id
Creating a taxpayer with a vat_id that already exists under your organisation returns a
409 CONFLICT_ERROR — it does not hand back the existing record. Retrieve it with
List and retrieve taxpayers instead of retrying blindly on a 5xx or
timeout.