openapi: 3.1.0
info:
  title: RunSignup Corrals Donations API
  description: The RunSignup REST API provides access to race and event management operations for the RunSignup platform. It enables race directors, timing companies, affiliates, and technology partners to integrate race registration, participant management, results posting, bib and chip assignment, division management, team management, fundraising, volunteer management, and user account management. The API covers 100+ endpoints across 29 categories. Authentication uses OAuth 2.0 (preferred) or permanent API keys for partners and timers. The base URL is https://runsignup.com/Rest and responses are available in JSON or XML format.
  version: '1.0'
  contact:
    name: RunSignup Support
    url: https://runsignup.com/support
  termsOfService: https://runsignup.com/terms
servers:
- url: https://runsignup.com/Rest
  description: RunSignup REST API
security:
- OAuth2: []
- apiKeyAuth: []
tags:
- name: Donations
  description: Retrieve donation and fundraising data associated with race registrations.
paths:
  /race/{race_id}/donations/list:
    get:
      operationId: getRaceDonations
      summary: Get Race Donations
      description: Returns a list of donations made in association with race registrations. Includes donor information, amount, and associated fundraiser.
      tags:
      - Donations
      parameters:
      - $ref: '#/components/parameters/RaceId'
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: results_per_page
        in: query
        schema:
          type: integer
          default: 100
      responses:
        '200':
          description: List of donations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonationsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DonationsResponse:
      type: object
      properties:
        donations:
          type: array
          items:
            $ref: '#/components/schemas/Donation'
        total_results:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
        error_msg:
          type: string
          description: Human-readable error message
    Donation:
      type: object
      properties:
        donation_id:
          type: integer
        user_id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        amount:
          type: number
          format: float
          description: Donation amount in USD
        charity_id:
          type: integer
        fundraiser_id:
          type: integer
        donation_date:
          type: string
          format: date-time
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    RaceId:
      name: race_id
      in: path
      required: true
      description: The unique ID of the race
      schema:
        type: integer
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication (preferred)
      flows:
        authorizationCode:
          authorizationUrl: https://runsignup.com/OAuth/Authorize
          tokenUrl: https://runsignup.com/OAuth/Token
          scopes:
            read: Read access to race and participant data
            write: Write access to race and participant data
    apiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: Permanent API key for affiliates, partners, and timers. Pass api_key and api_secret as query parameters.
externalDocs:
  description: RunSignup API Documentation
  url: https://runsignup.com/API