API calls require api_key and api_secret parameters in the URL. Be sure to include "https" in front of all API calls to keep your API credentials secure.
IMPORTANT! All times in the API are in Eastern Time unless otherwise noted.
All fields will have an associated datatype. Below are the field types used in the API.
| Data Type | Description | Valid Values |
|---|---|---|
string |
Character string. | |
password |
A password string. | |
int |
Signed integer. | |
uint |
Unsigned integer. | |
float |
Floating point number. | |
bool |
Boolean value. | T, F |
id_list |
Comma separated list of integer IDs. | |
string_list |
Comma separated list of integer strings. | |
format |
Response or request format. You can submit GRU files from RunScore and The Race Director by specifying CSV. Not all methods support each format. The preferred type is `json`. | xml, json, csv |
date |
Date formatted as "YYYY-mm-dd", a timestamp, or one of the strings "today" and "tomorrow". | |
time |
24-hr time formatted as "hh:mm:ss". | |
unix_timestamp |
Unix timestamp. | |
datetime |
Date and time formatted as "YYYY-mm-dd hh:mm:ss" where time is in 24-hour format. | |
gender |
Gender as either "M" or "F". | M, F |
phone |
Phone number formatted as "xxx-xxx-xxxx". | |
state |
Two letter state or province abbreviation. | |
country |
Two letter ISO 3166-1 alpha-2 country code. | US, AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW |
distance_units |
Units for distance: K: km, M: miles, y: yards, and m: meters. | K, M, y, m |
event_type |
Event type: running_race - Run or Run/Walk virtual_race - Virtual Race / Challenge nonprofit_event - Nonprofit Event running_only - Run Only walking_only - Walk Only race_walk - Race Walk wheelchair - Wheelchair Race triathlon - Triathlon duathlon - Duathlon bike_race - Bike Race bike_ride - Bike Ride mountain_bike_race - Mountain Bike Race gravel_grinder - Gravel Grinder fundraising_ride - Fundraising Ride trail_race - Trail Race open_course_trail - Open Course Trail ultra - Ultra hike - Hike obstacle_course - Obstacle Course adventure_race - Adventure Race swim - Swim swim_run - SwimRun aqua_bike - Aquabike ski - Ski paddle_sports - Paddle Sports disc_golf - Disc Golf clinic - Clinic expo - Expo skate - Skating ruck - Ruck other - Other |
running_race, virtual_race, nonprofit_event, running_only, walking_only, race_walk, wheelchair, triathlon, duathlon, bike_race, bike_ride, mountain_bike_race, gravel_grinder, fundraising_ride, trail_race, open_course_trail, ultra, hike, obstacle_course, adventure_race, swim, swim_run, aqua_bike, ski, paddle_sports, disc_golf, clinic, expo, skate, ruck, other |
If there is an issue with your request, you may get responses such as below.
List of Error Codes<error> <error_code>6</error_code> <error_msg>Key authentication failed</error_msg> </error>
<error>
<error_code>3</error_code>
<error_msg>Invalid parameters</error_msg>
<param_missing>
<param_name>api_key</param_name>
</param_missing>
<param_missing>
<param_name>api_secret</param_name>
</param_missing>
</error>
Each RunSignup API is accompanied by an OpenAPI 3.0 specification that describes all available endpoints, request/response schemas, and authentication requirements.
Access OpenAPI Resources:
For more information about OpenAPI, visit the Swagger Documentation or the OpenAPI Specification Repository.
The RunSignup OpenAPI specification includes several custom extensions to provide enhanced functionality and better integration with our platform. These extensions offer rich metadata for improved tooling support, including enhanced code generation capabilities and AI-assisted development workflows.
| Extension | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
x-permissions |
Documents access control requirements for each endpoint, specifying which user types can access the resource.
Used throughout the API to indicate whether endpoints require race director privileges, timer access, or are available to all users. Example: {"x-permissions": ["race_directors", "timers"]}
|
||||||||
x-response-field-inclusion |
If a response parameter has this extension added, it means that parameter will only be included in the response when the GET parameters specified are set to the indicated value.
The requires property can specify additional parameters that must also be present for the field to be included.
Commonly used to conditionally include detailed information, custom fields, or additional metadata based on request parameters.Example: {"x-response-field-inclusion": [{"request-parameter": "include_details", "value": "T", "requires": ["user_id"]}]}
|
||||||||
x-currency-symbol |
Provides the currency symbol to use.
This is often used with x-decimal-places, x-min-value, and x-max-value extensions (see example) to provide comprehensive currency formatting metadata including symbol, decimal places, and validation constraints.
Used extensively in pricing-related APIs to ensure proper currency display and validation across different regions and currencies.Example: {"x-currency-symbol": "$", "x-decimal-places": 2, "x-min-value": 0, "x-max-value": 999999.99}Related Currency Extensions:
|
||||||||
x-address-fields |
Documents address field mappings and validation rules for structured address data.
Used to provide clear mapping between display labels and address field names.
In the example below, the street address will be in the address_line_1 field.Example: {"x-address-fields": {"street": "address_line_1", "city": "city", "state": "state", "zipcode": "zip_code"}}
|
||||||||
x-key-info |
Documents dynamic key object structures with type and pattern information.
Used in APIs where response objects have dynamic keys (like event IDs, division IDs, or time-based identifiers) that follow specific patterns and contain structured data.
In the example below, the keys of the JSON object will be the event ID. Example: {"x-key-info": {"type": "integer", "description": "Race event ID"}}
|
||||||||
x-pattern-properties |
Documents pattern-based property validation using regular expressions.
Unlike x-key-info which documents the structure of dynamic object keys, x-pattern-properties defines validation rules for properties whose names follow specific patterns (like split times, custom field values, or category-specific data).
This extension is used when you have multiple properties with similar naming patterns rather than a single dynamic key structure.
In the example below, any property matching the pattern "split-" followed by digits and "-place" will be validated as a string type.Example: {"x-pattern-properties": {"split-\\d+-place": {"type": "string"}}}
|
||||||||
x-key-naming-convention |
Documents key naming conventions for consistent code generation.
Used in complex response objects to explain the structure and meaning of dynamic JSON keys, particularly in endpoints where object keys represent specific business logic or data relationships.
In the example below, the JSON keys will be division IDs (integers) and their values will be finisher counts (integers). Example: {"x-key-naming-convention": "Properties are division IDs (integers) mapping to finisher counts (integers)"}
|
The API Reference lists the available resources that can be accessed via the RunSignup API.
For a quick start, download our PHP client library. Also, take a look at our API examples at https://github.com/RunSignUp-Team/OpenSource/tree/master/RunSignUpApiExamples. An example application of the API for race timing is described in https://runsignup.wordpress.com/2012/08/13/mobile-cloud-timer-app/.
This section describes the general process for using the API to post race results. There are variations you can make to this process depending on your needs. For example, you may use the API keys for a partner instead of authenticating a user with OAuth. This example assumes that you will download the registration id for each participant and map finishers to their registration id.
Once you have this completed, be sure to check out our API Methods for more advanced features:
RunSignup users can be authenticated by your application or website using OAuth and the RunSignup API. The RunSignup OAuth Integration Guide describes how to do this.
