API Access

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.

Timezones

IMPORTANT! All times in the API are in Eastern Time unless otherwise noted.

Datatypes

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. 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:
virtual_race - Virtual Race / Challenge
running_race - Run or Run/Walk
running_only - Run Only
walking_only - Walk Only
race_walk - Race Walk
wheelchair - Wheelchair Race
triathlon - Triathlon
trail_race - Trail Race
bike_race - Bike Race
bike_ride - Bike Ride
mountain_bike_race - Mountain Bike Race
gravel_grinder - Gravel Grinder
duathlon - Duathlon
swim - Swim
expo - Expo
clinic - Clinic
obstacle_course - Obstacle Course
adventure_race - Adventure Race
ultra - Ultra
ski - Ski
aqua_bike - Aquabike
paddle_sports - Paddle Sports
swim_run - SwimRun
other - Other
virtual_race, running_race, running_only, walking_only, race_walk, wheelchair, triathlon, trail_race, bike_race, bike_ride, mountain_bike_race, gravel_grinder, duathlon, swim, expo, clinic, obstacle_course, adventure_race, ultra, ski, aqua_bike, paddle_sports, swim_run, other

Errors

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>

API Reference

The API Reference lists the available resources that can be accessed via the RunSignup API.

Client Libraries and Examples

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/.

Results Posting

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.

One-Time Setup
  1. Go to the API Keys page and register your application. This will give you an OAuth Key and Secret that you will use when connecting to the API on behalf of a race director or timer.
Posting Results
  1. Use the OAuth endpoints listed on the API Keys page and your application's OAuth key and secret to authenticate the user.
  2. Get races for the user to let them select the appropriate race and event. Set the events parameter to "T" so you get the events with each race.
  3. Download participants for the selected event into your timing system. The participants are returned in pages, so you need to get all the pages. You can set results_per_page as you wish, but it may be no larger than 2,500.
  4. Create a result set for the event and store the returned result set id. You should set the name of the result set (e.g. "Live Results", "Official Results", etc.) You can hide the results by setting public_results to "F".
    You can also supply the name and URL of the source for the results. This will be displayed to users who view the results. You might consider using this to link to the timer's website.
  5. Post results by sending the registration id, place, clock time, and (optional) chip time for each runner.
Advanced Features

Once you have this completed, be sure to check out our API Methods for more advanced features:

  • Set up splits (e.g. Mile Markers, Triathlon Splits) and post them in real-time.
  • Set up divisions (e.g. Age Groups, Clydesdale, Athena) and post division results (or let us automatically calculate division results).
  • Add custom fields to the results. You can put any content you want in these fields and runners will be able to view them with the rest of the results.

Authentication

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.

We use cookies to offer you a better browsing experience. Read how we use cookies and how you can control them by visiting our Privacy Policy. If you continue to use this site, you consent to use all cookies.