Easy Reg API Documentation

Please note, as of January 2023, the XML format has been deprecated and will be phased out by 2024. All new development and enhancements will only be done for the JSON format. It is recommended that you use the JSON format for any future API implementation.

Authentication

In order to make any requests to the API, you'll need to supply your API key (api_key) as a query string parameter. For example:

  https://www.easyreg.co.za/apiv1/events.json?api_key=123

Please Note: From here on out, for the sake of brevity, we won't include the authentication parameters in the examples. But please make sure you include them when using the API.

How to view data for a specific event

You'll want to follow these steps:

Get the list of events that your user account has access to. See the Events section.
Get the list of registration types belonging to your selected event. See the Registration Types section.
Get the list of registrations belonging to your selected registration type. See the Registrations section.

Alternatively, if you hit the Registrations directly, you'll be returned all registrations belonging to events to which your user account is assigned.

Format of results (JSON or XML)

The services below support both JSON and XML. Simply adjust your request based on your desired format. For example:

  GET: https://www.easyreg.co.za/apiv1/events.json

or...

  GET: https://www.easyreg.co.za/apiv1/events.xml

For the sake of simplicity we'll default to json in the examples below.

Events

Get a list of events that your user account has access to:

  GET: https://www.easyreg.co.za/apiv1/events.json

Registration Types

Specify the ID of the event you're interested in. To get all registration types for a specific event:

  GET: https://www.easyreg.co.za/apiv1/events/{event_id}/registration_types.json

Parameters:

event_id - (optional) The ID of the event in question. If not supplied, all events assigned to user are assumed.

Courier Addresses

Specify the ID of the event you're interested in, to get the courier address for all paid registrations for a specific event:

  GET: https://www.easyreg.co.za/apiv1/courier_addresses.json

Parameters:

event_id - The ID of the event in question.

Registrations List

You can hit the registrations directly, like so:

  GET: https://www.easyreg.co.za/apiv1/registrations.json

This will return all registrations assigned to events that the API user has access to.

The result of this API call is a paginated result set, here are the parameters:

Parameters:

event_id - (optional) The ID of the event in question. If not supplied, all events assigned to user are assumed.
registration_type_id - (optional) The ID of the registration type in question. If not supplied, all registration types belonging to the event_id supplied or event_ids assumed.
page - (optional) The current page, defaults to 1.
per_page - (optional) The amount of results per page, defaults to 50, maximum value of 200.
last_modified_at - (optional) Returns registrations that have been created / updated since this date/time value. Format example: '2019-04-26 10:58:21 UTC'. Date/time values are stored internally as UTC, and is thus the default timezone.
custom_fields - (optional) Can be 'true' or 'false'. Whether to include custom question and answers, defaults to 'false'. If specified, results will be sorted in ascending order by 'last_modified_at'.
csa_fields - (optional) Can be 'true' or 'false'. Whether to include Cycling South Africa (CSA) specific fields for the registrant, defaults to 'false'. If specified, results will be sorted in ascending order by 'last_modified_at'.
product_fields - (optional) Can be 'true' or 'false'. Whether to include merchandise and/or donations, defaults to 'false'. If specified, results will be sorted in ascending order by 'last_modified_at'.
team_members_within_registration - (optional) Can be 'true' or 'false', defaults to 'false'. Whether to include team members as a nested attribute of the registration, instead of returning them individually.
has_bib_number - (optional) Can be 'true' or 'false', defaults to 'false'. Whether to limit results to only those registrations which have a bib number assigned.

Alternatively, you can specify the ID of both the event and the registration type as part of the URL, like so:

  GET: https://www.easyreg.co.za/apiv1/events/{event_id}/registration_types/{registration_type_id}/registrations.json

The result of this API call is the same as above, with the exception that it is filtered by event_id and/or registration_type_id.

A Note About Custom Fields

Custom fields contain non-standard fields (fields may differ depending on the event requirements). Custom fields normally hold data such as:

Medical details
Emergency contact information
Shirt size
Other event-specific requirements

A Note About Cycling South Africa (CSA) Fields

CSA fields contain information specific to the CSA registrant. The fields will only be populated if the registration requires a CSA license and the registrant is a member on the CSA member's portal.
CSA fields normally hold data such as:

member_csa_id, membership_status, racing_license_status, day_license_status, uci_code, country, region, city, affiliate and club

A Note About Pagination

All result sets include information about the paginated result set. The following paging information is present in the root node of the result set:

page - The current page.
per_page - The amount of results per page.
total_entries - The total amount of results for the entire data set.

Registration Details

Once you have obtained the ID of a registration (using the registration's id field from the list above), you can hit the end-point like so:

  GET: https://www.easyreg.co.za/apiv1/registrations/{id}.json

Parameters:

id - The ID of the registration in question.

The resulting JSON structure matches the one returned in the list view, with the exception a new custom_fields array of fields, representing the custom questions that an event organizer can ask of a registrant.

Registration Statuses

Overview

The registration system uses various statuses to track the state of a registration throughout its lifecycle. These statuses are grouped into different categories based on their payment and processing state.

Registration Status Categories

Draft and Initial States

draft - Initial state when a registration is first created but not yet submitted

Unpaid States (Awaiting Payment)

to_pay_via_credit_card - Registration pending payment via credit card
to_pay_via_eft - Registration pending payment via Electronic Funds Transfer

Paid States

payment_complete_eft - Payment successfully completed via Electronic Funds Transfer
payment_complete_credit_card - Payment successfully completed via credit card
payment_complete_snapscan - Payment successfully completed via SnapScan
payment_complete_cashier_cash - Payment successfully completed at cashier with cash
payment_complete_cashier_credit_card - Payment successfully completed at cashier with credit card
payment_complete_no_cost - Registration completed at no cost
free_entry - Registration complete and marked as free

Special Payment States

partially_paid - Registration where partial payment has been received
deferred_to - Registration that has been deferred to from another registration
payment_complete_race_organiser - Payment marked as complete. However the money was taken directly by race organiser and not paid via Easy Reg.

Cancelled/Modified States

withdrawn - Registration has been withdrawn
refunded_via_voucher - Registration has been refunded with a voucher
stale - Registration has become inactive due to lack of activity
transferred - Registration has been transferred to another person
deferred_away - Registration has been deferred to a different event/date
forfeited - Registration has been forfeited

Last, but not least...

Don't forget to attach your authentication details as query string parameters!