API Reference

Status: under development. Target interface, may evolve until 1.0.

All endpoints require a secret API key. Requests may carry an X-Request-Id header (UUID v4); it is echoed in the response and logged on both sides as the reconciliation key.

POST /v1/screening/screen

Screen up to 100 subjects in one request.

Authentication: API key (secret)

Request

POST /v1/screening/screen
Authorization: Bearer oat_your_secret_key
Content-Type: application/json

{
  "subjects": [
    {
      "reference": "NEF-2026-004182",
      "type": "individual",
      "name": "Jean-Pierre Martin",
      "birth_date": "1974-03-12",
      "nationalities": ["FR"],
      "country_of_residence": "FR",
      "identifiers": [
        { "type": "passport", "value": "18AB94721", "country": "FR" }
      ]
    }
  ],
  "options": {
    "sources": ["ofac_sdn", "ofac_cons", "fr_tresor_gels", "pep_fr"],
    "threshold": 0.75,
    "include_weak_aliases": false
  }
}

Field	Type	Required	Description
`subjects[].reference`	string	Yes	Caller's internal reference, echoed back verbatim. Must not contain personal data.
`subjects[].type`	enum	Yes	`individual`, `entity`, `vessel`, `aircraft`
`subjects[].name`	string	Yes	Full name as collected
`subjects[].birth_date`	string	No	`YYYY-MM-DD`, or `YYYY` if only the year is known
`subjects[].nationalities`	string[]	No	ISO 3166-1 alpha-2; strongly improves precision
`subjects[].identifiers`	array	No	Passport, residence permit, national or registration identifier
`options.sources`	string[]	No	Defaults to every source enabled on the account
`options.threshold`	number	No	Restitution threshold, 0 to 1. Default 0.75
`options.include_weak_aliases`	boolean	No	Include aliases flagged weak by the source. Default `false`

Response `200`

{
  "screening_id": "scr_01J9XQ2M4K7P3N8V",
  "screened_at": "2026-07-31T09:14:22Z",
  "list_versions": {
    "ofac_sdn": { "version": "2026-07-30", "retrieved_at": "2026-07-31T06:00:11Z" },
    "fr_tresor_gels": { "version": "2026-07-29", "retrieved_at": "2026-07-31T05:30:02Z" }
  },
  "results": [
    {
      "reference": "NEF-2026-004182",
      "status": "potential_match",
      "matches": [
        {
          "entity_id": "ent_01J9XQ3P8T2M6R4W",
          "score": 0.91,
          "match_type": "name_and_registration",
          "matched_fields": ["name", "registration_number"],
          "list": "fr_tresor_gels",
          "category": "sanction",
          "entity": {
            "type": "entity",
            "primary_name": "SOCIETE GENERALE DE NEGOCE",
            "aliases": ["SGN SARL"],
            "regimes": [
              {
                "code": "UE_SYRIE",
                "label": "Régime UE Syrie",
                "legal_basis": "Règlement (UE) n° 36/2012",
                "listed_at": "2023-11-14"
              }
            ],
            "source_url": "https://gels-avoirs.dgtresor.gouv.fr/..."
          }
        }
      ]
    }
  ]
}

status is clear, potential_match or error. category is sanction, pep or pep_rca.

Each submitted subject counts as one billable unit, whatever the batching.

GET /v1/screening/screenings/:screening_id

Replays a past screening identically, including the list versions in force at the time of the call. This is the evidence endpoint. Retention: 5 years by default (L.561-12 CMF baseline); longer retention is configurable contractually.

Authentication: API key (secret)

GET /v1/screening/entities/:entity_id

Full record of a designated entity: names and aliases, birth data, nationalities, identifiers, every applicable regime with legal basis and designation dates, known addresses, digital asset addresses when present, and the link to the original source. For PEPs: functions held with start and end dates, jurisdiction, level, and declared family or association links.

Authentication: API key (secret)

GET /v1/screening/lists

Health and versions of the sources enabled on the account. Poll it from your monitoring.

Authentication: API key (secret)

Response `200`

{
  "lists": [
    {
      "id": "fr_tresor_gels",
      "label": "Registre national des gels — DG Trésor",
      "version": "2026-07-29",
      "retrieved_at": "2026-07-31T05:30:02Z",
      "record_count": 4187,
      "status": "healthy"
    }
  ]
}

A stale status means a source has not refreshed within the contractual window and should raise an alert on your side as on ours.

POST /v1/screening/subjects

Registers a subject for continuous screening. It is re-screened on every source update; any new match triggers a webhook signed with HMAC-SHA256 (X-Webhook-Signature, same scheme and retry policy as monitoring webhooks).

Authentication: API key (secret)

{
  "reference": "NEF-2026-004182",
  "type": "individual",
  "name": "Jean-Pierre Martin",
  "birth_date": "1974-03-12",
  "nationalities": ["FR"]
}

Related: GET /v1/screening/subjects, DELETE /v1/screening/subjects/:reference.

POST /v1/screening/exports/audit

Produces a timestamped, signed export of screenings over a period: subject, reference, result, matches, applied threshold, list versions. CSV and JSON. Designed for inspection evidence.

Authentication: API key (secret)

Errors

{
  "error": "The 'name' field is required for subject at index 3.",
  "request_id": "3f8a1c40-9d2e-4b71-8c05-1a7e6f2b4d90"
}

Code	Condition
`400`	Malformed request
`401`	Missing, expired or invalid API key
`403`	Publishable key used, or source not enabled on the account
`422`	Valid request but unprocessable subject
`429`	Rate limit exceeded, see `Retry-After`
`503`	Temporary unavailability. No screening is deemed performed.

A 503 must never be interpreted as clear: replay the screening. Standard rate limit is 200 requests per minute per API key; dedicated throughput is available contractually.

On this page