Skip to content
Gungner docs

API reference by scope

Published verbatim from Gungner’s Brayns partner interface pack, version 1.6.0 (reference.md). This page is not edited here.

Every route reachable with a consumer (OAuth2 client-credentials) token — grouped by the scope that gates it. Portal and demo-console routes are excluded by construction: they are session-authenticated, not consumer-token-authenticated, and are never reachable with the token this pack documents.

Authentication

Section titled “Authentication”

Every consumer token comes from this route — it is part of the pinned contract even though it carries no scope of its own (a tenant’s own consumer credentials authenticate the request).

POST /oauth/token

Section titled “POST /oauth/token”

Exchange client credentials (JSON or form-encoded) for a tenant-scoped access token

  • Scope: none — see Authentication
  • Tags: auth

Request body:

  • grant_type: enum (client_credentials)
  • client_id: string
  • client_secret: string
  • scope: string

Responses:

  • 200 — An access token

    • access_token: string
    • token_type: enum (Bearer)
    • expires_in: integer
    • scope: string
    • countries[]: enum

  • 400 — Malformed request

    • error: string
    • message: string

  • 401 — Invalid credentials

    • error: string
    • message: string

Countries and the wire form

Section titled “Countries and the wire form”

Every identifier a route or tool takes is written in wire form (ADR-017): an optional two-letter country prefix and the value. lt:123456789 is a Lithuanian company code; an unprefixed value means se:, so every Swedish identifier is written as it always was. The prefix is lowercase and the country must be one Gungner knows; anything else is 400 invalid_identifier. The scheme is fixed by the resource — a company route reads the country’s company code. Canonical objects, events and subject identifiers carry country explicitly.

A token carries the countries its grant allows (countries in the token response and the JWT, beside scope). An identifier outside them is 403 country_not_granted; outside what the tenant is provisioned for, 403 country_not_provisioned; granted and provisioned but not yet served for that resource, 501 country_not_supported. Reads about a subject return only its identifiers and objects in the granted countries, and a subject with none there answers exactly as a subject that does not exist.

Coverage by country today:

Resource SE LT
Company profile, officers, signatories, beneficial owners, refresh served 501 until SPEC-003f
Person profile, engagements served 501 until SPEC-003f/003g
Documents served — (Bolagsverket filings only)
Subject resolve, subjects, events served served for data that exists
Monitoring subscriptions, screening served 501 for a subject identified only in Lithuania, until SPEC-003f/003g; a subject also identified in Sweden is served as Swedish

Access log

Section titled “Access log”

Every request made under a grant lands in the tenant’s audit log carrying the grant’s id (gid), and Gungner keeps a per-grant access log over those rows. The rule: every authenticated request that reached a route is logged — allowed, failed, or refused by a guard (scope, country, a revoked or expired credential) — except a 400 validation failure, which reached no data. A refused request is logged once, by the guard that refused it. Over MCP, each tool call adds one mcp.tool_call row beside exactly the rows the same REST calls write. No row records a company or personal identifier the request carried: a guard refusal and a route access name the route template (GET /v1/companies/{orgnr}), never the path as sent.

Data routes, by scope

Section titled “Data routes, by scope”

Two scopes open a write route and the reads beside it, rather than only the write: monitoring:subscribe on /v1/subscriptions, and screening:run on /v1/screening/checks. kyb:refresh opens the paid company refresh and nothing else. A consumer able to create something it then cannot read back would be an incoherent grant. monitoring:read and screening:read are the least-privilege read-only halves, and screening:read is the only screening scope Gungner’s own assistant can hold.

identity:read, decisions:write are declared in the scope set but no live route requires them yet.

Scope: events:read

Section titled “Scope: events:read”

GET /v1/events

Section titled “GET /v1/events”

Replay this tenant’s events from a cursor

  • Scope: events:read
  • Tags: events

Responses:

  • 200 — A page of events

    • events[].id: string
    • events[].seq: integer
    • events[].schema_version: string
    • events[].tenant_id: string
    • events[].type: string
    • events[].subject_id: string,null
    • events[].ref: string,null
    • events[].occurred_at: string
    • events[].recorded_at: string
    • events[].data: object
    • events[].evidence.source: string
    • events[].evidence.source_timestamp: string
    • events[].evidence.call_ref: string
    • events[].evidence.transaction_ref: string
    • events[].evidence.upstream_ref: string,null
    • events[].evidence.digest: string,null
    • events[].evidence.schema_version: string,null
    • events[].evidence.retrieved_at: string
    • next_cursor: integer

  • 400 — The cursor is not in canonical form

    • error: enum (invalid_cursor)
    • recovery: enum (restart from cursor 0)

  • 401 — Missing or invalid token

  • 403 — Token lacks events:read

Scope: kyb:read

Section titled “Scope: kyb:read”

GET /v1/companies/{orgnr}

Section titled “GET /v1/companies/{orgnr}”

Company profile, status and tax placeholder

  • Scope: kyb:read
  • Tags: companies

Responses:

  • 200 — Company profile

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.schema_version: string
    • data.tenant_id: string
    • data.subject_id: string
    • data.orgnr: string
    • data.name: string
    • data.legal_form: string
    • data.status: string
    • data.registered_at: string,null
    • data.address.street: string,null
    • data.address.postal_code: string,null
    • data.address.city: string,null
    • data.address.country: string
    • data.sni[]: string
    • data.employees_band: string,null
    • data.tax.f_skatt: boolean
    • data.tax.vat: boolean
    • data.tax.employer: boolean
    • data.tax.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.tax.evidence.source_timestamp: string
    • data.tax.evidence.call_ref: string
    • data.tax.evidence.transaction_ref: string
    • data.tax.evidence.upstream_ref: string,null
    • data.tax.evidence.digest: string,null
    • data.tax.evidence.schema_version: string,null
    • data.tax.evidence.retrieved_at: string
    • data.latest_annual_report.year: integer
    • data.latest_annual_report.ref: string
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string

  • 400 — The organisationsnummer is not well-formed

    • error: string
    • message: string

  • 403 — Scope not granted, or the country is not granted (country_not_granted) or not provisioned (country_not_provisioned)

    • error: string
    • message: string

  • 501 — The country is granted but this resource is not served there yet (country_not_supported)

    • error: string
    • message: string

  • 503 — Upstream unavailable, no cached data

    • error: string
    • message: string

GET /v1/companies/{orgnr}/beneficial-owners

Section titled “GET /v1/companies/{orgnr}/beneficial-owners”

Beneficial owners (verkliga huvudmän)

  • Scope: kyb:read
  • Tags: companies

Responses:

  • 200 — Beneficial owners

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.schema_version: string
    • data.tenant_id: string
    • data.subject_id: string
    • data.orgnr: string
    • data.owners[].name: string
    • data.owners[].personal_number_ref: string,null
    • data.owners[].nature_of_control: string
    • data.owners[].share_band: enum (25-50 | 50-75 | 75-100 | unknown)
    • data.no_ubo_reported: boolean
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string

  • 400 — The organisationsnummer is not well-formed

    • error: string
    • message: string

  • 403 — Scope not granted, or the country is not granted (country_not_granted) or not provisioned (country_not_provisioned)

    • error: string
    • message: string

  • 429 — Paid API daily budget exceeded

    • error: string
    • message: string

  • 501 — The country is granted but this resource is not served there yet (country_not_supported)

    • error: string
    • message: string

  • 503 — Upstream unavailable, no cached data

    • error: string
    • message: string

GET /v1/companies/{orgnr}/officers

Section titled “GET /v1/companies/{orgnr}/officers”

Officers and the signatory rule (funktionärer + firmateckning)

  • Scope: kyb:read
  • Tags: companies

Responses:

  • 200 — Officers and signatory rule

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.schema_version: string
    • data.tenant_id: string
    • data.subject_id: string
    • data.orgnr: string
    • data.officers[].role: string
    • data.officers[].name: string
    • data.officers[].personal_number_ref: string,null
    • data.officers[].appointed_at: string,null
    • data.signatory_rule_text: string,null
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string

  • 400 — The organisationsnummer is not well-formed

    • error: string
    • message: string

  • 403 — Scope not granted, or the country is not granted (country_not_granted) or not provisioned (country_not_provisioned)

    • error: string
    • message: string

  • 429 — Paid API daily budget exceeded

    • error: string
    • message: string

  • 501 — The country is granted but this resource is not served there yet (country_not_supported)

    • error: string
    • message: string

  • 503 — Upstream unavailable, no cached data

    • error: string
    • message: string

GET /v1/companies/{orgnr}/signatories

Section titled “GET /v1/companies/{orgnr}/signatories”

Signatory rule (same object as /officers — see module note)

  • Scope: kyb:read
  • Tags: companies

Responses:

  • 200 — Officers and signatory rule

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.schema_version: string
    • data.tenant_id: string
    • data.subject_id: string
    • data.orgnr: string
    • data.officers[].role: string
    • data.officers[].name: string
    • data.officers[].personal_number_ref: string,null
    • data.officers[].appointed_at: string,null
    • data.signatory_rule_text: string,null
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string

  • 400 — The organisationsnummer is not well-formed

    • error: string
    • message: string

  • 403 — Scope not granted, or the country is not granted (country_not_granted) or not provisioned (country_not_provisioned)

    • error: string
    • message: string

  • 429 — Paid API daily budget exceeded

    • error: string
    • message: string

  • 501 — The country is granted but this resource is not served there yet (country_not_supported)

    • error: string
    • message: string

  • 503 — Upstream unavailable, no cached data

    • error: string
    • message: string

GET /v1/documents/{id}

Section titled “GET /v1/documents/{id}”

Download a Bolagsverket document (e.g. an annual report)

  • Scope: kyb:read
  • Tags: documents

Responses:

  • 200 — Document content, base64-encoded

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.document_id: string
    • data.filename: string
    • data.content_type: string
    • data.content_base64: string
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string

  • 403 — Scope not granted, or SE is not among the countries this credential may read

    • error: string
    • message: string

  • 503 — Upstream unavailable, no cached data

    • error: string
    • message: string

GET /v1/persons/{ref}/engagements

Section titled “GET /v1/persons/{ref}/engagements”

A person’s beneficial-owner and officer engagements across companies

  • Scope: kyb:read
  • Tags: persons

Responses:

  • 200 — Engagements

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.schema_version: string
    • data.tenant_id: string
    • data.subject_id: string
    • data.person_ref: string,null
    • data.engagements[].orgnr: string
    • data.engagements[].role: string
    • data.engagements[].since: string,null
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string

  • 404 — No such identifier ref for this tenant, or it does not name a person

    • error: string
    • message: string

  • 429 — Paid API daily budget exceeded

    • error: string
    • message: string

  • 501 — The person is in a country no engagements connector serves yet (country_not_supported)

    • error: string
    • message: string

  • 503 — Upstream unavailable, no cached data

    • error: string
    • message: string

GET /v1/subjects/{id}

Section titled “GET /v1/subjects/{id}”

The canonical subject object, with its aliases, identifiers and references

  • Scope: kyb:read
  • Tags: subjects

Responses:

  • 200 — The subject

    • schema_version: string
    • tenant_id: string
    • subject_id: string
    • kind: enum (person | company)
    • created_at: string
    • identifiers[].identifier_ref: string
    • identifiers[].type: enum (personnummer | samordningsnummer | orgnr | imones-kodas | asmens-kodas)
    • identifiers[].country: enum (SE | LT)
    • identifiers[].valid_from: string
    • identifiers[].valid_to: string,null
    • refs[].ref: string
    • refs[].created_at: string
    • aliases[]: string
    • evidence.source: string
    • evidence.source_timestamp: string
    • evidence.call_ref: string
    • evidence.transaction_ref: string
    • evidence.upstream_ref: string,null
    • evidence.digest: string,null
    • evidence.schema_version: string,null
    • evidence.retrieved_at: string

  • 404 — No such subject for this tenant — or none with an identifier in a country this credential may see, which answers identically (SPEC-006d §2.5)

    • error: string
    • message: string

Scope: kyb:read or kyc:read

Section titled “Scope: kyb:read or kyc:read”

POST /v1/subjects/resolve

Section titled “POST /v1/subjects/resolve”

Resolve an identifier to a subject_id, creating one on first sight

  • Scope: kyb:read or kyc:read
  • Tags: subjects

Request body:

  • type: enum (personnummer | samordningsnummer | orgnr | imones-kodas | asmens-kodas)
  • value: string
  • ref: string

Responses:

  • 200 — The resolved subject

    • subject_id: string
    • aliases[]: string
    • identifier_ref: string

  • 400 — The identifier failed validation

    • error: string
    • message: string

  • 403 — Scope not granted, or the identifier’s country is not granted or not provisioned

    • error: string
    • message: string

  • 409 — The ref is already mapped to a different subject

    • error: string
    • message: string

Scope: kyb:refresh

Section titled “Scope: kyb:refresh”

POST /v1/companies/{orgnr}/refresh

Section titled “POST /v1/companies/{orgnr}/refresh”

Force a re-fetch of the company profile, emitting change events under an active subscription

  • Scope: kyb:refresh
  • Tags: companies

Responses:

  • 200 — Re-fetched company profile

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.schema_version: string
    • data.tenant_id: string
    • data.subject_id: string
    • data.orgnr: string
    • data.name: string
    • data.legal_form: string
    • data.status: string
    • data.registered_at: string,null
    • data.address.street: string,null
    • data.address.postal_code: string,null
    • data.address.city: string,null
    • data.address.country: string
    • data.sni[]: string
    • data.employees_band: string,null
    • data.tax.f_skatt: boolean
    • data.tax.vat: boolean
    • data.tax.employer: boolean
    • data.tax.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.tax.evidence.source_timestamp: string
    • data.tax.evidence.call_ref: string
    • data.tax.evidence.transaction_ref: string
    • data.tax.evidence.upstream_ref: string,null
    • data.tax.evidence.digest: string,null
    • data.tax.evidence.schema_version: string,null
    • data.tax.evidence.retrieved_at: string
    • data.latest_annual_report.year: integer
    • data.latest_annual_report.ref: string
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string
    • events_emitted: integer

  • 400 — The organisationsnummer is not well-formed

    • error: string
    • message: string

  • 403 — Scope not granted, or the country is not granted (country_not_granted) or not provisioned (country_not_provisioned)

    • error: string
    • message: string

  • 501 — The country is granted but this resource is not served there yet (country_not_supported)

    • error: string
    • message: string

  • 503 — Upstream unavailable, no cached data

    • error: string
    • message: string

Scope: kyc:read

Section titled “Scope: kyc:read”

GET /v1/persons/{ref}

Section titled “GET /v1/persons/{ref}”

The SPAR person profile — names, folkbokföring, address and protection markers

  • Scope: kyc:read
  • Tags: persons

Responses:

  • 200 — The person profile

    • stale: boolean
    • data.country: enum (SE | LT)
    • data.schema_version: string
    • data.tenant_id: string
    • data.subject_id: string
    • data.person_ref: string,null
    • data.names.given_name: string,null
    • data.names.middle_name: string,null
    • data.names.surname: string,null
    • data.names.notification_name: string,null
    • data.birth_date: string,null
    • data.folkbokforing.registered_at: string,null
    • data.folkbokforing.residence: string,null
    • data.folkbokforing.county_code: string,null
    • data.folkbokforing.municipality_code: string,null
    • data.address.street: string,null
    • data.address.postal_code: string,null
    • data.address.city: string,null
    • data.address.country: string
    • data.foreign_address.line_1: string,null
    • data.foreign_address.line_2: string,null
    • data.foreign_address.line_3: string,null
    • data.foreign_address.country_name: string,null
    • data.markers.protected: enum (none | sekretess | skyddad)
    • data.markers.protected_since: string,null
    • data.markers.deceased_date: string,null
    • data.markers.emigrated_date: string,null
    • data.latest_change_at: string,null
    • data.evidence.source: enum (bolagsverket.vardefulla-datamangder | bolagsverket.foretagsinformation | spar.personsokning | spar.avisering | skatteverket.uppgifter | scb.foretagsregister | customer.identity_event | gungner.gateway | gungner.derived | gungner.merge)
    • data.evidence.source_timestamp: string
    • data.evidence.call_ref: string
    • data.evidence.transaction_ref: string
    • data.evidence.upstream_ref: string,null
    • data.evidence.digest: string,null
    • data.evidence.schema_version: string,null
    • data.evidence.retrieved_at: string

  • 403 — The tenant has no active SPAR permit, or it is suspended

    • error: string
    • message: string

  • 404 — No such identifier ref for this tenant, it does not name a person, or SPAR holds no such person

    • error: string
    • message: string

  • 429 — SPAR daily call budget exceeded

    • error: string
    • message: string

  • 501 — The person is in a country no person connector serves yet (country_not_supported)

    • error: string
    • message: string

  • 503 — SPAR unavailable

    • error: string
    • message: string

Scope: monitoring:read or monitoring:subscribe or kyb:read or kyc:read

Section titled “Scope: monitoring:read or monitoring:subscribe or kyb:read or kyc:read”

GET /v1/subscriptions/{id}

Section titled “GET /v1/subscriptions/{id}”

One monitoring subscription

  • Scope: monitoring:read or monitoring:subscribe or kyb:read or kyc:read
  • Tags: subscriptions

Responses:

  • 200 — Subscription

    • subscription_id: string
    • subject_id: string
    • kind: enum (person | company)
    • legal_basis: enum (aml_cdd | contract | legal_obligation | consent | legitimate_interest)
    • legal_basis_ref: string,null
    • status: enum (active | suspended | ended)
    • check_days: integer
    • full_refresh_days: integer
    • created_at: string
    • suspended_at: string,null
    • ended_at: string,null
    • purge_after: string,null
    • next_run_at: string,null

  • 404 — No such subscription for this tenant

    • error: string
    • message: string

Scope: monitoring:subscribe

Section titled “Scope: monitoring:subscribe”

GET /v1/subscriptions

Section titled “GET /v1/subscriptions”

This tenant’s monitoring subscriptions

  • Scope: monitoring:subscribe
  • Tags: subscriptions

Responses:

  • 200 — Subscriptions

    • subscriptions[].subscription_id: string
    • subscriptions[].subject_id: string
    • subscriptions[].kind: enum (person | company)
    • subscriptions[].legal_basis: enum (aml_cdd | contract | legal_obligation | consent | legitimate_interest)
    • subscriptions[].legal_basis_ref: string,null
    • subscriptions[].status: enum (active | suspended | ended)
    • subscriptions[].check_days: integer
    • subscriptions[].full_refresh_days: integer
    • subscriptions[].created_at: string
    • subscriptions[].suspended_at: string,null
    • subscriptions[].ended_at: string,null
    • subscriptions[].purge_after: string,null
    • subscriptions[].next_run_at: string,null

POST /v1/subscriptions

Section titled “POST /v1/subscriptions”

Start monitoring a subject under a stated legal basis

  • Scope: monitoring:subscribe
  • Tags: subscriptions

Request body:

  • subject_id: string
  • kind: enum (person | company)
  • legal_basis: enum (aml_cdd | contract | legal_obligation | consent | legitimate_interest)
  • legal_basis_ref: string
  • check_days: integer
  • full_refresh_days: integer

Responses:

  • 201 — Subscription created

    • subscription_id: string
    • subject_id: string
    • kind: enum (person | company)
    • legal_basis: enum (aml_cdd | contract | legal_obligation | consent | legitimate_interest)
    • legal_basis_ref: string,null
    • status: enum (active | suspended | ended)
    • check_days: integer
    • full_refresh_days: integer
    • created_at: string
    • suspended_at: string,null
    • ended_at: string,null
    • purge_after: string,null
    • next_run_at: string,null

  • 400 — The legal basis is not one ADR-011 §2 names

    • error: string
    • message: string

  • 403 — Person kind without an active SPAR permit

    • error: string
    • message: string

  • 404 — No such subject for this tenant

    • error: string
    • message: string

  • 409 — An active subscription already covers this subject and kind

    • error: string
    • message: string

  • 501 — The subject holds identifiers only in a country no monitoring connector serves yet (country_not_supported)

    • error: string
    • message: string

POST /v1/subscriptions/{id}/end

Section titled “POST /v1/subscriptions/{id}/end”

Stop monitoring — one-way, cancels queued work immediately

  • Scope: monitoring:subscribe
  • Tags: subscriptions

Responses:

  • 200 — Subscription ended

    • subscription_id: string
    • subject_id: string
    • kind: enum (person | company)
    • legal_basis: enum (aml_cdd | contract | legal_obligation | consent | legitimate_interest)
    • legal_basis_ref: string,null
    • status: enum (active | suspended | ended)
    • check_days: integer
    • full_refresh_days: integer
    • created_at: string
    • suspended_at: string,null
    • ended_at: string,null
    • purge_after: string,null
    • next_run_at: string,null

  • 404 — No such subscription for this tenant

    • error: string
    • message: string

  • 409 — The subscription has already ended

    • error: string
    • message: string

Scope: screening:policy or screening:read

Section titled “Scope: screening:policy or screening:read”

GET /v1/screening/overrides

Section titled “GET /v1/screening/overrides”

List this tenant’s policy override versions

  • Scope: screening:policy or screening:read
  • Tags: Screening

Responses:

  • 200 — Versions, newest first

    • versions[].id: string
    • versions[].version: number
    • versions[].config: object
    • versions[].proposed_by: string
    • versions[].approved_by: string,null
    • versions[].status: enum (draft | approved | active | retired)
    • versions[].effective_from: string,null
    • versions[].created_at: string

GET /v1/screening/whitelist

Section titled “GET /v1/screening/whitelist”

List whitelist entries

  • Scope: screening:policy or screening:read
  • Tags: Screening

Responses:

  • 200 — Entries, newest first

    • entries[].id: string
    • entries[].subject_id: string,null
    • entries[].input_hash: string,null
    • entries[].source_id: string
    • entries[].source_entry_id: string
    • entries[].reason: string
    • entries[].created_by: string
    • entries[].approved_by: string,null
    • entries[].created_at: string
    • entries[].expires_at: string
    • entries[].revoked_at: string,null
    • entries[].effective: boolean

Scope: screening:read or screening:run

Section titled “Scope: screening:read or screening:run”

GET /v1/screening/checks

Section titled “GET /v1/screening/checks”

List screening checks

  • Scope: screening:read or screening:run
  • Tags: Screening

Responses:

  • 200 — Checks, newest first

    • checks[].id: string
    • checks[].subject_id: string,null
    • checks[].input_kind: enum (subject | adhoc)
    • checks[].input_snapshot.name: string,null
    • checks[].input_snapshot.birth_date: string,null
    • checks[].input_snapshot.nationalities[]: string
    • checks[].input_snapshot.country: string,null
    • checks[].input_snapshot.orgnr: string,null
    • checks[].input_snapshot.identifier_masked: boolean
    • checks[].input_snapshot.person_fields_masked: boolean
    • checks[].input_snapshot.input_hash: string,null
    • checks[].input_verified: boolean
    • checks[].band: enum (clear | review | hit)
    • checks[].candidate_count: number
    • checks[].policy_version_id: string
    • checks[].tenant_override_version_id: string,null
    • checks[].source_version_ids[]: string
    • checks[].degraded_sources[]: string
    • checks[].truncated_datasets[]: string
    • checks[].matcher_version: string
    • checks[].checked_at: string
    • checks[].candidates[].id: string
    • checks[].candidates[].entity_id: string
    • checks[].candidates[].source_id: string
    • checks[].candidates[].source_entry_id: string
    • checks[].candidates[].source_version_id: string
    • checks[].candidates[].score: number
    • checks[].candidates[].band: enum (clear | review | hit)
    • checks[].candidates[].reasons[].code: string
    • checks[].candidates[].reasons[].detail: string
    • checks[].candidates[].reasons[].contributes: enum (up | down | neutral)
    • checks[].candidates[].listing: object
    • checks[].candidates[].evidence: object
    • checks[].candidates[].whitelisted: boolean
    • checks[].candidates[].whitelist_id: string,null

POST /v1/screening/checks

Section titled “POST /v1/screening/checks”

Run a screening check

  • Scope: screening:read or screening:run
  • Tags: Screening

Request body:

  • subject_id: string
  • name: string
  • birth_date: string
  • nationalities[]: string
  • orgnr: string
  • country: string

Responses:

  • 201 — The check and its candidates

    • id: string
    • subject_id: string,null
    • input_kind: enum (subject | adhoc)
    • input_snapshot.name: string,null
    • input_snapshot.birth_date: string,null
    • input_snapshot.nationalities[]: string
    • input_snapshot.country: string,null
    • input_snapshot.orgnr: string,null
    • input_snapshot.identifier_masked: boolean
    • input_snapshot.person_fields_masked: boolean
    • input_snapshot.input_hash: string,null
    • input_verified: boolean
    • band: enum (clear | review | hit)
    • candidate_count: number
    • policy_version_id: string
    • tenant_override_version_id: string,null
    • source_version_ids[]: string
    • degraded_sources[]: string
    • truncated_datasets[]: string
    • matcher_version: string
    • checked_at: string
    • candidates[].id: string
    • candidates[].entity_id: string
    • candidates[].source_id: string
    • candidates[].source_entry_id: string
    • candidates[].source_version_id: string
    • candidates[].score: number
    • candidates[].band: enum (clear | review | hit)
    • candidates[].reasons[].code: string
    • candidates[].reasons[].detail: string
    • candidates[].reasons[].contributes: enum (up | down | neutral)
    • candidates[].listing: object
    • candidates[].evidence: object
    • candidates[].whitelisted: boolean
    • candidates[].whitelist_id: string,null

  • 400 — Invalid input, an organisationsnummer that is not well-formed, or a name that is a personal identity number (name_is_identifier)

    • error: string
    • message: string

  • 403 — No active SPAR permit, or the caller lacks kyc:read for a person subject

    • error: string
    • message: string

  • 404 — Subject not found

    • error: string
    • message: string

  • 429 — Daily budget exhausted

    • error: string
    • message: string

  • 501 — The identifier’s country is granted but not served for screening yet (country_not_supported)

    • error: string
    • message: string

  • 503 — Screening or person source unavailable

    • error: string
    • message: string

GET /v1/screening/checks/{id}

Section titled “GET /v1/screening/checks/{id}”

Read a screening check

  • Scope: screening:read or screening:run
  • Tags: Screening

Responses:

  • 200 — The check and its candidates

    • id: string
    • subject_id: string,null
    • input_kind: enum (subject | adhoc)
    • input_snapshot.name: string,null
    • input_snapshot.birth_date: string,null
    • input_snapshot.nationalities[]: string
    • input_snapshot.country: string,null
    • input_snapshot.orgnr: string,null
    • input_snapshot.identifier_masked: boolean
    • input_snapshot.person_fields_masked: boolean
    • input_snapshot.input_hash: string,null
    • input_verified: boolean
    • band: enum (clear | review | hit)
    • candidate_count: number
    • policy_version_id: string
    • tenant_override_version_id: string,null
    • source_version_ids[]: string
    • degraded_sources[]: string
    • truncated_datasets[]: string
    • matcher_version: string
    • checked_at: string
    • candidates[].id: string
    • candidates[].entity_id: string
    • candidates[].source_id: string
    • candidates[].source_entry_id: string
    • candidates[].source_version_id: string
    • candidates[].score: number
    • candidates[].band: enum (clear | review | hit)
    • candidates[].reasons[].code: string
    • candidates[].reasons[].detail: string
    • candidates[].reasons[].contributes: enum (up | down | neutral)
    • candidates[].listing: object
    • candidates[].evidence: object
    • candidates[].whitelisted: boolean
    • candidates[].whitelist_id: string,null

  • 404 — No such check

    • error: string
    • message: string

Envelope

Section titled “Envelope”

Every data read returns {data, stale}. stale: true means the value was served from cache past its revalidation window. GET /v1/subjects/{id} and POST /v1/subjects/resolve are un-enveloped: a subject is a database-native object, never fetched-with-TTL from an upstream.

Evidence

Section titled “Evidence”

Every field group carries: call_ref, digest, retrieved_at, schema_version, source, source_timestamp, transaction_ref, upstream_ref. See semantics.md §5.