ArbiterSports FAQs

Please visit us at our new Help Center to access all of our help articles and forums.

Overview

The AcceptAssignments returns information back to the partner who sent it. The information is sent through a push API call to the third party.

In order to receive assignment information, the assignment must meet the following criteria:

The game originated from the third party

The assigning account currently receives game from the third party

The assigning account has selected to return assignment information to the third party that sent the games

The assignment has been accepted

At the time an assignment is accepted, whether by the official or the assigner, a call is made to the third party that sent the game with the assignment details below.

Fields

Authentication

Field

Type

Description

Username

STRING

Username assigned to third party by ArbiterSports (same as used for DataExchange API)

Password

STRING

Password assigned to third party by ArbiterSports

Function

Field

Type

Description

GroupID

INT

Assigning account number within Arbiter. This is the same account number that was provided when the game was sent through the API.

GameID

INT

Account specific game ID. The GroupID and GameID fields form a unique identified for the game.

UniqueGameID

LONG

System generated number that uniquely identifies a game in our system.

OfficialID

INT

Unique ID for the official. The GroupID, GameID, and OfficialID uniquely identify the assignment. This is important for identifying the assignment when UpdateAssignments and RemoveAssignments are called.

OfficialName

STRING

First and last name of the official concatenated together (separated by a space). E.g. "Firstname" + " " + "LastName"

SlotNumber

INT

Row order of the assignment on the game. This is unique for each game. For example, if a game has two officials assigned to it listed as Referee and Umpire, then the SlotNumber for Referee would be 1 and for Umpire would be 2.

PositionName

STRING

Name of the assignment position.

Status

STRING

All statuses are accepted through this call. ArbiterSports only provide assignment information for accepted assignments. If an official is removed then the status would be changed.

StatusDate

STRING

Date that the status was changed (this is

TravelFee

DECIMAL

Total payment amount for travel, perdiem, and any travel categories set up in the account (e.g. luggage, tolls, etc)

GameFee

DECIMAL

Total game fee amount.

RefPayAccount

STRING

ArbiterPay Account number for the official that is associated with this account. Officials can have more than one ArbiterPay account if they associate them to different assigning groups.

OfficialEmail

STRING

Official's signin email address. If the official has more than one email address it lists the primary email address.

OfficialPhone

STRING

First listed public phone number for the official.

Return

ArbiterSports does not require a return value for this call.

WSDL

http://www.arbitersports.com/DataExchangeV3/PartnerExchangeV3.asmx?op=AcceptAssignments

Notes

This is an authenticated web service. ArbiterSports will authenticate against the third party scheduling partner using the same username and password that is used for the DataExchange API.

The Officials REST API allows organizations to retrieve officials data through a REST API. The information is real time but limited to a max of 10,000 records per day. As a REST service, after getting your permissions set up you can access the information through a browser at arbiterrest.arbitersports.com/groups.

Permissions

in order to access information you must be an admin in the account and request access to the API Tech Services at [email protected]. The information available through the API will depend on the permissions set up on the admin account. For example, if an admin account does not have permission to monitor tests, that account won't have access to tests through the REST API.

Available Information

Personal information

Field

Data Type

Description

UserID

INT

Unique identified for the official within ArbiterSports system.

Email

STRING

Primary email address on file. If the official has more than one email address on file, this would be their login email address.

First

STRING

Official's first name

Last

STRING

Officials last name

Middle

STRING

Official's middle name

Address1

STRING

Official's address 1 field

Address2

STRING

Official's address 2 field

City

STRING

Official's city

State

STRING

Official's state

Zip

STRING

Official's postal code

ModifiedDate

DATETIME

Last time the official's information was updated. The information is flagged as updated if the personal information or custom fields for the official are updated. To test if the official has completed a test or registration during that time, you must look up the dates that the registration or test were completed.

BirthDate

DATETIME

Official's birthdate

SSN

STRING

Official's SSN on file (only available if the admin has payroll access). The format of the SSN is XXX-XX-XXXX.

Phones

STRING*

Listing of phones. Can include all phone numbers for the official including the type (e.g. home, work), number, and extension.

GroupID

INT

Account number of the group the official is in.

JoinedDate

DATETIME

Date the official was added into the account

Custom

STRING*

List of custom fields. Includes the ID, name, and value for the official of each custom field.

Registration

Field

Data Type

Description

GroupID

INT

Account number of the registration

RegistrationiD

INT

Unique ID that identifies the registration (e.g. "ACME Baseball 2015-16" = ID 123)

UserID

INT

Official's unique ArbiterSports identifier

Title

STRING

Name of the registration (e.g. "ACME Baseball 2015-16")

Started

DATETIME

Date and time that the official started registration. If the official is not logged in when they start registration, this is set as the time they completed the personal info step.

Completed

DATETIME

Date and time that the official completed the final step of registration

PaymentAmount

DECIMAL

Amount paid for this registration. If the official completed multiple registrations at the same time this is the total of the payments.

PaymentDate

DATETIME

Date and time the payment was made.

PaymentType

STRING

Payment method selected by the official (e.g. Credit Card, eCheck)

OrderNumber

STRING

ProPay order number

AuthCode

STRING

ProPay authcode

Testing

Field

Data Type

Description

TestID

INT

ID of the test that the official completed

GroupID

INT

Account number that the test is in

UserID

INT

Official's unique ArbiterSports identifier

Title

STRING

Name of the test

StartedDate

DATETIME

Date and time the official started taking the test.

CompletedDate

DATETIME

Date and time the official completed the test. If the official has not completed the test this will be blank.

Completed

BOOLEAN

True or false value if the

QuestionsCorrect

INT

Number of questions the official answered correctly (only calculated for completed tests)

QuestionsTotal

INT

Total number of questions officials are required to complete on the test. If a test has a pool of questions that are randomly selected, this will display the number that the official must complete.

Attempts

INT

Number of times the official has completed the test

Eligibility (seasons)

Field

Data Type

Description

GroupID

INT

Account number of the eligibility period

UserID

INT

Official's unique ArbiterSports identifier

SportID

INT

Account specific sport ID.

SeasonID

INT

Unique season/eligibility ID. Each new year eligibility will have a it's own unique SeasonID. E.g. "2015-16 Softball" eligibility = ID 10.

Title

STRING

Name of the eligibility period

StartDate

DATETIME

Open date of the eligibility period. This is the first date (inclusive) that officials with this eligibility period will be eligible.

EndDate

DATETIME

Last date (inclusive) that officials with this eligibility period will be eligible.

Ranks Within ArbiterSports, officials can be assigned a ranking to a sport position. This ranking ranges from 100-999 with 100 being most experienced and 999 being most novice. A ranking indicates that an official works that sport. If the official is not ranked for a sport they cannot work it regardless of eligibility status.

Field

Data Type

Description

GroupID

INT

Account number of the rank

UserID

INT

Official's unique ArbiterSports identifier

PositionID

INT

Account specific ID of the position rank

SportID

INT

Account specific sportID

Title

STRING

Name of the position (e.g. Ref)

Rank

INT

Rank number for the official

Online clinics (More details coming)

Field

Data Type

Description

ClinicID

TestID

GroupID

Location

Date

Certificate

SportsRetrieve the sport information to match up official's ranks

Field

Data Type

Description

SportID

INT

Account specific SportID

GroupID

INT

Account that the sport belongs to

GenericSportID

INT

Unique ID that ties the group specific sport to the ArbiterSports master list of sports. For example, an account may have sports named "Boys Basketball" and another named "Girls Basketball," however, the GenericSportID for both would be 2.

Title

STRING

Account specific name of the sport. For example, an account may name their sport "Rec Soccer."

Generic Sport ID

1

Baseball

2

Basketball

3

Field Hockey

4

Football

5

Hockey

6

Lacrosse

7

Ringette

8

Soccer

9

Softball

10

Swimming

11

Track

12

Volleyball

13

Water Polo

14

Wrestling

15

Squash

16

Tennis

17

Golf

18

Gymnastics

19

Rugby

20

Other

21

Curling

22

Boxing

23

Mixed Martial Arts

24

Cricket

25

Cross Country

26

Bowling

27

Ski

28

Snowboarding

29

Racquetball

30

Competitive Cheerleading

31

Sideline Cheerleading

32

Equestrian

33

Badminton

34

Weightlifting

35

Riflery

36

Archery

37

Rowing

38

Flag football

39

Cross Country Skiing

40

Figure Skating

41

Dance

42

Pom Pon

43

Sailing

44

Surfing

45

Synchronized Swimming

46

Indoor Track

47

Diving

Overview

The AcceptGames sends approved games, by the assigner from the holding table in ArbiterSports, to the partner who sent it. The information is sent through a push API call to the third party.

In order to receive assignment information, the assignment must meet the following criteria:

The game originated from the third party

The assigning account currently receives game from the third party

Assignment is accepted (sent to third party when assignment is accepted)

Assigners have a page that displays all failed API calls, typically from a mismatch in teams, sites, or levels. On this page, assigners can import games that failed when being inserted. When a game previously failed, a negative game number was returned to the partner. Once the assignment is imported, a call to the partner provides the negative game number along with the new game number.

Because the failed game number was initially sent, partners should save that game number and then update it to the positive game number once the game is imported.

Fields

Authentication

Field

Type

Description

Username

STRING

Username assigned to third party by ArbiterSports (same as used for DataExchange API)

Password

STRING

Password assigned to third party by ArbiterSports

Function

Field

Type

Description

GroupID

INT

Assigning account number within Arbiter. This is the same account number that was provided when the game was sent through the API.

GameID

INT

Account specific game ID. Once the game is successfully imported by the assigner, the game ID is assigned and sent back through this call.

UniqueGameID

LONG

System generated number that uniquely identifies a game in our system.

DEGameID

INT

Original negative game ID assigned to the failed game.

OfficialID

INT

Not currently used

Return

ArbiterSports does not require a return value for this call.

WSDL

http://www.arbitersports.com/DataExchangeV3/PartnerExchangeV3.asmx?op=AcceptGames

Notes

This is an authenticated web service. ArbiterSports will authenticate against the third party scheduling partner using the same username and password that is used for the DataExchange API.

Sample code for accessing the Arbiter Officials REST API. Click below for the appropriate sample code.

Overview

This document will walk you through the steps to tests the PartnerExchange API. These steps are to test on our beta site. Once testing is complete, please notify ArbiterSports support that you are ready to make this live and they will transfer the information.

Steps

Email ArbiterSports support ([email protected] and click the submit request at the top of this page) with your end point URL for the API on your site. ArbiterSports will set this up on beta before pushing it to production.

Log in as an admin to our beta website (www.arbitersports-beta.com), and go to Settings >> Preferences and select to send officials data to partners when accepted.

Send new games to that account (you will need to send them through the dataexchange API on beta, which is the same URL as live but with www.arbitersports.com replaced with www.arbitersports-beta.com).

Assign officials to those games. When assigning the officials you can mark them as accepted immediately. Once accepted, the assignment information is sent across. Assign games in published status and continue to the next step.

Accept the game for the official as an admin or if you are an official in the account, you can assign yourself to a game and then accept it as the official. Once accepted, the assignment information is sent across.

Notes

Partners will only receive information if a) the game was sent to Arbiter using the DataExchange API from that partner and b) the account is set up to send officials information to the partner once it's accepted.

From Note 1, in order to use the Partner Exchange API you must have previously implemented the DataExchange API.

Introduction

The Officials API provides a RESTful interface to interact with many of Arbiters website features, including membership, custom fields, registration, testing, and clinic. Both XML and JSON responses are supported for simple integration with almost any programming language. This document provides details for developers on how to integrate with the Officials API.

Entry Points

The Officials API provides two separate entry points:

https :// arbiterrest . arbitersports . com / groups / - This is the production entry point and provides real-time access to your groups information.

https :// arbiterrest . arbitersports - beta . com / groups / - This is the sandbox entry point. Data available through this entry point will not be in sync with your actual Arbiter data, and is meant for development testing purposes.

Limitations

The Officials REST API allows a maximum request of up to 500 officials. If the account you are pulling information from has more than 500 officials, then you will need to query down the results.

Example

https://arbiterrest.arbitersports.com/groups/100000/officials?limit(250,251)

This returns up to 250 officials, beginning with the 251st official in the group (presumably the first 250 have already been retrieved).

Authentication

The Officials API requires a username and password to be provided through HTTP Basic authentication with every request. This username requires API specific rights that must be requested through your Arbiter contact.

Once you have an account with API access, you can begin by sending an HTTP request to the API Entry point listed above. Every request you make must contain an Authenticate header with your credentials encoded according to the HTTP Basic authentication scheme or the service will return a 401 HTTP Status Code with a WWW-Authenticate header. The good news is that the HTTP Basic scheme is easy to implement, and most languages provide built-in support for it. See http :// en . wikipedia . org / wiki / Basic _ access _ authentication for implementation specifics.

Your web browser also supports HTTP Basic, and will prompt for credentials after receiving a 401 response code. This makes it easy to explore the API through your web browser without writing a single line of code.

API Requests

The Officials API works through standard HTTP calls, and thus is compatible with almost any programming language. Any modern programming language should be able to make HTTP calls - consult your favorite languages documentation for specifics.

This also means that you can explore the API through any web browser. You can easily inspect the HTTP headers that your browser sends and receives using a tool like Fiddler, or using the network inspection capabilities of Chromes Developer Tools, Firefoxs Firebug extension, or Internet Explorer 8+s F 12 Developer Tools.

Request URLs

Each resource is identified by a unique URL. A resource can either be a single entity or a collection of entities. Collection resources have paths like /groups/ and do not end with identifiers. Single entity resources have paths like /groups/{id} where {id} is the identifier for a specific entity within that collection.

Collection resources support additional parameters for query control that can be passed through the HTTP requests query string in a format known as Resource Query Language (RQL). RQL defines a standard format allowing for filtering, sorting, and paging of the collection.

Output formats

The Officials API handles multiple output formats. Currently, the API supports XML or JSON output which are both widely supported by most programming languages. Output formats are selected using the Accept HTTP request header or appending accept(format) to the query string for a given resource.

XML will be used as the default format if nothing is specified. A request to .../groups/ will return all groups the current user has access to in an XML format. The JSON representation of this same resource can be specified by appending accept(json) to the URL to yield .../groups/?accept(json).

HTTP Methods

REST APIs expose resources (nouns) using standard HTTP methods (verbs) to denote actions against that resource. Standard CRUD actions are translated as:

GET: Read the resource at the given URL

POST: Create a new resource in the given collection URL

PUT: Update the resource at the given URL

DELETE: Delete the resource at the given URL

For the first phase of this API, only GET requests are supported. Additional HTTP methods will be added in over time.

Collection Paging

All collections support paging using RQLs limit(start,count) querystring parameter. For performance reasons, several collections may require paging. A request for 5000 officials records at once will take an exceptionally long time for the service to collect and send across the network. For large collections it is recommended to request and process the collection in smaller pages.

Examples:

at http :// arbiterrest . arbitersports . com / groups /12345/ officials /? limit (20,20) will contain the first 20 items in the collection. The next 20 items are available at at http :// arbiterrest . arbitersports - beta . com / groups /12345/ officials /? limit (20,20), the next with ?limit(40,20) and so on until an empty collection is returned.

RQL: Resource Query Language

Based on work by Kris Zyp of Sitepen.com. http :// www . sitepen . com / blog /2010/11/02/ resource - query - language - a - query - language - for - the - web - nosql / Only the subset of RQL listed below is supported.

Filtering

Logical Operators

and(query,query,...) | query&query

Filters for objects where all of the given query operators are true.

and(price=19.00,eq(rating,5))

Also has shorthand syntax using standard & querystring syntax:

price=19.00&rating=5

or(query,query,) | (query|query)

Filters for objects where any one of the given operators are true.

or(price=19.00,eq(rating,5))

Also has shorthand syntax using | in place of standard querystring & syntax:

(price=19.00|rating=5)

Relational operators

eq(property,value) | property=value

Filters for objects where the specified property's value is equal to the provided value.

eq(price,19.00)

Also has a shorthand syntax follows that follows normal querystring parameter syntax:

price=19.00

ne(property,value)

Filters for objects where the specified property is not equal to the provided value

ne(rating,0)

gt(property,value) | property>value

Filters for objects where the specified property is greater than the provided value

gt(rating,0)

Also has shorthand syntax using > in place of standard querystring = syntax

rating>0

lt(property,value) | property<value

Filters for objects where the specified property is less than the provided value

lt(rating,3)

Also has shorthand syntax using < in place of standard querystring = syntax

rating<3

ge(property,value) | property>=value

Filters for objects where the specified property is greater than or equal to the provided value

ge(rating,2)

Also has shorthand syntax using >= in place of standard querystring = syntax

rating>=2

le(property,value) | property<=value

Filters for objects where the specified property is less than or equal to the provided value

lt(rating,2)

Also has shorthand syntax using <= in place of standard querystring = syntax

rating<=2

in(property,(value,value,...))

Filters for objects where the specified property's value is in the provided array

in(id,(1,5,6,8,21))

contains(property,(query))

Filters for objects where the specified property is a collection and that collection has items containing the given query.

contains(phones,(type=Mobile))

Sorting

sort([+/-]field)

Sorts the returned query result by the given property. The order of sort is specified by the prefix (+ for ascending, - for descending) to property. To sort by foo in ascending order:

sort(+foo)

One can also do multiple property sorts. To sort by price in ascending order and rating in descending order:

sort(+price,-rating)

Paging

limit(count, offset)

Returns a limited range of records from the result set. The first parameter indicates the number of records to return and the second parameter indicates the starting offset (number of items to skip).

limit(10, 30)

Output Formats

accept(format)

Custom extension to RQL that allows for specifying the desired return content type. This overrides the value provided in the HTTP Accept header, if any.

accept(application/json) or simply accept(json)

Presentation given in the Technical Deep Dive at the NFHS Summer Conference in 2012.