---
title: "List participants behind a churn category"
method: GET
path: "/v1/aps/{key}/churn/participants"
tags: ["Access Points"]
---

# List participants behind a churn category

`GET /v1/aps/{key}/churn/participants`

## Request

- Base URL: `https://api.peppolstatus.com`
- URL: `https://api.peppolstatus.com/v1/aps/{key}/churn/participants`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

The drill-down: the participant IDs behind one churn category count for this Provider over the period, newest observation day first. `counterpart` narrows a mover category to the participants won from or lost to one Provider. Cursor-paginated in pages of at most 500: follow `next_cursor` until it is null. A Vendor key (`v-<slug>`) lists the Vendor's events, also accepts `newly_matched` and `no_longer_matched`, and adds `counterpart_kind` to each item.

## Path parameters

- `key` string, required

## Query parameters

- `category` 'joiner' | 'mover_in' | 'mover_out' | 'leaver' | 'newly_matched' | 'no_longer_matched', required
- `from` string, date
- `to` string, date
- `counterpart` string
- `limit` integer
- `cursor` string

## Response `200`

The participants in that category.

- ChurnParticipantPage: One page of the participants behind one churn category count.
  - `items` ChurnParticipant[], required
    - `id` string, required: Canonical `scheme::value` Peppol ID.
    - `scheme` string, required
    - `value` string, required
    - `day` string, date, required
    - `counterpart_key` string, nullable, required
    - `counterpart_name` string, nullable, required
    - `counterpart_kind` 'provider' | 'vendor' | 'null', nullable: On a Vendor's drill-down only: whether the counterpart is a Provider or another Vendor; null when the category has no counterpart.
    - `name` string, nullable, required: Current registered display name of the participant; null when the Directory publishes none.
    - `country` string, nullable, required: ISO-3166-1 alpha-2 country of the participant; null when none is known.
    - `company_entity_type` string, nullable, required: Company legal-form family (company|natural_person|association|public), or null when unmatched.
    - `company_sector` string, nullable, required: Company NACE Rev. 2.1 division (2-digit, one of 87; never 45), or null. Derived from the register code by its nomenclature: a Rev. 1-era code (e.g. NAF 1993, NACE-BEL 2003) gives null.
    - `company_size` string, nullable, required: Company size band code, or null. Stored codes: the INSEE trancheEffectifs codes for FR (e.g. `21`; `NN` = unknown), and for NO the same code set plus `1-4`. No other register has a size.
    - `company_region` string, nullable, required: Company seat region code, or null. A bare INSEE région code for FR (e.g. `84`); ISO 3166-2 for BE, NO and SK (e.g. `BE-VLG`). No other register has a region.
    - `company_sector_label` string, nullable, required: English NACE Rev. 2.1 label of company_sector (e.g. 62 → "Computer programming and consultancy"), or null when company_sector is null or unknown.
    - `company_size_label` string, nullable, required: English size band label of company_size (e.g. 21 → "50–99 employees", NN → "Size unknown"). Equal to the code when the code is unknown; null when company_size is null.
    - `company_region_label` string, nullable, required: Region name of company_region in the local language (e.g. 84 → "Auvergne-Rhône-Alpes", BE-VLG → "Flanders"). Equal to the code when the code is unknown; null when company_region is null.
  - `next_cursor` string, nullable, required: Opaque cursor for the next page, or null on the last page.

## Other responses

- `400`: A missing or invalid `category`, an invalid `limit`, or a `counterpart` on a category that has none.

---

[API](https://skmtc.dev/peppolstatus/apis/peppolstatus-api.md) · [All operations](https://skmtc.dev/peppolstatus/apis/peppolstatus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/peppolstatus/apis/peppolstatus-api/revisions/7e74fb32f23c?raw)