RunSignup · Schema

RunSignup Race

Represents a race or endurance event on the RunSignup platform. A race is the top-level container that holds one or more events (e.g., 5K, 10K, Half Marathon). The race object includes general information, location, registration settings, and links to events.

Race RegistrationEvent ManagementRunningSportsFitnessTimingFundraising

Properties

Name	Type	Description
race_id	integer	Unique race identifier assigned by RunSignup.
name	string	The name of the race.
next_date	string	The date of the next upcoming event in MM/DD/YYYY format.
next_end_date	string	The end date of the next upcoming event in MM/DD/YYYY format.
is_draft_race	string	Whether this race is in draft mode (not published).
is_private_race	string	Whether this race is private (invitation only).
is_registration_open	string	Whether registration is currently open.
created	string	Date the race was created in the system.
last_modified	string	Date the race was last modified.
city	string	City where the race is held.
state	string	US state abbreviation where the race is held.
country_code	string	ISO country code for the race location.
zip	string	Postal code for the race location.
description	string	HTML or plain text description of the race.
url	string	RunSignup registration page URL for the race.
external_race_url	string	External race website URL provided by the race director.
logo_url	string	URL to the race logo image.
charity_id	integer	ID of the charity associated with this race for fundraising.
events	array	List of events within this race (e.g., 5K, 10K, Half Marathon).

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://runsignup.com/schemas/runsignup/race.json",
  "title": "RunSignup Race",
  "description": "Represents a race or endurance event on the RunSignup platform. A race is the top-level container that holds one or more events (e.g., 5K, 10K, Half Marathon). The race object includes general information, location, registration settings, and links to events.",
  "type": "object",
  "required": ["race_id", "name"],
  "properties": {
    "race_id": {
      "type": "integer",
      "description": "Unique race identifier assigned by RunSignup.",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "description": "The name of the race.",
      "minLength": 1
    },
    "next_date": {
      "type": "string",
      "description": "The date of the next upcoming event in MM/DD/YYYY format."
    },
    "next_end_date": {
      "type": "string",
      "description": "The end date of the next upcoming event in MM/DD/YYYY format."
    },
    "is_draft_race": {
      "type": "string",
      "description": "Whether this race is in draft mode (not published).",
      "enum": ["T", "F"]
    },
    "is_private_race": {
      "type": "string",
      "description": "Whether this race is private (invitation only).",
      "enum": ["T", "F"]
    },
    "is_registration_open": {
      "type": "string",
      "description": "Whether registration is currently open.",
      "enum": ["T", "F"]
    },
    "created": {
      "type": "string",
      "description": "Date the race was created in the system."
    },
    "last_modified": {
      "type": "string",
      "description": "Date the race was last modified."
    },
    "city": {
      "type": "string",
      "description": "City where the race is held."
    },
    "state": {
      "type": "string",
      "description": "US state abbreviation where the race is held."
    },
    "country_code": {
      "type": "string",
      "description": "ISO country code for the race location.",
      "pattern": "^[A-Z]{2,3}$"
    },
    "zip": {
      "type": "string",
      "description": "Postal code for the race location."
    },
    "description": {
      "type": "string",
      "description": "HTML or plain text description of the race."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "RunSignup registration page URL for the race."
    },
    "external_race_url": {
      "type": "string",
      "format": "uri",
      "description": "External race website URL provided by the race director."
    },
    "logo_url": {
      "type": "string",
      "format": "uri",
      "description": "URL to the race logo image."
    },
    "charity_id": {
      "type": "integer",
      "description": "ID of the charity associated with this race for fundraising."
    },
    "events": {
      "type": "array",
      "description": "List of events within this race (e.g., 5K, 10K, Half Marathon).",
      "items": {
        "$ref": "#/$defs/Event"
      }
    }
  },
  "$defs": {
    "Event": {
      "type": "object",
      "description": "A specific event distance or category within a race. Participants register for a specific event.",
      "required": ["event_id", "name"],
      "properties": {
        "event_id": {
          "type": "integer",
          "description": "Unique event identifier within the race."
        },
        "name": {
          "type": "string",
          "description": "Event name (e.g., '5K Run', '10K Walk', 'Half Marathon')."
        },
        "start_time": {
          "type": "string",
          "description": "Event start time in the race's local timezone."
        },
        "end_time": {
          "type": "string",
          "description": "Event end time."
        },
        "distance": {
          "type": "number",
          "description": "Event distance value.",
          "minimum": 0
        },
        "distance_unit": {
          "type": "string",
          "description": "Unit for the distance value.",
          "enum": ["K", "M", "Miles"]
        },
        "max_participants": {
          "type": "integer",
          "description": "Maximum number of participants allowed. Null means unlimited.",
          "minimum": 0
        },
        "registration_opens": {
          "type": "string",
          "description": "Date/time when registration opens for this event."
        },
        "registration_closes": {
          "type": "string",
          "description": "Date/time when registration closes for this event."
        },
        "age_min": {
          "type": "integer",
          "description": "Minimum age requirement.",
          "minimum": 0
        },
        "age_max": {
          "type": "integer",
          "description": "Maximum age requirement.",
          "minimum": 0
        }
      }
    },
    "Participant": {
      "type": "object",
      "description": "A registered participant in a race event.",
      "required": ["registration_id"],
      "properties": {
        "registration_id": {
          "type": "integer",
          "description": "Unique registration identifier."
        },
        "user_id": {
          "type": "integer",
          "description": "RunSignup user account ID."
        },
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "dob": {
          "type": "string",
          "description": "Date of birth in MM/DD/YYYY format."
        },
        "gender": {
          "type": "string",
          "enum": ["M", "F", "X"]
        },
        "bib_num": {
          "type": "string",
          "description": "Assigned bib number."
        },
        "chip_num": {
          "type": "string",
          "description": "Assigned RFID chip number."
        },
        "event_id": {
          "type": "integer"
        },
        "event_name": {
          "type": "string"
        },
        "race_id": {
          "type": "integer"
        },
        "registration_date": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "Result": {
      "type": "object",
      "description": "A race result entry for a participant including place and finish time.",
      "required": ["registration_id"],
      "properties": {
        "result_id": {
          "type": "integer"
        },
        "registration_id": {
          "type": "integer",
          "description": "Links this result to the participant's registration."
        },
        "bib_num": {
          "type": "string"
        },
        "clock_time": {
          "type": "string",
          "description": "Gun time from start (HH:MM:SS.ms format)."
        },
        "chip_time": {
          "type": "string",
          "description": "Net chip time from crossing start line (HH:MM:SS.ms format)."
        },
        "place_overall": {
          "type": "integer",
          "description": "Overall finish place across all genders and ages.",
          "minimum": 1
        },
        "place_gender": {
          "type": "integer",
          "description": "Finish place within the participant's gender category.",
          "minimum": 1
        },
        "place_division": {
          "type": "integer",
          "description": "Finish place within the participant's age/gender division.",
          "minimum": 1
        },
        "pace": {
          "type": "string",
          "description": "Pace per mile or kilometer (MM:SS format)."
        }
      }
    }
  }
}