Jurisdiction Settings
Two calls read and replace your organisation's settings for one country's e-invoicing pack:
GET /api/v1/jurisdictions/{code}/settings
PUT /api/v1/jurisdictions/{code}/settings
{code} is a two-letter country code, such as OM. Paths below are relative to
https://app.goroute.ai/peppol-api.
On GoRoute's production service (app.goroute.ai) three packs are switched on: Spain's, since
16 October 2026, Poland's, since 22 October 2026, and Nigeria's, since 30 October 2026. So ES,
PL and NG work there, and every other code answers 404 JURISDICTION_NOT_AVAILABLE. What
each pack does on production is described in Spain โ Verifactu,
Poland โ KSeF and the
Nigeria country guide. For Nigeria, what these calls return is in
Nigeria โ Where the settings live.
Other GoRoute services, such as the test service (app-test.goroute.ai) or an in-country
Oman service, switch on their own set of packs. Do not rely on a list here: run the check below.
Check your own service before you build anything on this. With your API key, call:
curl -i -H "X-API-Key: YOUR_API_KEY" \
"https://app.goroute.ai/peppol-api/api/v1/jurisdictions/ES/settings"
- 404 โ that country's pack is not switched on for your service. Nothing is wrong with your API key.
- 200 โ the pack is on, and the body is your organisation's stored settings.
If you get a 404 and expected otherwise, it is a question of how your service is configured, not of your credentials or your permissions.
How much these calls can do for you depends entirely on which pack you need:
- Oman is mandated and has a single setting you are not permitted to change, so on Oman there is very little to do here.
- Spain (Verifactu) is opt-in, and its settings object has several fields a merchant does set โ including whether the pack is enabled at all. If you are integrating Spain, these calls matter.
- Nigeria (NRS) is opt-in. Its settings here hold only three fields an organisation sets
itself:
enabled,default_business_idandauto_acknowledge. You can set them with these calls or withPUT /api/v1/nigeria/settings. Everything else (the NRS role, the NRS address and the business list) is owned by the platform, and aPUThere that names it is refused. See Nigeria โ Where the settings live. - Poland (KSeF) is opt-in. Its settings hold four fields:
enabled,nip,legal_nameandconsumer_invoices, and any other key is refused. The KSeF token is never stored here; it has its own call. The setup order and every field are on Poland โ KSeF.
Spain's individual fields are not listed on this page. Two of them carry Spanish tax
meaning, and the route a Spanish merchant normally goes through is the Verifactu setup path
rather than this generic call, so they belong with the Spain content where that path can be
described in one piece โ which has not been written yet. Until it is, the authoritative list
is the pack's own schema as the API publishes it: a PUT with a wrong type or an unknown key
is refused with JURISDICTION_SETTINGS_INVALID and an issues list naming each problem, and
a GET shows what your organisation currently has stored. For what the Verifactu regime is
and the readiness calls around it, see
Spain โ Verifactu.
What a pack's settings areโ
A country pack is GoRoute's implementation of one country's e-invoicing regime โ Oman's PINT OM rendering, its tax reporting and its validation rules. Your organisation's settings for a pack are stored against your organisation and validated against that pack's own schema, so each country decides what its settings contain.
A pack is either mandated or opt-in:
- Mandated means the country's rules apply to every matching document without you enrolling, and you cannot switch them off. Oman is mandated.
- Opt-in means the pack applies only to organisations enrolled in it. Spain (Verifactu) is
the first opt-in pack, and enrolment is what the
enabledfield in its settings records.
Read your settingsโ
curl -H "X-API-Key: YOUR_API_KEY" \
"https://app.goroute.ai/peppol-api/api/v1/jurisdictions/OM/settings"
Needs a valid API key. No special permission.
{
"code": "OM",
"settings": {
"enabled": true
}
}
settings is an empty object ({}) when your organisation has never stored any. For a mandated
pack such as Oman that does not mean the pack is off โ a mandated pack applies whether or
not you have stored anything.
The answer may also carry notices: things GoRoute should tell you about the settings you have
stored. Each notice has a code, a severity and a message. The PUT answer carries them too,
for the settings it has just stored. A notice never refuses a write. An answer without notices,
or with an empty list, means there is nothing to tell you.
Replace your settingsโ
The body is the settings object itself, not wrapped in anything. It replaces what was stored rather than merging into it, so send every key you want to keep.
curl -X PUT \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}' \
"https://app.goroute.ai/peppol-api/api/v1/jurisdictions/OM/settings"
Needs the settings:manage permission, which is enforced for this call whatever your
organisation's other role settings are. The response is the stored settings, as the GET
would return them.
authority:manage is also accepted, but only for an opt-in pack. That exists so a
connected store app can finish a merchant's own country setup for them โ the Verifactu app
doing a Spanish merchant's Spain settings, for instance. On a mandated pack such as Oman
authority:manage is not enough: the call answers 403 INSUFFICIENT_PERMISSION and asks for
settings:manage by name.
The permission is checked before the country code is looked up. A caller with neither permission gets 403 for every code, including codes that are not packs at all, so the status code cannot be used to discover which packs a service has.
The Oman pack's settingsโ
One field:
| Field | Type | Default | Meaning |
|---|---|---|---|
enabled | boolean | true | Whether the Oman pack applies to your organisation |
Any other key is rejected โ the schema accepts no extra fields, so a typo is an error rather than a value silently ignored.
Oman is mandated, so enabled cannot be set to false. In practice the only bodies the PUT
accepts for OM are {"enabled": true} and {} (which means the same thing, because enabled
defaults to true). Anything that would switch Oman off is refused and nothing is stored.
So for Oman there is nothing to configure here: its one setting is one you are not permitted to change. That is a fact about Oman, not about these two calls โ Spain's opt-in pack does have settings a merchant sets.
Your stored tax-authority credentialsโ
Some packs need a credential of your own to act for you at the tax authority: Spain's qualified certificate, Poland's KSeF token, Nigeria's NRS keys. Each is uploaded through its own pack's call. One read-only call lists what your organisation has stored:
GET /api/v1/authority-credentials
It returns each credential's status and public facts only: what kind it is, whom it names, when it is valid, and when GoRoute last used it. It never returns the certificate, the private key, the token, a password, or anything derived from them.
Needs a valid API key (or a signed-in session). No special permission.
| Query parameter | Default | Meaning |
|---|---|---|
regime | all | Only this country's credentials, such as ES, PL or NG. Upper or lower case. At most 8 characters; a longer value is refused with 422. A code with nothing stored answers an empty list |
include_revoked | false | true also lists revoked credentials, so you can see what each one replaced |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://app.goroute.ai/peppol-api/api/v1/authority-credentials?regime=es"
The answer is your organisation's id and a list, newest first. This example is a Spanish certificate, as it would read on 3 November 2026; every value is a placeholder.
{
"org_id": "3f2a1c4e-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
"credentials": [
{
"id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"regime": "ES",
"kind": "pkcs12",
"status": "active",
"custody": "merchant",
"subject": "CN=EJEMPLO SL,O=EJEMPLO SL,C=ES",
"issuer": "CN=EXAMPLE QUALIFIED CA,O=EXAMPLE TRUST SERVICE,C=ES",
"serial_number": "1A2B3C4D5E6F",
"fingerprint_sha256": "0F1E2D3C4B5A69788796A5B4C3D2E1F00F1E2D3C4B5A69788796A5B4C3D2E1F0",
"holder_ids": ["B12345678"],
"not_before": "2025-03-01T00:00:00+00:00",
"not_after": "2027-03-01T00:00:00+00:00",
"days_left": 117,
"expired": false,
"rotation_due_at": null,
"rotation_due": false,
"consent_record_id": null,
"custody_terms_version": null,
"public_facts": {},
"use_count": 37,
"last_used_at": "2026-11-02T09:14:05+00:00",
"revoked_at": null,
"created_at": "2026-10-20T11:02:44+00:00"
}
]
}
| Field | Meaning |
|---|---|
id | The stored credential's id |
regime | The country the credential is for, such as ES |
kind | What is stored: pkcs12 is a certificate with its private key, token is a secret string |
status | active, or revoked once it was removed or replaced. A revoked credential's secret is erased and can never be used again |
custody | Whose credential it is. merchant for every credential described on this page |
subject, issuer, serial_number, fingerprint_sha256 | The certificate's own public details. null for a token |
holder_ids | The tax identifiers the certificate names, such as a Spanish NIF. Empty for a token |
not_before, not_after | When the certificate is valid. null for a token |
days_left | Whole days until not_after. null for a revoked credential or a token |
expired | true once not_after has passed |
rotation_due_at, rotation_due | When GoRoute will start asking for a replacement, and whether that time has passed. null and false for the credentials described on this page |
consent_record_id, custody_terms_version | The record of your agreement to let GoRoute hold a key, where a pack asks for one. null for the credentials described on this page |
public_facts | Public details a pack keeps about the credential. Empty for the credentials described on this page |
use_count, last_used_at | How many times GoRoute has opened this stored credential, and when it last did. A replacement starts again at 0 |
revoked_at | When it was revoked. null while it is active |
created_at | When it was stored |
What each pack on the production service stores here:
- Spain โ one
pkcs12credential with regimeES: the business's qualified certificate, uploaded withPOST /api/v1/jurisdictions/es/certificate. Watchdays_leftandexpiredto replace it before it runs out. Uploading a new certificate revokes the old one; removing it isDELETE /api/v1/jurisdictions/es/certificate. See Spain โ Verifactu. - Poland โ one
tokencredential with regimePL: the KSeF token, connected withPOST /api/v1/jurisdictions/pl/token. A token has no validity dates here, sonot_afteranddays_leftarenull;created_atis when it was connected. Connecting a new token revokes the old one; removing it isDELETE /api/v1/jurisdictions/pl/token. See Poland โ KSeF. - Nigeria โ one
tokencredential with regimeNGholds all of the organisation's own NRS keys together. It does not say which keys are in it:GET /api/v1/nigeria/settingsdoes (has_taxpayer_key,has_si_key,has_ap_key). Every save of a key replaces the record, so the previous one shows as revoked. An SI or AP key inherited from a parent organisation is stored on that organisation, not listed here. Keys saved before this store existed appear only once they have been moved into it; the guide says when that happens. See Nigeria โ Roles and keys.
This call only reads. Uploading, replacing and removing a credential go through each pack's own calls, named above.
Refusalsโ
| Status | error_code | When |
|---|---|---|
| 401 | โ | No API key, or one that is not valid |
| 403 | INSUFFICIENT_PERMISSION | PUT with neither settings:manage nor authority:manage. Checked before the code, so you get this for any code |
| 403 | INSUFFICIENT_PERMISSION | PUT on a mandated pack (Oman) with only authority:manage. authority:manage is accepted for opt-in packs only |
| 404 | JURISDICTION_NOT_AVAILABLE | {code} is not a pack switched on for this service. On the production service this is every code except ES, PL and NG |
| 422 | JURISDICTION_SETTINGS_INVALID | The body does not match the pack's schema โ a wrong type, or a key the pack does not define. The response carries an issues list naming each problem |
| 422 | JURISDICTION_MANDATED | The pack is required by law and the settings would not keep it enabled โ for Oman, {"enabled": false}. Nothing was stored |
A JURISDICTION_MANDATED refusal is decided before your organisation record is read, so a
rejected PUT never changes anything.
Relatedโ
- Oman country guide โ what the Oman pack actually does
- Error codes
- API reference