API Resource: Games

Assignr API - Version 1 Deprecation

This page describes version 1 of the Assignr API, which will be discontinued on May 31, 2022. 

The current version of the Assignr API is version 2. Documentation can be found at our official API documentation site. To obtain access to version 2 of the API, please contact us. 

Data Elements

Notes

• When a new game is created, corresponding records for Teams, Game Types, Venues, Leagues, and Genders will be created as needed.
• For all of the "Find or Create" fields, you may change the ID field, or the name field, but not both.
• The officiating pattern is not a "Find or Create" field. If pattern_name or pattern_id is specified, and it matches an existing pattern, the game will be created. Otherwise, the game will not be created, since the pattern is a required field.
• The is_public and status field are required, however, if they are omitted, they will automatically be set to their respective default values. 

• localized_date and localized_time accept a wide variety of date formats. We use the chronic library to parse the date and time. Many different date formats are acceptable:

  • Date Formats: 3/14, 3/14/2011, 2011-03-14, March 14, "March 14, 2011", Mar 14
  • Time Formats: 3:00 PM, 15:00, 3pm, 3:00pm, 3:00 pm

• To ensure that the date and time are transmitted in an unambiguous manner, we recommend the following date / time format (example shown is March 14, 2011, 1:30pm):

  • Date: 2011-03-14
  • Time: 13:30

Notification Triggers

• A change in published status (is_public) from unpublished to published will send any unsent referee notifications.
• A change in published status (is_public) from published to unpublished will, from a referee’s perspective, remove the game from their schedule. They will be notified that they have been removed from the game.
• Any change in localized_date, localized_time, or venue_id / venue_name will trigger notifications AND will require the referee to re-confirm the game.
• To cancel a game, change the status field from Active ("A") to either Canceled With Pay ("X") or Canceled Without Pay ("C"). This will trigger notifications to all assigned referees.
• A change in an unpublished game will not trigger any notifications.
• A change to a game occurring in the past will also not trigger any notifications.

Validations

• Each game must be unique with respect to date, time, venue, and active/canceled status.
• A referee may not be assigned to more than one position for a given game.
• The user_defined_id field is an alphanumeric field that is visible from within assignr.com. It is an optional field, but if it is provided, it must be unique for the given site.
• The external_id field is a numeric field that you may use for any purpose. If you are linking assignr.com to a game scheduling service, you may use this field to store your corresponding game primary key in this field.
• A change of officiating pattern cannot "bump out" an assigned referee. For example, if a game has a pattern that requires two officials, and both positions are assigned, the pattern cannot be changed to a pattern that only requires one referee.

Retrieve a list of games (INDEX)

Return a paginated list of games. Limit is 50 games per request.

Sample Response: GET /games.json

{
    "page":1,
    "pages":31,
    "count":1524,
    "games":
    [
        {
            "id":26845,
            "start_time":"Sat, 06 Mar 2011 08:00:00 -0500",
            "end_time":"Sat, 06 Mar 2011 08:59:00 -0500",
            "localized_date":"Mar 6 2011",
            "localized_time":"8:00 AM",
            "created_at":"Fri, 12 Feb 2011 11:46:56 -0500",
            "updated_at":"Fri, 12 Feb 2011 11:46:56 -0500",
            "is_public":0,
            "status":"A",
            "home_team_name":"Arizona Rush 94 Swoosh",
            "home_team_id":27249,
            "away_team_name":"TVSC Premier 94",
            "away_team_id":27250,
            "game_type_name":"Youth",
            "game_type_id":15,
            "league_name":"Pima Cup",
            "league_id":227,
            "venue_name":"Port Evangeline Church",
            "venue_id":3575,
            "age_group_name":"U 17 ",
            "age_group_id":2032,
            "gender_name":"Girls",
            "gender_id":228,
            "pattern_name":"5 officials",
            "pattern_id":18,                
            "published_comment": "This is a comment everyone can see",
            "unpublished_comment": "Only assignors will see this comment",                
            "existing_assignments":
            [
                {
                    "id":61167,
                    "lock_version":0,
                    "position_name":"Referee"
                },
                {
                    "id":61168,
                    "lock_version":0,
                    "position_name":"Umpire"
                },
                {
                    "id":61169,
                    "lock_version":0,
                    "position_name":"Head Linesman"
                },
                {
                    "id":61170,
                    "lock_version":0,
                    "position_name":"Line Judge"
                },
                {
                    "id":61171,
                    "lock_version":0,
                    "position_name":"Back Judge"
                }
            ]
        },
        {
            "id":26639,
            "start_time":"Sat, 06 Mar 2011 08:00:00 -0500",
            "end_time":"Sat, 06 Mar 2011 08:59:00 -0500",
            "localized_date":"Mar 6 2011",
            "localized_time":"8:00 AM",
            "created_at":"Fri, 12 Feb 2011 11:46:11 -0500",
            "updated_at":"Tue, 21 Sep 2011 21:28:21 -0400",
            "is_public":0,
            "status":"A",
            "home_team_name":"U10C THUNDERCATS",
            "home_team_id":27122,
            "away_team_name":"Region 1 Wizards",
            "away_team_id":27119,
            "game_type_name":"Youth",
            "game_type_id":15,
            "league_name":"Pima Cup",
            "league_id":227,
            "venue_name":"Port Paxton Church",
            "venue_id":3557,
            "age_group_name":"U 10",
            "age_group_id":2024,
            "gender_name":"Boys",
            "gender_id":229,
            "pattern_name":"5 officials",
            "pattern_id":18,
            "published_comment": "This is a comment everyone can see",
            "unpublished_comment": "Only assignors will see this comment",                
            "existing_assignments":
            [
              {
                  "id":60137,
                  "lock_version":1,
                  "position_name":"Referee",
                  "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                  "name":"Jakubowski, Manuel",
                  "sort_order":1
              },
              {
                  "id":60138,
                  "lock_version":1,
                  "position_name":"Umpire",
                  "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                  "name":"Huels, Rahsaan",
                  "sort_order":2
              },
              {
                  "id":60139,
                  "lock_version":1,
                  "position_name":"Head Linesman",
                  "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                  "name":"Ratke, Micheal",
                  "sort_order":3
              },
              {
                  "id":60140,
                  "lock_version":0,
                  "position_name":"Line Judge",
                  "sort_order":4
              },
              {
                  "id":60141,
                  "lock_version":0,
                  "position_name":"Back Judge",
                  "sort_order":5
              }
            ]
        },
        ... repeats for up to 50 games ...
    ]
}

Sort Order

The default sort order for games is date ascending (past to future), start time ascending (morning to evening), and venue ascending (A-Z). To change the sort order, append one or more "sort" parameters to the request URL. For example, this request will sort the results by date, then by venue, then by start time.

GET /games.json?sort[0]=date&sort[1]=search_venue&sort[2]=start_time

You can append up to ten sort parameters, numbered 0 through 9. The following fields can be specified in your sort parameters:

• date
• start_time
• search_venue
• search_age_group
• search_pattern
• status
• is_public
• search_gender
• search_home_team
• search_away_team
• search_league
• search_game_type
• user_defined_id

By default, the sort order will be ascending. To specify a descending sort order, append a hyphen to the sort parameter. As an example, this will sort by date descending order, then by time.

GET /games.json?sort[0]=-date&sort[2]=start_time

Retrieve a specific game (SHOW)

The following commands will retrieve the game details for a specific game.

Sample Response: GET /games/123.json

{
    "game":
    {
        "id":26639,
        "start_time":"Sat, 06 Mar 2011 08:00:00 -0500",
        "end_time":"Sat, 06 Mar 2011 08:59:00 -0500",
        "localized_date":"Mar 6 2011",
        "localized_time":"8:00 AM",
        "created_at":"Fri, 12 Feb 2011 11:46:11 -0500",
        "updated_at":"Tue, 21 Sep 2011 21:28:21 -0400",
        "is_public":0,
        "status":"A",
        "home_team_name":"U10C THUNDERCATS",
        "home_team_id":27122,
        "away_team_name":"Region 1 Wizards",
        "away_team_id":27119,
        "game_type_name":"Youth",
        "game_type_id":15,
        "league_name":"Pima Cup",
        "league_id":227,
        "venue_name":"Port Paxton Church",
        "venue_id":3557,
        "age_group_name":"U 10",
        "age_group_id":2024,
        "gender_name":"Boys",
        "gender_id":229,
        "pattern_name":"5 officials",
        "pattern_id":18,
        "published_comment": "This is a comment everyone can see",
        "unpublished_comment": "Only assignors will see this comment",                
        "existing_assignments":
        [
            {
                "id":60137,
                "lock_version":1,
                "position_name":"Referee",
                "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                "name":"Jakubowski, Manuel",
                "sort_order":1
            },
            {
                "id":60138,
                "lock_version":1,
                "position_name":"Umpire",
                "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                "name":"Huels, Rahsaan",
                "sort_order":1
            },
            {
                "id":60139,
                "lock_version":1,
                "position_name":"Head Linesman",
                "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                "name":"Ratke, Micheal",
                "sort_order":1
            },
            {
                "id":60140,
                "lock_version":0,
                "position_name":"Line Judge",
                "sort_order":1
            },
            {
                "id":60141,
                "lock_version":0,
                "position_name":"Back Judge",
                "sort_order":1
            }
        ]
    }
}

Create a Game (CREATE)

To create a game, use the POST command to /games.json.

The following status codes can be returned:

• 201 Created: Successfully created a game. The response body will have an XML or JSON representation of the game you created.
• 403 Unprocessable Entity: The game failed one or more validation checks.

Sample Request Body: POST /games.json

{"game":
  {
      "localized_date":"Mar 6 2010",
      "localized_time":"8:00 AM",
      "is_public":0,
      "home_team_name":"U10C THUNDERCATS",
      "away_team_name":"Region 1 Wizards",
      "game_type_name":"Youth",
      "league_name":"Pima Cup",
      "venue_name":"Golf Links West",
      "age_group_name":"U 10",
      "gender_name":"Boys",
      "pattern_name":"3 Referees"
  }
}

Update a Game (UPDATE)

To update a game, send a PUT command to  /games/123.json. The request body should be JSON. If you are only updating a specific field, you can just include the fields you wish to change. For example, if you only want to cancel a game, the request can look like this:

PUT /games/123.json
{"game":{"status":"X"}}

Upon successful update of the record, the response code returned will be 200 (OK).

Sample Request: PUT /games/123.json

The existing_assignments attributes are repeating attributes. existing_assignments only need to be included if you are modifying the assigned referees for a game.

In this example, the first three assignments (60138, 60139, and 60140) are changing the assigned referee. The last two assignments (60140, 60141) are removing any assigned referees.

{
   "game": {
   "localized_date": "Feb 16 2017",
   "localized_time": "6:30 PM",
   "is_public": 1,
   "existing_assignments": [
     {
     "id": 60137,
     "lock_version": 0,
     "user_id": 1992,
     },
      {
      "id": 60138,
      "lock_version": 0,
      "user_id": 1992,
      },
      {
      "id": 60139,
      "lock_version": 0,
      "user_id": 7276,
      },
      {
      "id": 60140,
      "lock_version": 0,
      "user_id": 7287,
      },
      {
      "id": 60141,
      "lock_version": 0,
      "user_id": null,
      }
 ]
 }
}

Delete a Game (DELETE)

To delete a game, issue a DELETE command to the game's URL:

DELETE /games/123.json

The server will respond with a status code 200 (OK) if the game was deleted, otherwise you will see an error response (422 Unprocessable Entity). No response body is rendered.

Validation Errors

If you try to create, update, or delete a game, and the change that you want to make validates one or more assignr.com validation rules, assignr.com will respond with a 422 Unprocessable Entity error. The response body will contain details about the error, like this:

{

"error":[
    { "message": "Venue already has a game scheduled at this day and time" },
    { "message": "Game ID already exists" }
]    

}