list_participants

{
  "type": "object",
  "properties": {
    "sort": {
      "type": "string",
      "enum": [
        "first_seen.desc",
        "first_seen.asc",
        "name.asc",
        "name.desc",
        "country.asc",
        "country.desc",
        "registered.asc",
        "registered.desc",
        "entity_type.asc",
        "entity_type.desc",
        "sector.asc",
        "sector.desc"
      ],
      "default": "first_seen.desc",
      "description": "Sort + keyset key. `registered`, `entity_type` (the Type column) and `sector` (the Activity / NACE-division column) order over `(<col>, first_seen_at, id)`; the `entity_type`/`sector` views show only enriched (non-null) participants. It is IGNORED when `doctype`/`transport_profile`/`host` is set WITHOUT any other narrowing filter, and when `sub_provider` is set without `q` or one of those endpoint filters — those results are driven from the matching index and ordered by identifier (`scheme`, `value`), the only ordering that stays inside the query timeout. Otherwise (an endpoint filter combined with `country`/`smp`/`ap`/`registered`/`provenance`/`q`, or `sub_provider` with `q`) the normal sort applies."
    },
    "country": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of ISO country codes (`BE,NL`)."
    },
    "scheme": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of Peppol identifier schemes."
    },
    "smp": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of current SMP hostnames (`smp1.example,smp2.example`)."
    },
    "ap": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of serving Access Point SeatIDs (`PBE000123,PNO000456`)."
    },
    "doctype": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of Peppol document type ids. Matches a participant if ANY of its current endpoints declares one of the given doctypes. Used ALONE (no other filter) results are ordered by identifier and `sort` is ignored; combined with another filter the requested `sort` applies."
    },
    "transport_profile": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of transport profile ids (`peppol-transport-as4-v2_0`). Matches a participant if ANY of its current endpoints uses one of the given profiles. Used ALONE (no other filter) results are ordered by identifier and `sort` is ignored; combined with another filter the requested `sort` applies."
    },
    "host": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of endpoint-URL hostnames (`ap.example.com`). Matches a participant if ANY of its current endpoints publishes an endpoint URL on one of the given hosts — the exact participant set an Access Point host serves. Case-insensitive. Used ALONE (no other filter) results are ordered by identifier and `sort` is ignored; combined with another filter the requested `sort` applies."
    },
    "sub_provider": {
      "type": "string",
      "description": "ONE curated sub-provider (reseller) slug (`codabox`) — the same slugs `GET /v1/aps/{key}` reports in `sub_providers[].sub_provider`. Matches a participant the daily rollup fingerprinted to that brand on ANY of its current endpoints, from three signals: the SMP `ServiceDescription`, the SMP technical-contact domain, and the endpoint host. Only curated names resolve, so the free-text long tail is not addressable here. Unlike the other filters this one takes a single value: a comma list, or a value that is not a slug (lowercase alphanumerics, dash-separated), is a 400. The sub-provider is an ADDITIVE annotation — the `ap` seat stays the operator of record. Results are ordered by identifier (`scheme`, `value`) and `sort` is ignored, EXCEPT alongside `q` or `doctype`/`transport_profile`/`host`, where the requested `sort` applies. Combining it with any other filter (`country`, `scheme`, `smp`, `ap`, `registered`, `provenance`, `entity_type`, `sector`, `size`, `region`, `postcode`, `vat_liable`) evaluates that filter against the rollup's DAILY SNAPSHOT of those participant columns, not the live row — a participant changing SMP or country is reflected here on the next rollup. Those combinations report an exact `meta.filter_count` (`filter_count_source: \"exact\"`); adding `q` or an endpoint filter falls back to the bounded count."
    },
    "registered": {
      "type": "boolean",
      "description": "Filter by current SML registration state."
    },
    "provenance": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "directory",
          "discovered"
        ]
      },
      "description": "Comma-array of provenance values."
    },
    "entity_type": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of company legal-form families (`company`,`natural_person`,`association`,`public`), from the company-register enrichment denormalized onto the participant."
    },
    "sector": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of 2-digit NACE divisions (`47,62`)."
    },
    "size": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of company size classes (as stored; SIRENE only)."
    },
    "region": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of company seat region codes (`BE-BRU,BE-VLG`)."
    },
    "postcode": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comma-array of company seat postcodes."
    },
    "vat_liable": {
      "type": "boolean",
      "description": "Filter by company VAT-liable / mandate-scope flag."
    },
    "q": {
      "type": "string",
      "description": "Smart search: `scheme::value`/bare value → ID lookup; else name-contains."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Page size, clamped to [1, 200]. Defaults to 50."
    },
    "cursor": {
      "type": "string",
      "description": "Opaque pagination cursor returned as `next_cursor` by the previous page."
    }
  }
}