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

# Configure program participation

> Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_configure. Upserts locations, groups and non-overlapping periods; provide period or periods (periods wins if both exist). At most one period may be open. IDs update existing rows; absent IDs match normalized location/group names or period names before creating. Omitted locations/groups remain. Current placements or draft checks prevent deactivation. Required/profile field keys must belong to this program and any assignee must be an active organization user. Returns a fresh overview and increments setup revision; revision conflicts return 422.



## OpenAPI

````yaml put /admin/programs/{program_id}/participation/setup
openapi: 3.0.0
info:
  title: Gratona API
  description: >-
    REST API for the Gratona fundraising platform, including donor, donation,
    sponsorship, program, event, and integration workflows. Endpoints are
    organized by tag. Most endpoints require either a Passport bearer token or
    an issued API key — see the Security Schemes section.
  contact:
    name: Gratona Engineering
    url: https://gratona.com
    email: devs@gratona.com
  version: 1.0.0
servers:
  - url: https://api.gratona.com/v1
    description: Server Version 1.0.0
security: []
tags:
  - name: Auth
    description: >-
      Login, signup, logout, password reset, and email verification for admin
      users and donors.
  - name: Donors
    description: >-
      Donor records: CRUD, profile fields, household linkage, search, filters,
      merge, and duplicate detection.
  - name: Donations
    description: >-
      Individual donation records, recurring commitments, soft credits, refunds,
      designations, and exports.
  - name: Sponsorships
    description: >-
      Donor-to-entity commitment relationships, lifecycle transitions, and
      commitment-specific filters.
  - name: Entities
    description: >-
      Recipient records (children, families, projects, animals, etc.), their
      status, and entity-level fields.
  - name: Programs
    description: >-
      Program / campaign configuration: hierarchy, settings, and program-level
      metadata.
  - name: Forms
    description: >-
      Custom form builder (HysForm), form fields, standardized donor fields, and
      field migrations.
  - name: Trips
    description: >-
      Mission-trip management: trips, participants, budgets, tasks,
      e-signatures, fundraising milestones, and background checks.
  - name: Communications
    description: >-
      Email templates, SMS, newsletters, donor email manager, and per-donor
      notes.
  - name: Payments
    description: >-
      Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks).
      Excludes inbound webhooks — see the Webhooks tag.
  - name: Reports
    description: Dashboards, analytics, scheduled reports, and exports.
  - name: Admin
    description: >-
      Client-account administration: users, groups/permissions, settings,
      integrations, and account lifecycle.
  - name: Donor Portal
    description: >-
      Endpoints consumed by the donor-facing portal (donor login, dashboard,
      donation history, messages).
  - name: Recipient Portal
    description: Endpoints consumed by the recipient-facing portal.
  - name: Public
    description: >-
      Unauthenticated public endpoints: donor signup, public trip pages,
      peer-to-peer campaigns, public checkout.
  - name: Webhooks
    description: >-
      Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr,
      DropboxSign). Annotated minimally for reference; payload shapes are owned
      by the upstream provider.
  - name: Events
    description: >-
      Event setup, invitations, registration, ticketing, attendance and event
      reporting.
  - name: Journeys
    description: >-
      Journey graphs, activation, enrollment, message templates and event
      follow-up automations.
  - name: Tasks
    description: Workspace tasks, assignments, saved task views and record collaboration.
  - name: Fundraising
    description: >-
      Fundraising portfolios, stewardship plans, giving anniversaries and
      personal donor follow-up.
  - name: Impact Stories
    description: Story intake, review, assets, consent and publication workflows.
  - name: Integrations
    description: Workspace integration connections, mappings, synchronization and recovery.
  - name: Email Calendar
    description: Connected email/calendar accounts and donor interactions.
  - name: Spaces
    description: Workspace Spaces and collaborative Pages.
  - name: Library
    description: Workspace documents, source connections, files and analysis.
  - name: Intelligence
    description: Donor intelligence and Tali workspace workflows.
  - name: Automation
    description: >-
      V3 automation primitive discovery, input validation, invocation and Zapier
      contracts.
  - name: Schema
    description: V3 model, enum, capability and scope discovery.
  - name: Zapier
    description: Zapier automation connections, polling feeds and actions.
  - name: Files
    description: Files
  - name: Client
    description: Client
  - name: Payment Gateways
    description: Payment Gateways
  - name: Email Settings
    description: Email Settings
  - name: Admin Dashboard
    description: Admin Dashboard
  - name: Recipients
    description: Recipients
  - name: Historical Archived Updates
    description: Historical Archived Updates
  - name: Team & access
    description: Team & access
  - name: Settings
    description: Settings
  - name: Notifications
    description: Notifications
  - name: Participation
    description: Participation
  - name: Users
    description: Users
  - name: Wrapped
    description: Wrapped
  - name: Donor SignUp
    description: Donor SignUp
  - name: Frontend
    description: Frontend
  - name: User
    description: User
  - name: Workspace
    description: Workspace
paths:
  /admin/programs/{program_id}/participation/setup:
    put:
      tags:
        - Participation
      summary: Configure program participation
      description: >-
        Requires the participation feature, programs_view and access to this
        organization-owned program. Requires participation_configure. Upserts
        locations, groups and non-overlapping periods; provide period or periods
        (periods wins if both exist). At most one period may be open. IDs update
        existing rows; absent IDs match normalized location/group names or
        period names before creating. Omitted locations/groups remain. Current
        placements or draft checks prevent deactivation. Required/profile field
        keys must belong to this program and any assignee must be an active
        organization user. Returns a fresh overview and increments setup
        revision; revision conflicts return 422.
      operationId: docParticipationConfigurePUT
      parameters:
        - name: program_id
          in: path
          description: >-
            Program whose participation setup, placements and checks are being
            accessed.
          required: true
          schema:
            type: integer
            minimum: 1
          example: 123
      requestBody:
        description: >-
          Request fields accepted by this operation. Omitted optional properties
          retain the behavior described above.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipationSetupInputReference'
      responses:
        '200':
          description: Configure program participation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipationOverviewReference'
        '401':
          description: Missing or invalid bearer token or API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '403':
          description: >-
            The caller lacks the required permission, resource access or feature
            availability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The organization-owned resource or parent was not found or is not
            available for this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Request validation or a domain constraint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestRejection'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    ParticipationSetupInputReference:
      required:
        - sites
      properties:
        revision:
          description: Optional optimistic setup revision; a mismatch returns 422.
          type: integer
          minimum: 1
          nullable: true
        enabled:
          description: Omitted defaults to true, including an existing disabled setup.
          type: boolean
        terminology:
          type: string
          enum:
            - school
            - general
        default_session_type:
          type: string
          enum:
            - roster_verification
        cadence:
          type: string
          enum:
            - weekly
            - biweekly
            - monthly
            - flexible
        default_evidence_source:
          type: string
          enum:
            - official_record
            - headcount
            - staff_confirmation
            - participant_confirmation
            - legacy_import
            - other
        allowed_evidence_sources:
          description: >-
            Allowed evidence sources; the configured default evidence source is
            added automatically if absent.
          type: array
          items:
            type: string
            enum:
              - official_record
              - headcount
              - staff_confirmation
              - participant_confirmation
              - legacy_import
              - other
          minItems: 1
        site_field_id:
          type: integer
          minimum: 1
          example: 42
          nullable: true
        cohort_field_id:
          type: integer
          minimum: 1
          example: 42
          nullable: true
        required_intake_field_keys:
          type: array
          items:
            type: string
            maxLength: 100
          maxItems: 25
        profile_ready_field_keys:
          description: >-
            An empty array disables custom-field readiness requirements; keys
            must belong to the program recipient form.
          type: array
          items:
            type: string
            maxLength: 100
          maxItems: 100
        profile_photo_required:
          type: boolean
        unresolved_check_threshold:
          type: integer
          maximum: 52
          minimum: 1
        dropout_review_after_days:
          description: 'Validation: `nullable|integer|min:1|max:365`.'
          type: integer
          maximum: 365
          minimum: 1
          nullable: true
        follow_up_due_days:
          type: integer
          maximum: 365
          minimum: 1
        follow_up_assignee_user_id:
          type: integer
          minimum: 1
          example: 42
          nullable: true
        sites:
          type: array
          items:
            required:
              - name
              - cohorts
            properties:
              id:
                type: integer
                minimum: 1
                example: 42
                nullable: false
              name:
                type: string
                maxLength: 255
                minLength: 1
                example: Main campus
              code:
                type: string
                maxLength: 100
                nullable: true
              site_type:
                type: string
                enum:
                  - school
                  - center
                  - clinic
                  - community
                  - distribution_point
                  - outreach_area
                  - other
              status:
                type: string
                default: active
                enum:
                  - active
                  - inactive
              legacy_values:
                type: array
                items:
                  type: string
                  maxLength: 255
                maxItems: 25
              cohorts:
                type: array
                items:
                  required:
                    - name
                  properties:
                    id:
                      type: integer
                      minimum: 1
                      example: 42
                      nullable: false
                    name:
                      type: string
                      maxLength: 255
                      minLength: 1
                      example: Group A
                    code:
                      type: string
                      maxLength: 100
                      nullable: true
                    sort_order:
                      type: integer
                      maximum: 10000
                      minimum: 0
                    status:
                      type: string
                      default: active
                      enum:
                        - active
                        - inactive
                    legacy_values:
                      type: array
                      items:
                        type: string
                        maxLength: 255
                      maxItems: 25
                  type: object
                maxItems: 100
                minItems: 1
            type: object
          maxItems: 100
          minItems: 1
        period:
          required:
            - name
            - starts_on
            - ends_on
          properties:
            id:
              type: integer
              minimum: 1
              example: 42
              nullable: false
            name:
              type: string
              maxLength: 255
              minLength: 1
              example: 2026 term
            starts_on:
              type: string
              format: date
              example: '2026-10-20'
              nullable: false
            ends_on:
              description: >-
                Must be on or after starts_on; periods in one program cannot
                overlap.
              type: string
              format: date
              example: '2026-12-31'
            status:
              type: string
              default: open
              enum:
                - draft
                - open
                - closed
          type: object
        periods:
          type: array
          items:
            required:
              - name
              - starts_on
              - ends_on
            properties:
              id:
                type: integer
                minimum: 1
                example: 42
                nullable: false
              name:
                type: string
                maxLength: 255
                minLength: 1
                example: 2026 term
              starts_on:
                type: string
                format: date
                example: '2026-10-20'
                nullable: false
              ends_on:
                description: >-
                  Must be on or after starts_on; periods in one program cannot
                  overlap.
                type: string
                format: date
                example: '2026-12-31'
              status:
                type: string
                default: open
                enum:
                  - draft
                  - open
                  - closed
            type: object
          maxItems: 50
          minItems: 1
        access_scopes:
          description: >-
            When present replaces all program role scopes; an empty list removes
            scope restrictions. Null cohort_id permits all cohorts at that site.
          type: array
          items:
            required:
              - group_id
              - site_id
            properties:
              group_id:
                type: integer
                minimum: 1
                example: 42
                nullable: false
              site_id:
                type: integer
                minimum: 1
                example: 42
                nullable: false
              cohort_id:
                type: integer
                minimum: 1
                example: 42
                nullable: true
            type: object
          maxItems: 1000
      type: object
      anyOf:
        - required:
            - period
          type: object
        - required:
            - periods
          type: object
    ParticipationOverviewReference:
      required:
        - feature_enabled
        - configured
        - program
        - selected_period_id
        - schedule
        - settings
        - periods
        - sites
        - summary
        - capabilities
        - intake_fields
        - recipient_creation
        - configuration
      properties:
        feature_enabled:
          type: boolean
          example: true
        configured:
          description: >-
            True when participation settings are enabled, an active accessible
            site exists and a period is open.
          type: boolean
        program:
          $ref: '#/components/schemas/ParticipationNamedIdReference'
        selected_period_id:
          type: integer
          minimum: 1
          example: 42
          nullable: true
        schedule:
          oneOf:
            - allOf:
                - $ref: '#/components/schemas/ParticipationScheduleReference'
            - type: string
              enum:
                - null
              nullable: true
        settings:
          oneOf:
            - allOf:
                - $ref: '#/components/schemas/ParticipationSettingsReference'
            - type: string
              enum:
                - null
              nullable: true
        periods:
          type: array
          items:
            $ref: '#/components/schemas/ParticipationPeriodReference'
        sites:
          type: array
          items:
            required:
              - id
              - name
              - code
              - site_type
              - roster_count
              - cohorts
            properties:
              id:
                type: integer
              name:
                type: string
              code:
                type: string
                nullable: true
              site_type:
                type: string
              roster_count:
                type: integer
              cohorts:
                type: array
                items:
                  required:
                    - id
                    - name
                    - roster_count
                    - can_start
                    - next_check_on
                    - missed_windows
                    - latest_session
                    - completion_status
                    - scheduled_session
                    - schedule_status
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    roster_count:
                      type: integer
                    can_start:
                      type: boolean
                    next_check_on:
                      type: string
                      format: date
                      nullable: true
                    missed_windows:
                      type: integer
                    latest_session:
                      oneOf:
                        - allOf:
                            - $ref: >-
                                #/components/schemas/ParticipationSessionSummaryReference
                        - type: string
                          enum:
                            - null
                          nullable: true
                    completion_status:
                      type: string
                      enum:
                        - complete
                        - in_progress
                        - not_started
                    scheduled_session:
                      oneOf:
                        - allOf:
                            - $ref: >-
                                #/components/schemas/ParticipationSessionSummaryReference
                        - type: string
                          enum:
                            - null
                          nullable: true
                    schedule_status:
                      type: string
                      enum:
                        - upcoming
                        - closed
                        - in_progress
                        - complete
                        - overdue
                        - due
                  type: object
            type: object
        summary:
          required:
            - recipients_with_current_placement
            - recipients_without_current_placement
            - draft_sessions
            - unresolved_recipients
            - verified_recipients
            - period_unresolved_recipients
            - new_recipients
            - transferred_recipients
            - withdrawn_recipients
            - incomplete_profiles
            - completed_cohorts
            - expected_cohorts
          properties:
            recipients_with_current_placement:
              type: integer
            recipients_without_current_placement:
              type: integer
            draft_sessions:
              type: integer
            unresolved_recipients:
              type: integer
            verified_recipients:
              type: integer
            period_unresolved_recipients:
              type: integer
            new_recipients:
              type: integer
            transferred_recipients:
              type: integer
            withdrawn_recipients:
              type: integer
            incomplete_profiles:
              type: integer
            completed_cohorts:
              type: integer
            expected_cohorts:
              type: integer
          type: object
        capabilities:
          required:
            - view
            - record
            - submit
            - configure
            - scope
          properties:
            view:
              type: boolean
            record:
              type: boolean
            submit:
              type: boolean
            configure:
              type: boolean
            scope:
              $ref: '#/components/schemas/ParticipationScopeReference'
          type: object
        intake_fields:
          description: >-
            Program recipient fields for callers with record capability;
            otherwise empty.
          type: array
          items:
            $ref: '#/components/schemas/ParticipationRecipientFieldReference'
        recipient_creation:
          oneOf:
            - allOf:
                - $ref: >-
                    #/components/schemas/ParticipationRecipientCreationOptionsReference
            - type: string
              enum:
                - null
              nullable: true
        configuration:
          oneOf:
            - allOf:
                - $ref: '#/components/schemas/ParticipationConfigurationReference'
            - type: string
              enum:
                - null
              nullable: true
      type: object
    UnauthorizedResponse:
      title: UnauthorizedResponse
      description: >-
        Returned with HTTP 401 when the request lacks a valid Passport bearer
        token, a valid `X-HYS-API-Key`, or a valid session. The body is the
        simple `{message, status}` envelope emitted by `AuthenticateApiOrKey`.
      required:
        - message
        - status
      properties:
        message:
          description: >-
            Always the literal string `Unauthorized` from the `auth.api_or_key`
            middleware. Login endpoints return `Invalid Credentials` instead.
          type: string
          example: Unauthorized
        status:
          type: string
          example: error
      type: object
    ErrorResponse:
      title: ErrorResponse
      description: >-
        Generic error envelope used by most controllers. Most error responses
        pair a human-readable `message` with `status: error`. Some endpoints
        additionally include `errors` (validator errors), `error` (legacy
        single-error string), `code`, or domain-specific context fields.
      required:
        - message
      properties:
        message:
          description: Human-readable error message.
          type: string
          example: Something went wrong. Please try again.
        status:
          description: >-
            Always the literal string `error` for failures. Some endpoints omit
            this field.
          type: string
          example: error
        error:
          description: Legacy single error code/string used by older endpoints.
          type: string
          example: invalid_request
          nullable: true
        code:
          description: >-
            Optional application-level error code (not all endpoints populate
            this).
          type: string
          example: DONOR_NOT_FOUND
          nullable: true
      type: object
    NotFoundResponse:
      title: NotFoundResponse
      description: >-
        Returned with HTTP 404 when a resource lookup misses (typically because
        the id doesn't exist OR is scoped to a different `client_id`). Note:
        many endpoints intentionally collapse 'not found' and 'forbidden' into a
        single 404 to avoid leaking which records exist in another tenant.
      required:
        - message
      properties:
        message:
          description: >-
            Human-readable message. Often a more specific string like `Donor not
            found` or `Trip not found`.
          type: string
          example: Not Found
        status:
          type: string
          example: error
      type: object
    RequestRejection:
      description: >-
        Request or workflow rejection. Framework field-validation failures
        contain errors; semantic rejections may contain message without errors;
        legacy/provider failures may use error and error_code. The operation
        description identifies the rejected condition. Domain responses may add
        current revision, limits or other conflict context.
      anyOf:
        - $ref: '#/components/schemas/ValidationErrorResponse'
        - $ref: '#/components/schemas/ErrorResponse'
        - required:
            - error
          properties:
            error:
              description: Legacy or provider-facing error message.
              type: string
              example: The request could not be completed.
            error_code:
              description: Stable domain error code, when provided.
              type: string
              example: WORKFLOW_UNAVAILABLE
          type: object
    ParticipationNamedIdReference:
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string
      type: object
    ParticipationScheduleReference:
      required:
        - cadence
        - fixed
        - state
        - as_of
        - window_starts_on
        - window_ends_on
        - next_window_starts_on
      properties:
        cadence:
          type: string
          enum:
            - weekly
            - biweekly
            - monthly
            - flexible
        fixed:
          type: boolean
        state:
          type: string
          enum:
            - closed
            - upcoming
            - active
        as_of:
          type: string
          format: date
          example: '2026-10-20'
          nullable: false
        window_starts_on:
          type: string
          format: date
          example: '2026-10-20'
          nullable: false
        window_ends_on:
          type: string
          format: date
          example: '2026-10-20'
          nullable: false
        next_window_starts_on:
          type: string
          format: date
          example: '2026-10-20'
          nullable: true
      type: object
    ParticipationSettingsReference:
      required:
        - enabled
        - terminology
        - default_session_type
        - cadence
        - default_evidence_source
        - allowed_evidence_sources
        - site_field_id
        - cohort_field_id
        - required_intake_field_keys
        - profile_ready_field_keys
        - profile_photo_required
        - unresolved_check_threshold
        - dropout_review_after_days
        - follow_up_due_days
        - follow_up_assignee_user_id
        - revision
      properties:
        enabled:
          type: boolean
        terminology:
          type: string
          enum:
            - school
            - general
        default_session_type:
          type: string
          example: roster_verification
        cadence:
          type: string
          enum:
            - weekly
            - biweekly
            - monthly
            - flexible
        default_evidence_source:
          type: string
          enum:
            - official_record
            - headcount
            - staff_confirmation
            - participant_confirmation
            - legacy_import
            - other
        allowed_evidence_sources:
          type: array
          items:
            type: string
            enum:
              - official_record
              - headcount
              - staff_confirmation
              - participant_confirmation
              - legacy_import
              - other
        site_field_id:
          type: integer
          minimum: 1
          example: 42
          nullable: true
        cohort_field_id:
          type: integer
          minimum: 1
          example: 42
          nullable: true
        required_intake_field_keys:
          type: array
          items:
            type: string
        profile_ready_field_keys:
          description: >-
            Null uses required recipient fields; an explicit empty list requires
            no custom fields.
          type: array
          items:
            type: string
          nullable: true
        profile_photo_required:
          type: boolean
        unresolved_check_threshold:
          type: integer
        dropout_review_after_days:
          type: integer
          nullable: true
        follow_up_due_days:
          type: integer
        follow_up_assignee_user_id:
          type: integer
          minimum: 1
          example: 42
          nullable: true
        revision:
          type: integer
      type: object
    ParticipationPeriodReference:
      required:
        - id
        - name
        - starts_on
        - ends_on
        - status
      properties:
        id:
          type: integer
        name:
          type: string
        starts_on:
          type: string
          format: date
          nullable: true
        ends_on:
          type: string
          format: date
          nullable: true
        status:
          type: string
          enum:
            - draft
            - open
            - closed
      type: object
    ParticipationSessionSummaryReference:
      required:
        - id
        - scheduled_for
        - seen_count
        - expected_count
        - unresolved_count
        - status
      properties:
        id:
          type: integer
        scheduled_for:
          type: string
          format: date
          nullable: true
        seen_count:
          type: integer
        expected_count:
          type: integer
        unresolved_count:
          type: integer
        status:
          type: string
          enum:
            - draft
            - submitted
            - superseded
            - voided
      type: object
    ParticipationScopeReference:
      required:
        - restricted
        - sites
      properties:
        restricted:
          type: boolean
        sites:
          type: array
          items:
            required:
              - site_id
              - all_cohorts
              - cohort_ids
            properties:
              site_id:
                type: integer
              all_cohorts:
                type: boolean
              cohort_ids:
                type: array
                items:
                  type: integer
            type: object
      type: object
    ParticipationRecipientFieldReference:
      required:
        - id
        - key
        - label
        - type
        - options
        - required
        - required_for_intake
        - title
        - option_values
        - placement_source
      properties:
        id:
          type: integer
        key:
          type: string
        label:
          type: string
        type:
          type: string
        options:
          type: string
        required:
          type: boolean
        required_for_intake:
          type: boolean
        title:
          type: boolean
        option_values:
          type: array
          items:
            type: string
        placement_source:
          type: string
          enum:
            - site
            - cohort
            - null
          nullable: true
      type: object
    ParticipationRecipientCreationOptionsReference:
      required:
        - program_type
        - number_sponsors
        - sponsorship_amounts
        - contribution_levels
        - donation_target
        - recipient_portal_enabled
        - tags
      properties:
        program_type:
          type: string
        number_sponsors:
          type: array
          items:
            type: string
        sponsorship_amounts:
          type: array
          items:
            type: string
        contribution_levels:
          type: array
          items:
            type: string
        donation_target:
          $ref: '#/components/schemas/ParticipationJsonValueReference'
        recipient_portal_enabled:
          type: boolean
        tags:
          type: array
          items:
            type: string
      type: object
    ParticipationConfigurationReference:
      required:
        - recipient_fields
        - roles
        - follow_up_assignees
        - access_scopes
        - sites
      properties:
        recipient_fields:
          type: array
          items:
            $ref: '#/components/schemas/ParticipationRecipientFieldReference'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/ParticipationNamedIdReference'
        follow_up_assignees:
          type: array
          items:
            $ref: '#/components/schemas/ParticipationNamedIdReference'
        access_scopes:
          type: array
          items:
            required:
              - group_id
              - site_id
              - cohort_id
            properties:
              group_id:
                type: integer
              site_id:
                type: integer
              cohort_id:
                type: integer
                nullable: true
            type: object
        sites:
          type: array
          items:
            required:
              - id
              - name
              - code
              - site_type
              - status
              - legacy_values
              - cohorts
            properties:
              id:
                type: integer
              name:
                type: string
              code:
                type: string
                nullable: true
              site_type:
                type: string
                enum:
                  - school
                  - center
                  - clinic
                  - community
                  - distribution_point
                  - outreach_area
                  - other
              status:
                type: string
                enum:
                  - active
                  - inactive
              legacy_values:
                type: array
                items:
                  type: string
              cohorts:
                type: array
                items:
                  required:
                    - id
                    - name
                    - code
                    - sort_order
                    - status
                    - legacy_values
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    code:
                      type: string
                      nullable: true
                    sort_order:
                      type: integer
                    status:
                      type: string
                      enum:
                        - active
                        - inactive
                    legacy_values:
                      type: array
                      items:
                        type: string
                  type: object
            type: object
      type: object
    ValidationErrorResponse:
      title: ValidationErrorResponse
      description: >-
        Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The
        `errors` map is keyed by the failing field name; each value is an array
        of human-readable error messages for that field. Most controllers also
        include a top-level `status: error`.
      required:
        - errors
      properties:
        errors:
          description: >-
            Map of field name to array of validator error messages. Example:
            `{email: [The email field is required.], amount: [The amount must be
            a number.]}`.
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        status:
          description: Always the literal string `error`.
          type: string
          example: error
        message:
          description: >-
            Optional summary message — present on some endpoints, absent on
            others.
          type: string
          example: The given data was invalid.
          nullable: true
      type: object
    ParticipationJsonValueReference:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/ParticipationJsonValueReference'
        - type: array
          items:
            $ref: '#/components/schemas/ParticipationJsonValueReference'
        - type: string
          enum:
            - null
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      description: Passport bearer token authentication for legacy admin sessions.
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      description: Gratona API key sent with the compatibility header X-HYS-API-Key.
      name: X-HYS-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.