Introduction

Before you start your integration read through this documentation

Welcome to our API docs.

This API document is designed for those interested in developing for our platform.

Equipe is the application that enhance your work with equestrian shows - from entries to results with simplicity. This means that in order to save work, we rely heavily on getting the into Equipe so the user don’t have to import it via CSV or manually put it in.

You’ll succeed if you do this.

Here’s some useful information.

Something may not happen if you try and do this.

Something bad will happen if you do this.

Getting Started

Equipe Federation API docs

Looking for the possibility to integrate your federation to the world of Equipe? This will guide you on how to structure your web service to be compliant with https://app.equipe.com. Then you will be able to use the functions of importing entires, enabling search of riders, officials, horses, clubs and later get results when the show is finished.

The Federation API is in reality the documentation for your API, Equipe will upon users request ask your system for information. This describe what we except.

Guide

Recommended steps to make a complete integration

These steps will guide you on how to make seamless integration between your federation and Equipe. The prerequisites is that you already have an entry system where organizers and riders can login to mange entries.

Step 1 - Sign in user

This solves two problems, create the organizer and user in Equipe, and make it single sign on from your federation system. The user then only needs to authenticate once. Read more

Step 2 - Import entries to Equipe

First of all we need to be able to import entries into Equipe. This is done by specifying the Shows URL in the settings for your federation in Equipe.

• User creates a new show in Equipe, and selects File > Federation > Import entries.
• Equipe makes a HTTP GET with headers to the Shows URL it return shows that the logged in user are able to import.
• Equipe will ask the user to select a show to import.
• Equipe will follow the entries_url with headers in the response from shows_url and begin importing entries.

This is a smart import, so the user can run this multiple times to fetch the latest changes. Updates in the show made in Equipe will not be overridden by the import. This is due to our tracking history.

Read more about the entry file format

Step 3 - Create judgement mapping

We have support for over 50+ show jumping judgements. There is a large chance that we already have support for your judgement, but if not, we are happy to add it. When the import runs it will track all judgement_id (this is the judgement identitifer, string value, unique to each discipline) that is not currently mapped to a judgement in Equipe. Go to your federation settings, under Judgements, and fill in the missing details. Some Federations have a loose definition of the rule, so the organizer can decide later on. Mapp it to the most common one.

For disciplines that are using Marking sheets (Dressage, Freestyle, Show jumping competitions for young horses, Eventing), we need the full tests in order for Equipe to function properly. This also allows the user to print the tests from our system with the name of the rider, horse and judge.

You have read-only access to all FEI tests, these can be copied to your federation and translated to your language, and your custom ones needs to be created. We have an editor to create these under your Federation settings.

The large advantage of doing the mapping in Equipe, is that your system never needs to know about any of our internals, we commmunicate with a judgement_identitifer keep it as a string to make the mapping work simpler. These works 2-way, so when we later export the results you will get your identifier back.

Step 4 - Build search webservices

Normally we get all entries before hand. But often there will be changes during the show and at that time your system is closed for new entries.

To make sure you get the correct information back in the results, implement the following web services in your system which allows the user to bring in new people, horses and clubs to the show.

• Search riders
• Search officials
• Search horses
• Search clubs

This way you have the control to only return valid riders and horses, who have paid their licences.

Step 5 - Receive submitted results

When the show is finished, the user will submit results upstream to your system. It can also be done per competition.

• User select File > Federation > Export results
• By default all competitions are selected
• Equipe builds the result json payload and makes a HTTP POST to your system.
• You run your own validation and return 202 Accepted for success or 422 Unprocessable entity with a json response that contains the validation error for failure.
• User gets your feedback

Read more

Step 6 - Translation

We have support for translation of both app.equipe.com and online.equipe.com (Live-result service). The first step is to translate online.equipe.com since this is for riders and audience. When you have users that have run several shows in Equipe, the main app should also be translated. Read more

Conclusion

We know by experiance that it can take some time to get all of the steps above right. But it’s well worth the effort. Equipe is the perfect addition to your entry system. We give extraordinary user experience to run an equestiran show. We have all features necessary to run a show on any level, from the smallest national show to the biggest 5* show.

The web services above is the key, that will give a true seamless experience for the user, to import competitions and entries, run the show and export the results without having to download and upload files manually.

We are ready to assist with your integration and explain in more detail and validate your json responses.

Single Sign On

This is the first step for a complete integration.

Make sure that you have specified your API KEY, enabled Single sign on and copied your unique YOUR-SINGLE-SIGN-ON-URL under settings for your federation in app.equipe.com.

Users of your system needs to login to https://app.equipe.com, you can sign in users that you already have authenticated. This also creates the organizer and user if they do not already exist in Equipe and assigns them to your federation. You should only generate this login possibility to users that have the role of organizer.

HTML Form

Generate a form with the following hidden fields.

Supported locales is sv, en, es, nl, fi, fr and da

Generate auth token

Concatenate the values of organizer_id, organizer_name, name, email, cell_phone and your api key. Make a SHA256 hexdigest of the result. We will use this to verify that your are the sender of the information and that it is untouched. Your federation api_key serves as the shared secret.

Example

federation_api_key = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
organizer_id = 235
organizer_name = 'Helsingborg FRK'
name = 'Kim Fors'
email = 'kim.fors@example.com'
cell_phone = '+4670123123'
locale = 'en'
auth_token = Digest::SHA256.hexdigest([organizer_id, organizer_name, name, email, cell_phone, locale, federation_api_key].join)

The auth_token is f9164f2b22f4627aa14cd411e9af4f2b67953eafb64010347bc05a26269f1305 for the given values above.

Authentication

All outgoing requests form Equipe with include Authentication headers

Make sure that you have specified your API KEY under settings for your federation in app.equipe.com and signed in users with Single Sign On

If the organizer does not have access to a specific end point return 401 Unauthorized.

Shows

List shows that is available for import

Make sure that you have specified Shows URL under settings for your federation in app.equipe.com.

You only need to return current shows. The user will be able to choose a show to import from this list. This url should only return shows for the organizer that is making the request, specified by the X-FEDERATION-ORGANIZER-ID request header.

The response must validate json-schema shows.json

Test this by creating a new show in Equipe, once the show is created go to File > Your federation > Import entries

Entries

A representation of a shows entries for Equipe

The entries_url is given by Shows URL response. Equipe will request the entries for the show the user have chosen to import.

Should return all entries for the show. All resources are represented in the top-level.

The response must validate json-schema entries.json

Does it take long time to collect and build entries response? Return 202 ACCEPTED until the data is ready and can be served. The entries_url will continue to be polled for 10 minutes or until it receive a non 202 ACCEPTED status.

The entries import is designed so that it can be run any number of times before the show starts. First time the user have to select a show, after that when the import is requested by the user it will immediately start the import without prompting to select show again.

Values that have been changed by the user will not be overridden by changes from the entries given by the web service. Entries that are no longer present in the web service response will be withdrawn.

Models

• Show
• Competition
• Person
• Horse
• Club
• Start

Search riders

Allows search and import individual riders to the show

Make sure that you have specified Search riders URL under settings for your federation in app.equipe.com.

Parameters

licence

National rider licence (exact match)

first_name

First name (starts with)

last_name

Last name (starts with)

The response must validate json-schema riders.json

Models

• Rider

Search officials

Allows search and import individual officials to the show

Make sure that you have specified Search officials URL under settings for your federation in app.equipe.com.

Parameters

first_name

First name starts with

last_name

Last name starts with

The response must validate json-schema officials.json

Models

• Official

Search horses

Allows search and import individual horses to the show

Make sure that you have specified Search horses URL under settings for your federation in app.equipe.com.

Parameters

first_name

First name starts with

last_name

Last name starts with

The response must validate json-schema horses.json

Models

• Horse

Search clubs

Allows search and import individual clubs to the show

Make sure that you have specified Search clubs URL under settings for your federation in app.equipe.com.

Parameters

name

Name starts with

The response must validate json-schema clubs.json

Models

• Club

Upload entries

This is a useful option if your federation is not yet ready to commit to our standard format. You can build your own service that converts the entry file given by the entry system.

Make sure that you have specified Upload entry file URL under settings for your federation in app.equipe.com.

• The user upload the entry file to Equipe
• Equipe will in the background make a post with the data untouched to Entry file upload URL, the Content-Type header is set as it was received by the user, the request.body contains the file content.
• You convert the entry file, and return our format for entries, see above Entries
• Equipe import the information, and tracks changes. The user will be able to import the entries serveral times.

Results

Get results from Equipe

We support 3 different ways of exporting results.

• Submit results directly to the federation in our format
• Submit results to an external converter that transform our format to standard of the given federation, the file is downloaded and submitted manually to the federation by the user.
• Download results in our format directly from the system

Submit results

Make sure that you have specified Results URL under settings for your federation in app.equipe.com.

Format

The result format has similar structure as the entries. But instead of entries, we export the starts. See example

{
  "show": {},
  "competitions": [],
  "people": [],
  "horses": [],
  "clubs": [],
  "teams": [],
  "starts": []
}

When the user exports the results, our system will make an HTTP POST with content type of application/json the request body contains the results in json format. If you accept the file, return status 202 Accepted to our system knows that the file is accepted.

In case of your own validation fails, the error needs to be communicated back to the user that tries to send the results.

Return 422 Unprocessable entity with content type application/json and the body should contain the error messages in json format as following

HTTP/1.1 422 Unprocessable entity
Content-Type: application/json
{
 "errors": ["Missing licence of rider XXX"]
}

Submit the results to external converter

Make sure that you have specified Result File URL under settings for your federation in app.equipe.com.

When the user initialize the export, our system will make an HTTP POST with content type of application/json the request body contain the results in json format. You transform the file and return in in the body with the correct content type set. We will then forward this to the user and the file will be downloaded automatically and the user can submit it to the federation.

In case of invalid result data return json response contain the error message with the status code 422 Unprocessable entity as the example above.

Download our result

This option is default if non of the above is specified. It will export the result data in our JSON-format to a file that will be downloaded.

Errors

When something goes wrong

We communicate errors as they occur. Data validation errors will be presented to the user requesting the information. When validation error happens we will show the errors and with the data being validated under the link Show context

If our requests fail we will show the bubble up the error to the user interface.

If something goes wrong internally in our system we will present internal server error.

We hope you get enough information if something goes wrong to be able to track the error.

Show

General settings for the show

Attributes in Bold is required

Competition

Attributes in Bold is required

Person

Attributes in Bold is required

Horse

Attributes in Bold is required

Club

Attributes in Bold is required

Start

Attributes in Bold is required

Payment

Attributes in Bold is required

Custom entry fee

Attributes in Bold is required

Custom field

Attributes in Bold is required

Rider

Attributes in Bold is required

Official

Attributes in Bold is required

Authentication

Add the API key to all requests as a GET parameter or set X-API-KEY header.

Login to your account. Visit you profile page and click show API-Key. This key should be set in the X-API-KEY header or api_key parameter on every request.

You need to be authenticated for all API requests. You can manage your API-Key from your profile. You will be prompted to enter your password to view your key or regenerate it.

Nothing will work unless you include this API key

Marking Sheets

List all marking sheets

Marking Sheets are used for Dressage, Freestyle, Para-dressage, Eventing and more. These sheets are created within app, and mapped to your specified judgement id or rule code.

As you will put a lot of effort creating this sheets we want to make sure that you are able to re-use this information outside app.equipe.com.

This will return all marking sheets, both the FEI and those created specific for your own federation.

curl /federations/YOUR_FEDERATION_ID/marking_sheets.json?api_key=YOUR_APP_KEY

Follow the links to get the marking sheet in pdf or as json with full details.

Marking Sheet

Get Marking Sheet

Returns a specific marking sheet from your collection

curl /federations/YOUR_FEDERATION_ID/marking_sheets.json?api_key=YOUR_APP_KEY

Errors

Commonly used HTTP status codes

Translation

Translation of app.equipe.com

Translation should be done and maintained by a active user of the system.

You will notice that more words will come over and over again. This is because they are used in different parts of the apps. The translation-key is visible in the top-right of the word, it will give you some context where it’s used. Marked with yellow in the screenshot above.

Translation.io saves white space and new line, so be careful when you leave the text box so there is no extra new line (enter) or traling white space.

Try to keep the words in similar length as the original values.

# The translation of these keys must be as short as in English as it's used on on report headers with very limited space.
en:
  reports:
    label_overrides:
      starts:
        st: St.No
        running_number: St.No
        re: Rk
        horse_no: H.No
        tid: Time
        tidd: CC. Time
        rider_country: Nat

es:        
  reports:
    label_overrides:
      starts:
        st: O.S.
        running_number: O.S.
        re: Cl
        horse_no: NºC.
        tid: Tiempo
        tidd: CC. Tiempo
        rider_country: Nac
sv:
  reports:
    label_overrides:
      starts:
        st: St.Nr
        running_number: St.Nr
        re: Pl
        horse_no: H.Nr
        tid: Tid
        tidd: Uth. Tid
        rider_country: Nat

# The translation of these keys must be as short as in English as it's used on the scoreboards with very limited space.
en:
  scoreboard:
    components:
      participants: Total
      remaining: Left
      end_time: Finish
      rank: Rank

Important to get it right

This is importent values to translate correctly.

en:
  meetings:
    navbar:                     # Look at other windows or mac software, these words is often used in menu items. Keep the same that is normally used in your language.
      file: File
      edit: Edit
      go_to: Go to
      tools: Tools
      actions: Actions
      economy: Economy      

en:
  activerecord:
    values:
      start:
        status:
          Ö: Withdrawn            # Withdrawn (configured under show settings, if they have to pay or not)
          ö: Withdrawn by judge   # Withdrawn
          E: Unpaid withdrawn     # Like withdrawn but communicate that the reason is because missing payment
          U: No-show              # Like withdrawn but possibility to add penatly fee (configured under show settings)
          u: No-show by judge     # Same as above but done from the judge tower
          B: Changed competition  # Like withdrawn, but the payer will not be charged for this start
          R: Reserve              # Will not be in the start lists, moved to a queue
          S: Starting notified    # Have told the show office that they are going to start, not used often
        status_short:             # See status above
          Ö: Withdrawn
          ö: withdrawn
          E: Unpaid
          U: No-show
          u: no-show
          B: Changed
          R: Reserve
          S: Starting
        or:                       # See reason below
          A: Abst.
          U: Ret.
          D: Eli.
          S: DQ
        reason:                    # All of these is a result, they will be calculated as starting
          A: Abstained             # This is the easiest to get wrong, Abstained is only used if the start is qualified for jump off, but does not want to participate, this is a result like eliminated or retired.
          U: Retired
          D: Eliminated           
          S: Disqualified          # Often done afterwards, when the competition is finished. Judges take this decision.

What is it?

• TDB - System for the Swedish federation, should not be translated to something else, this is not visible outside Sweden.
• Swish - Electronic payment person to person. If something similar exist it can be translated

Contact

Contact us if you are want to translate app.equipe.com to your language. You should know our system well before you start making the translation.