Skip to main content

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 the production service, these calls work for Spain, Poland and Nigeria only

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_id and auto_acknowledge. You can set them with these calls or with PUT /api/v1/nigeria/settings. Everything else (the NRS role, the NRS address and the business list) is owned by the platform, and a PUT here that names it is refused. See Nigeria โ€” Where the settings live.
  • Poland (KSeF) is opt-in. Its settings hold four fields: enabled, nip, legal_name and consumer_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 enabled field 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:

FieldTypeDefaultMeaning
enabledbooleantrueWhether 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 parameterDefaultMeaning
regimeallOnly 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_revokedfalsetrue 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"
}
]
}
FieldMeaning
idThe stored credential's id
regimeThe country the credential is for, such as ES
kindWhat is stored: pkcs12 is a certificate with its private key, token is a secret string
statusactive, or revoked once it was removed or replaced. A revoked credential's secret is erased and can never be used again
custodyWhose credential it is. merchant for every credential described on this page
subject, issuer, serial_number, fingerprint_sha256The certificate's own public details. null for a token
holder_idsThe tax identifiers the certificate names, such as a Spanish NIF. Empty for a token
not_before, not_afterWhen the certificate is valid. null for a token
days_leftWhole days until not_after. null for a revoked credential or a token
expiredtrue once not_after has passed
rotation_due_at, rotation_dueWhen 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_versionThe 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_factsPublic details a pack keeps about the credential. Empty for the credentials described on this page
use_count, last_used_atHow many times GoRoute has opened this stored credential, and when it last did. A replacement starts again at 0
revoked_atWhen it was revoked. null while it is active
created_atWhen it was stored

What each pack on the production service stores here:

  • Spain โ€” one pkcs12 credential with regime ES: the business's qualified certificate, uploaded with POST /api/v1/jurisdictions/es/certificate. Watch days_left and expired to replace it before it runs out. Uploading a new certificate revokes the old one; removing it is DELETE /api/v1/jurisdictions/es/certificate. See Spain โ€” Verifactu.
  • Poland โ€” one token credential with regime PL: the KSeF token, connected with POST /api/v1/jurisdictions/pl/token. A token has no validity dates here, so not_after and days_left are null; created_at is when it was connected. Connecting a new token revokes the old one; removing it is DELETE /api/v1/jurisdictions/pl/token. See Poland โ€” KSeF.
  • Nigeria โ€” one token credential with regime NG holds all of the organisation's own NRS keys together. It does not say which keys are in it: GET /api/v1/nigeria/settings does (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โ€‹

Statuserror_codeWhen
401โ€”No API key, or one that is not valid
403INSUFFICIENT_PERMISSIONPUT with neither settings:manage nor authority:manage. Checked before the code, so you get this for any code
403INSUFFICIENT_PERMISSIONPUT on a mandated pack (Oman) with only authority:manage. authority:manage is accepted for opt-in packs only
404JURISDICTION_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
422JURISDICTION_SETTINGS_INVALIDThe 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
422JURISDICTION_MANDATEDThe 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.