> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clevis.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List all available payroll schemes

> Returns every loaded payroll scheme across all countries.



## OpenAPI

````yaml /openapi.json get /v1/payroll/schemes
openapi: 3.1.0
info:
  title: Payroll API
  description: >

    ## Payroll Infrastructure API for Latin America


    **Stripe for payroll** — embedded payroll calculation infrastructure.


    ### Overview


    This API performs payroll calculations for Mexico, Colombia, Brazil,
    Argentina,

    and Chile. It is a **pure computation engine**: give it employee data, get
    back

    a fully itemized payroll breakdown.


    ### Key concepts


    - **Scheme** — A country-specific payroll ruleset (e.g., Mexico `ordinario`,
    Colombia `integral`).
      Use `GET /v1/payroll/schemes/{country}` to discover available schemes.
    - **Calculation** — A single employee payroll run for one period.

    - **Audit trail** — A step-by-step trace of every formula evaluated.
    Required for
      legal compliance in most Latin American countries.

    ### Decimal precision


    All monetary amounts are returned as **JSON strings** (not numbers) to
    prevent

    floating-point precision loss in client languages. Parse them with your
    language's

    `Decimal` type before doing any arithmetic.


    ```

    ✅ correct:  {"net_salary": "20039.25"}

    ❌ wrong:    {"net_salary": 20039.25}  // could lose precision

    ```


    ### Authentication


    All endpoints require a Bearer API key:

    ```

    Authorization: Bearer your_api_key_here

    ```


    ### Error format


    All errors follow a consistent structure:

    ```json

    {
      "error": {
        "code": "SCHEME_NOT_FOUND",
        "message": "Human-readable description",
        "details": {},
        "request_id": "abc123"
      }
    }

    ```


    Use the `code` field (not the HTTP status) for programmatic error handling.

    The `request_id` links to server logs — include it when contacting support.


    ### Payouts (mock provider)


    The `/v1/payouts` surface lets you pay an employee their `net_salary` after
    a

    calculation. In v1 every payout is handled by an **in-process mock
    provider** —

    no real funds are moved. Every response is marked with `mock: true` in the
    body

    and `X-Clevis-Mock: true` as a response header.


    - Magic `external_id` prefixes (`MOCK_REJECT_INTAKE_`, `MOCK_REJECT_BANK_`,
      `MOCK_SLOW_`, `MOCK_STUCK_`, `MOCK_OK_`) trigger deterministic outcomes for
      demos and tests.
    - `processing.step_seconds: 0` makes the payout transition to its terminal
      status synchronously before the response is returned.
    - Idempotency is supported via the `Idempotency-Key` header or via the
      `external_id` field (per API key).

    See `docs/specs/04_payout_mock_endpoint.md` for the full contract. The real

    dLocal integration will be a config flip behind the same interface; this

    client-facing contract does not change.
  contact:
    name: Payroll API Support
    email: api@payroll.io
  license:
    name: Proprietary
  version: 1.0.0
servers: []
security: []
tags:
  - name: Payroll
    description: Payroll calculation endpoints. All monetary values are JSON strings.
  - name: Payouts
    description: >-
      Single-beneficiary payout endpoints backed by an in-process **mock**
      provider in v1 — no real funds are moved. Every response carries `mock:
      true` and the `X-Clevis-Mock: true` header. Magic trigger values (e.g.
      `external_id` prefixed with `MOCK_REJECT_BANK_`) force deterministic
      outcomes for demos and tests.
  - name: Schemes & Health
    description: Discover available payroll schemes and check service health.
  - name: Health
    description: Service health and readiness checks.
paths:
  /v1/payroll/schemes:
    get:
      tags:
        - Schemes & Health
      summary: List all available payroll schemes
      description: Returns every loaded payroll scheme across all countries.
      operationId: Schemes & Health_list_all_schemes
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeListResponse'
components:
  schemas:
    SchemeListResponse:
      properties:
        country:
          type: string
          title: Country
        schemes:
          items:
            $ref: '#/components/schemas/SchemeInfo'
          type: array
          title: Schemes
        total:
          type: integer
          title: Total
      type: object
      required:
        - country
        - schemes
        - total
      title: SchemeListResponse
      description: Response for GET /v1/payroll/schemes/{country}.
    SchemeInfo:
      properties:
        id:
          type: string
          title: Id
          description: Scheme identifier. Used in calculation requests.
        legal_name:
          type: string
          title: Legal Name
        country:
          type: string
          title: Country
        currency:
          type: string
          title: Currency
        effective_from:
          type: string
          title: Effective From
        effective_until:
          anyOf:
            - type: string
            - type: 'null'
          title: Effective Until
        version:
          type: string
          title: Version
        status:
          type: string
          enum:
            - active
            - expired
            - future
          title: Status
        concept_count:
          type: integer
          title: Concept Count
          description: Total number of computable concepts in this scheme.
        legal_references:
          items:
            type: string
          type: array
          title: Legal References
        dsl_path:
          type: string
          title: Dsl Path
          description: Path to the DSL file (relative to rules/).
        changelog:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Changelog
      type: object
      required:
        - id
        - legal_name
        - country
        - currency
        - effective_from
        - effective_until
        - version
        - status
        - concept_count
        - legal_references
        - dsl_path
      title: SchemeInfo
      description: Metadata about one available payroll scheme.

````