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

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.