Skip to content

Enrollments

GET /enrollments returns the list of program suppliers that a participant is enrolled with for a given time_frame. This endpoint is useful as a discovery step before calling GET /programs or POST /calculations. The response is intentionally small: it gives you supplier key and type, not full program metadata.

Why it matters

More Focused Request

Tip

Take advantage of enrollments data to dramatically reduce your calls to GET /programs and POST /calculations.

It narrows downstream requests to only program suppliers the participant has been enrolled with.

Indicates Program Supplier Type

Warning

Transactions in a request to POST /calculations (when program_supplier_type is distributor) that do not contain a value for seller.key will be ignored.

It returns each program supplier's type, which affects transaction payloads. When program_supplier_type is distributor, transactions should include seller.key as expected by distributor-based program logic.

Workflow

In practice, a common flow is:

  1. Call /enrollments with participant-key and time_frame.
  2. For each returned program_supplier_key, call /programs.
  3. Run /calculations only for suppliers/programs relevant to that participant.

The enrollment list is sorted by program_supplier_key, which keeps results stable and predictable between calls.

Request

Method and path

GET /enrollments?time_frame=<year>

Required headers

  • x-api-key: API key used for request authentication.
  • participant-key: participant identifier used to resolve enrollments.

Required query params

  • time_frame: the enrollment time frame (for example, 2024).

Example

curl \
  --silent \
  --header "x-api-key: xyz" \
  --header "participant-key: tcp_austin_tx_999" \
  "http://localhost:8000/enrollments?time_frame=2026"

Response

Fields

  • data: list of participant enrollments.
  • program_supplier_key: supplier key used by /programs and /calculations.
  • program_supplier_type: supplier type.
    • basic_manufacturer
    • distributor
  • errors: API error list (empty on success).
  • meta.api_version: API version used to process the request.

Each enrollment record comes from participant registry data filtered by:

  • participant_key from the request header
  • time_frame from the query string

Example response

{
  "data": [
    {
      "program_supplier_key": "agro_supply",
      "program_supplier_type": "distributor"
    },
    {
      "program_supplier_key": "bradley",
      "program_supplier_type": "basic_manufacturer"
    },
    {
      "program_supplier_key": "green_field_crop_solutions",
      "program_supplier_type": "distributor"
    },
    {
      "program_supplier_key": "terra_force_usa",
      "program_supplier_type": "basic_manufacturer"
    }
  ],
  "errors": [],
  "meta": {
    "api_version": "v1"
  }
}