openapi: 3.1.0
info:
  title: RunSignup Corrals Participants 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: Participants
  description: Manage race participants including registration, editing, deletion, bib/chip assignment, and participant data retrieval.
paths:
  /race/{race_id}/participants:
    get:
      operationId: getRaceParticipants
      summary: Get Race Participants
      description: Returns a list of registered participants for the specified race. Can be filtered by event, registration status, and other criteria. Includes registration ID, name, contact info, bib, chip, and custom question responses.
      tags:
      - Participants
      parameters:
      - $ref: '#/components/parameters/RaceId'
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - xml
          default: json
      - name: event_id
        in: query
        description: Filter by specific event ID within the race
        schema:
          type: integer
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: results_per_page
        in: query
        schema:
          type: integer
          default: 100
          maximum: 1000
      - name: include_transfers
        in: query
        description: Include transferred registrations (T/F)
        schema:
          type: string
          enum:
          - T
          - F
          default: F
      - name: since_datetime
        in: query
        description: Only return registrations created or modified after this datetime
        schema:
          type: string
      responses:
        '200':
          description: List of race participants
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addOrEditParticipants
      summary: Add or Edit Race Participants
      description: Adds new participants or edits existing participant registrations for a race. Used by timing companies and race management systems to sync registration data.
      tags:
      - Participants
      parameters:
      - $ref: '#/components/parameters/RaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantUpdateRequest'
      responses:
        '200':
          description: Participants added or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantUpdateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /race/{race_id}/delete-participants:
    post:
      operationId: deleteParticipants
      summary: Delete Race Participants
      description: Removes specified participant registrations from a race. Requires race director or admin access.
      tags:
      - Participants
      parameters:
      - $ref: '#/components/parameters/RaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                registration_ids:
                  type: array
                  items:
                    type: integer
                  description: List of registration IDs to delete
      responses:
        '200':
          description: Participants deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /race/{race_id}/get-bib-chip:
    get:
      operationId: getBibChipAssignments
      summary: Get Bib and Chip Assignments
      description: Returns bib number and chip/RFID tag assignments for participants in a race event. Used by timing companies to retrieve tag-to-bib mappings.
      tags:
      - Participants
      parameters:
      - $ref: '#/components/parameters/RaceId'
      - name: event_id
        in: query
        description: The specific event ID to get assignments for
        schema:
          type: integer
      responses:
        '200':
          description: Bib and chip assignment data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BibChipResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ParticipantListResponse:
      type: object
      properties:
        participants:
          type: array
          items:
            type: object
            properties:
              user:
                $ref: '#/components/schemas/Participant'
        total_results:
          type: integer
        num_results:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
        error_msg:
          type: string
          description: Human-readable error message
    ParticipantUpdateResponse:
      type: object
      properties:
        added:
          type: integer
        updated:
          type: integer
        errors:
          type: array
          items:
            type: object
            properties:
              registration_id:
                type: integer
              message:
                type: string
    BibChipResponse:
      type: object
      properties:
        bib_chip_assignments:
          type: array
          items:
            $ref: '#/components/schemas/BibChipAssignment'
    BibChipAssignment:
      type: object
      properties:
        registration_id:
          type: integer
        bib_num:
          type: string
        chip_num:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        event_id:
          type: integer
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        zipcode:
          type: string
        country_code:
          type: string
    Participant:
      type: object
      properties:
        registration_id:
          type: integer
          description: Unique registration identifier
        user_id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        dob:
          type: string
          description: Date of birth (MM/DD/YYYY)
        gender:
          type: string
          enum:
          - M
          - F
          - X
        address:
          $ref: '#/components/schemas/Address'
        bib_num:
          type: string
          description: Assigned bib number
        chip_num:
          type: string
          description: Assigned chip/RFID number
        event_id:
          type: integer
        event_name:
          type: string
        race_id:
          type: integer
        team_id:
          type: integer
        team_name:
          type: string
        registration_date:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
    ParticipantUpdateRequest:
      type: object
      properties:
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid parameters
      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