ArbiterSports API

Overview

The ArbiterSports Partner API allows organizations to access schedule, assignment, and official data for their accounts.   The API supports standard RESTful endpoints.

URLs

Production: https://partner.arbitersports.com/index.html

Beta:  https://partners.arbitersports-beta.com/index.html
Our beta environment is configured identical to production.  The data is usually within 6 months old.  For testing Users calls, some of the data has been scrubbed and won’t reflect the full dataset. 

Access

Access is limited in two manners.  First, each endpoint has a specified scope to utilize it.  Partners have scopes enabled based on the purpose of the integration.  Second, each partner is given access to specific accounts (officiating groups, state offices, or schools) without the system.  If an account is not enabled, requests to get or update data within that account will be rejected.

If you do not have credentials, please contact [e-mail].

Tokens

Each call requires a bearer token to be provided. To get a bearer token, follow these steps:

1. Open the Postman app
2. In the POST, enter URL for the environment you're trying to access (beta - https://token.arbitersports-beta.com/connect/token or prod - https://token.arbitersports.com/connect/token)
3. Enter in the Body the credentials from the Arbiterapi Initiative.xls
   • Client ID
   • Client Secret
   • Scope
4. Click Send. The Bearer Token will be generated. Copy the access_token.
5. Go to the partners api URL
6. Click on the green ‘Authorize’ button
7. In the Value box, enter 'Bearer (access_token)'
8. Click Authorize

Scope

Each of the endpoints is governed by a specific scope.  There are three scopes: Scheduling, Registration, and Eligibility. 

Limits

Arbiter will set up the organizations that you have access to through the API.  While Scope indicates which endpoints are available, limits manage what data is available in those endpoints. 

Using Swagger

Depending on the Scope that was selected with the bearer token, you'll be able to use certain sections to pull information from.

1. Click on the section you scoped for
2. Select the type of data you're wanting to get
3. Enter the parameters for the section
4. Click on Execute

Below, you'll see the raw data that the API was able to pull if successful! If you're not seeing data, it could mean that we didn't specify which scope to have access to, or the partner is limited or does not have access.

Schedules

Overview

The Schedules endpoints allow partners to pull game and event data for Arbiter accounts they have access to.

Scope

All calls in this section require the “Scheduling” scope.

Getting Game Data

Endpoints

GetGames: Retrieves all games based on the input filter that has been given

• UniqueGameID – Unique identifier for the game.  This is used for tracking a game across multiple data pulls.
• GameNumber – The account specific ID for the game.  Users have the ability to set these themselves.  Useful if the users want to see a consistent GameID throughout all of their systems.
• GroupID – Account number of the assigning association responsible for getting officials to the game

Game Changes

When a game is changed in Arbiter, it goes through a process to get approval from assigners and opponents before the game is fully updated.  This allows all parties to ensure that the change will work for them (assigners getting officials, away teams getting busses, etc).  Our API allows you to pull games based on the previously agreed to information or the pending game information.

In the GetGames and GetGamesByUniqueGameIDs calls, there is a parameter to includePendingInformation.  If that is set to true, we will send you games with the pending change.  If false, we will send game data using the previously agreed to information.  By default (if the parameter is not provided), this is set to false.

Deleted Games

When a game is deleted by a school or assigner within Arbiter, there are three possible outcomes based on specific business rules. 

1. Game is accepted by multiple parties (another school or assigner)
   1. If the assigner deletes the game, the game is flagged as deleted.  The game will still be available in the API but marked as flag deleted.
   2. If a school deletes the game, they are removed from the game and are replaced by a TBA team placeholder.  In this case, if you don’t have access to the game through the remaining school on the game, it will not be returned through the GetGames endpoint.
2. Game has not been accepted by other parties
   1. The game is permanently deleted.

You will need to use three endpoints to account for each of the situations above.

1. Game is Flag Deleted in the system
   1. Use the IncludeDeletedGames in the GetGames endpoint.  The next time you get games that have been modified (which includes being flag deleted), the game will be included in the dataset.
2. Game was deleted by a school and you don’t have access to it any longer
   1. Use the GetGameTeamHistory call with a ModifiedSince parameter based on the last time you synced with Arbiter.  This call will return changes to teams, including the change to TBA, that allows you to see that a game you previously had access to is no longer accessible.
3. The game was permanently deleted
   1. Use the DeletedGames endpoint to get the game IDs of all games that were deleted within the dates provided. 

Users

Overview

The users section allows partners to get officials information and to save user information to their account.  Due to the sensitive nature of the data, this is only offered for partners who own the account.

Scope

All endpoints in the Users section require the Registration scope.

Endpoints

SaveOfficial

This is the main endpoint for creating or updating an official.  The endpoint behaves as both a post and put.  When an official is sent through the API, the API will attempt to find a match using the official's user ID first. If a match is not found using the email address, the email address field is used.

Field		Data Type		Definition
registerusers	NA		Root node
FirstName	string		Official's first name
LastName	string		Official's last name
Email	string		Email address for the official
Address1	string		Address 1 for the official.  Can include suite or apt number if address 2 field is not used.
Address2	string		The suite, apartment, or additional address information for the official
City	string		Name of city
State	string		Two character state abbreviation
Zip	string		Postal code for the official.  Supports US five or nine digit postal codes or Canadian six character postal codes (for Canadian postal codes, include the space separating the first three and last three characters).
DOB	date		Official's date of birth
SSN	string		Nine digit Social Security Number.  Can include dashes or only numbers
ArbiterUserID	INT		Used for updates.  For all RegisterUsers calls, this field should be left blank.
Password	string		Initial password for new uploads.  If the official is already in the system, the password field will be ignored.
Groups	INT		If the official will be added to more than one account (state account and local chapter), then more than one groupID would be provided.  The stateID included in this field is to be used for tracking the state's assigned ID number for the official.
PermissionSet	string		Name of the permission set the official should be assigned.  If no permission set is provided, the default permission set for the account will be applied to the official.
Phones	string		Contains a list of phone numbers. Use the web method GetPhoneTypes to assign the phone typeid attribute.  The phone number field allows for alphanumeric characters and will display as added (dashes, extensions, etc)
Ranks	INT		Ranks are used to indicate an official's competency in a sport.  Range from 100-999, with 100 being best.  Each rank has a position id and the numerical rank they are to be given for that position. Use the GetPositionNames function to get the proper position ID’s for a sport.
Seasons	INT		Seasons indicate the eligibility for an official.  In ArbiterSports, each season represents eligibility for a sport during a specific time period.  User the GetSportSeasons function to retrieve the season IDs for each sport.

Custom Fields

To get the custom fields for one of the groups you have access to, use the getGroupCustomFields endpoint.  This will return the name, ID, datatype, and any options (if the group has limited what can be selected by an official) available for that custom field.

To update custom fields for specific officials, use the CustomField Post endpoint.  The endpoint can be used to provide an array of officials and an array of custom fields for each of those officials.  However, if you have access to multiple groups, you can only give custom fields for one group at a time.

Eligibility

Endpoints

/api/Eligibility/GetGroupEligibilities

Get the eligibility names and IDs within the specified Arbiter account for use in mapping current eligibility to officials in your system or to send those eligibility requirements to Arbiter.

/api/Eligibility/GrantEligibility

Mark an official has having an eligibility tier.  This only gives the official eligibility for that specific tier, not the lower level tiers.  E.g. if you mark an official as being eligible for varsity football, it will not mark them as sub-varsity eligible.

/api/Eligibility/RemoveEligibility

Remove the eligibility for an official.  Officials will remain on games that they have been assigned even if the eligibility has been removed, however, they official will show an icon as ineligible for any games that were covered by this eligibility.

/api/Official/Eligibility

Get the eligibility information for officials within your account.  This allows you to pull eligibility information for specific officials, those who have completed specific eligibilities, or those that have completed an eligibility since a specific date.  We recommend syncing eligibility information and then using the eligibilityGrantedDate to remain in sync.

Response Codes

• 200 – Successful request.
• 400 or 403 – Unauthorized access.  This can result from having an expired/invalid token or attempting to access information that hasn’t been turned on for the account.
• 404 – Function does not exist OR a GET call didn’t find any data matching the requested filters.
• 500 - Code: Unhandled exception.  Please report to [e-mail].