API Integration Quick Start

You can do testing on https://test.runsignup.com.  Here are the generic Getting Started and Overview pages from the site, but here is the general flow:

There are multiple ways to do this depending on your use case:

1.  Partner access – If all your races will be under one partner account, you can use a partner API key and secret.

2.  User Access – If you want users to be able to log in and get their list of races, you’ll need to authenticate by the user:

a.  OAuth 1.0a – If you are familiar with OAuth 1.0a, you can use that to authenticate your users.  Details are here.

b.  Login API – This is a simple method of authenticating users.  Details are here.  You collect the user’s RunSignUp E-mail and password and send it to us in exchange for a temporary key.  This key is valid at most up to 24 hours after the last API request using it, but there’s no guarantee that it will be that long either, so you’ll need to to call this API to get a new key whenever you get an error code of 6.  This API is marked as deprecated because we prefer people not to use it because it means users must give their password to a third party, but we don’t plan on shutting it down any time soon.  Note that you’ll use tmp_key and tmp_secret in your API calls.

– You can get a list of races via this API.  Note that if you authenticate with the API, you will only get races the account has access too.  If you do not, you will get all public races.

– You can get information on a specific race here.  Note that you can get additional information on races when logged in as a director vs not being a director.

– You will use this API.

– event_id can be a CSV of multiple event IDs for the race

– results_per_page cannot be more than 2500

– You can either set page=2, 3, etc. to get further pages OR set the sort field to registration_id ASC and update after_registration_id after each page.  Either way, it’s probably best to set the sort field to registration_id ASC.

– When fetching pages, you can be efficient by only getting the next page if the number of participants you received back from the current call equals results_per_page.

– After the initial download of participants, I’d recommend updating modified_after_timestamp with each future call to only get the updates.  I’d set it to the about 10 seconds in the past to account for possible time differences on the user’s computer.

– If you use JSON, please note that there was a bug in our initial code and it’s still there to not break existing implementations.  The “participants” array on individual events is always empty.  Instead, all event participants are listed together in the top level “participants” field.

– Results are posted to “Result Sets” tied to an event in the race.  An event can have multiple result sets if you want.  You can create the result set via this API.  You can set alternative event IDs if the results span multiple events in RunSignUp.

– If you want to do splits, you can set them up with this API.  You can view existing splits for a result set with this API.

– If you want to post division results (i.e. age group results), you can set them up via the APIs under the “Race Divisions” heading on https://test.runsignup.com/API/Methods.

– You can post division placements via this API or when you are posting the full results.

– You probably want to call this API to disable us from computing division placements and send the placements you calculated.

– If you want to post custom columns, you can set them up via the APIs under the “Results – Custom Fields” heading on https://test.runsignup.com/API/Methods.

– You can use the Post Event Results API to post the results.

– It would be best to set up the result sets and other meta data first.  Then incrementally post the results (vs. clearing the results and re-uploading everything when a change happens).

Most fields that list the date and time as a string are in Eastern Time.  There are a few exceptions, which are noted in the documentation for those API methods. RUnSIgnUp does the conversion from Eastern time to each race’s website display. For example a race in San Jose would show in Pacific time.

For creating a race, you will need to use this API. You will have to contact us to get an API Secret for permission and access. There is information on https://test.runsignup.com/API/ProtectedAPI about using that secret to generate a signature.  It also lets you generate a signature to be sure you have the right one.

Note that to prevent spam, you will receive an error if you try to create more than 10 new races from the same IP in 15 minutes.  That might be an issue on initial imports of a large number of races, but if it is, contact us for a workaround.