
# Overview

This document describes the resources that make up the TeamSnap API.

## Getting Started

<div id='location' class="Anchor--hack"></div>

### Location

All API access is over HTTPS, and available via [`https://api.teamsnap.com/v3/`](https://api.teamsnap.com/v3/).
It is highly recommended that you enforce certificate validation to ensure the security of your services and your users.

<div id='schema' class="Anchor--hack"></div>

### Schema

TeamSnap's API is a [Collection+JSON](http://amundsen.com/media-types/collection/) API. This differs from your normal RESTful style JSON API in a few very important ways:

1. The client should not construct any URIs.
1. Caching of URIs is permitted; however, if an error is encountered, this cache should be cleared.
1. Every JSON object returned will be a collection.

More information on how Collection+JSON works and how it applies to this API is available on the Collection+JSON page of this documentation.

<div id='response-codes' class="Anchor--hack"></div>

#### Response Codes

The most common response codes will be in the `200` and `400` ranges.

Successful Calls:

- `200 OK` Call completed successfully.
- `201 CREATED` Object created successfully.
- `204 NO RESPONSE` Call completed, no response required.

Unsuccessful Calls:

- `401 UNAUTHORIZED` You are not authorized to access this resource. Try re-authorizing.
- `404 NOT FOUND` This resource does not exist, or you may be unauthorized. Try re-authorizing; if that fails, clear your URI cache.
- `411 Length Required` You need to add a Content Length header to your request.
- `429 TOO MANY REQUESTS` You have reached your rate limit.
- `500` Server took a brief vacation.

<div id='date-an-time' class="Anchor--hack"></div>

#### Date and Time

All dates and times (including timestamps) are in [ISO 8601 Format](https://en.wikipedia.org/wiki/ISO_8601).

<div id='null-data' class="Anchor--hack"></div>

#### Null Data

Blank fields are sent as `null` instead of being omitted from responses.

<div id='versioning' class="Anchor--hack"></div>

#### Versioning

The TeamSnap API versioning scheme adheres to the guidelines set out in [SemVer 2.0.0](http://semver.org/spec/v2.0.0.html). The version of the API is available in each request under the `version` field. Version is global across the API, resources are not versioned individually.

<div id='constructing-a-request' class="Anchor--hack"></div>

### Constructing a Request

To construct a request, you will need to obtain an authorization token.


Location

Response Codes

Date and Time

Null Data

Versioning

Constructing a Request

Schema

Getting Started


# API Objects

The TeamSnap API has a large number of objects and concepts that may be unfamiliar. This document describes these objects and some of their roles.

<div id='users' class="Anchor--hack"></div>

## Users

There is only one user related object - the user!

<div id='me' class="Anchor--hack"></div>

### me

The `me` `rel` will direct you to the current user's object. It is not possible to create or delete users via the API; however, it is possible to update data on a user's record.

`rel`s that point to `user` objects are:

- `me` - this `rel` always points to the current user
- `users`

<div id='teams-1' class="Anchor--hack"></div>

## Teams

<div id='teams_2' class="Anchor--hack"></div>

### teams

The `teams` `rel` will direct you to associated teams from your origin object. Full CRUD is possible with the teams endpoint.

<div id='teams_preferences' class="Anchor--hack"></div>

### teams_preferences

The `teams_preferences` `rel` will direct you to the team preferences for a specific team.

<div id='custom_fields' class="Anchor--hack"></div>

### custom_fields

<div id='tracked_items' class="Anchor--hack"></div>

### tracked_items

<div id='tracked_item_statuses' class="Anchor--hack"></div>

### tracked_item_statuses

<div id='members_1' class="Anchor--hack"></div>

## Members

A `member` (also referred to as a `roster` in our web and mobile apps) is a member of a team.

<div id='members_2' class="Anchor--hack"></div>

### members

The `members` `rel` provides a list of members associated with the origin object.

<div id='member_email_addresses' class="Anchor--hack"></div>

### member_email_addresses

The `member_email_addresses` `rel` provides a list of email addresses associated with the `member` record.

<div id='member_phone_numbers' class="Anchor--hack"></div>

### member_phone_numbers

The `member_phone_numbers` `rel` provides a list of phone numbers associated with the `member` record.

<div id='member_links' class="Anchor--hack"></div>

### member_links

<div id='member_preferences' class="Anchor--hack"></div>

### member_preferences

<div id='contacts_1' class="Anchor--hack"></div>

## Contacts

A `contact` is an associated object to a member; and represents a person who should be a designated contact for the member (i.e. parents, grandparents, emergency contact)

<div id='contacts_2' class="Anchor--hack"></div>

### contacts

The `contacts` `rel` provides a list of contacts associated with the origin object.

<div id='contact_email_addresses' class="Anchor--hack"></div>

### contact_email_addresses

<div id='contact_phone_numbers' class="Anchor--hack"></div>

### contact_phone_numbers

<div id='contact_preferences' class="Anchor--hack"></div>

### contact_preferences

<div id='events_1' class="Anchor--hack"></div>

## Events

An `event` is an associated object to a team; and represents an event or game that is tracked in the TeamSnap system.

<div id='events_2' class="Anchor--hack"></div>

### events

<div id='locations' class="Anchor--hack"></div>

### locations

<div id='opponents' class="Anchor--hack"></div>

### opponents

<div id='assignments' class="Anchor--hack"></div>

### assignments

<div id='availabilities' class="Anchor--hack"></div>

### availabilities


Users

teams

teams_preferences

custom_fields

tracked_items

tracked_item_statuses

Teams

members

member_email_addreses

member_phone_numbers

member_links

Members

contacts

contact_email_addresses

contact_phone_numbers

contact_preferences

Contacts

events

locations

opponents

assignments

availabilities

Events

API Objects

# Authorization

The TeamSnap API requires that all requests to the API are authorized. To authorize a request, it must have a valid OAuth 2 access token passed in the request header.

<div class="panel panel-warning"><h1 class="panel-title panel-heading"><i class="fa fa-exclamation-triangle"></i> New to OAuth 2?</h1><div class="panel-body"><b>This documentation does not cover the details of how OAuth 2 works or how to implement OAuth 2 client functionality.</b> If you are unfamiliar with OAuth 2, details on how OAuth 2 works can be found at the <a href="https://tools.ietf.org/html/rfc6749">official OAuth 2 spec</a>, and at the great <a href="https://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified">OAuth 2 Simplified Guide</a> by Aaron Parecki.</div></div>

<div class="panel panel-primary"><h1 class="panel-title panel-heading"><i class="fa fa-comment"></i> OAuth 2 Client Libraries</h1><div class="panel-body">TeamSnap recommends that you use an OAuth 2 client library to interact with TeamSnap's authorization service. A list of popular libraries is available at <a href="https://oauth.net/2/">http://oauth.net/2/</a>.</div></div>

<div id='creating-oauth-2-credentials' class="Anchor--hack"></div>

## Creating OAuth 2 Credentials

To authorize your request, an application credential set must exist on our system. You can create an application with the following steps:

1. Visit [https://auth.teamsnap.com](https://auth.teamsnap.com)
2. Login with your existing TeamSnap account ([create a free account](https://go.teamsnap.com/signup/trial) if you don't have one)
3. Click on your name, and click on <kbd>Your Applications</kbd>

When you create your application, you will be asked to specify redirect URIs that your service will utilize to obtain credentials. If you pass in a redirect URI to the authorization service later, without this redirect URI being specified in your application credential set, it will be rejected to protect the security of yours and TeamSnap's users.

<div id='oAuth-2-Endpoints' class="Anchor--hack"></div>

## OAuth 2 Endpoints

The specific endpoints available for TeamSnap's OAuth 2 service are:

* Authorization: `GET https://auth.teamsnap.com/oauth/authorize`
* Token Exchange: `POST https://auth.teamsnap.com/oauth/token`
* Token Revocation: `POST https://auth.teamsnap.com/oauth/revoke`

The OAuth 2 service does not provide an application credential / API endpoint.

<div id='web-application-flow' class="Anchor--hack"></div>

<div id='web-application-flow' class="Anchor--hack"></div>

## Web Application Flow

Also commonly known as 3-Leg OAuth, the web application flow is the recommended flow for any system that has a server seperate from the client. The steps are as follows:

<div id='redirect-user-to-teamsnap-1' class="Anchor--hack"></div>

### 1. Redirect User to TeamSnap

In your application, you should redirect the user to the appropriate authentication URL:

`GET https://auth.teamsnap.com/oauth/authorize`

with the appropriate parameters:

<table class="table table-condensed table-hover">
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>client_id</td>
<td>string</td>
<td><b>Required.</b> The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.</td>
</tr>
<tr>
<td>redirect_uri</td>
<td>string</td>
<td>The URL where you want users to be sent after authorization. This URI <b>MUST</b> be a subpath of a URI specified when you registered your application.</td>
</tr>
<tr>
<td>scope</td>
<td>string</td>
<td>A space-seperated list of scopes (permissions) your application requires.</td>
</tr>
<tr>
<td>response_type</td>
<td>string</td>
<td>code or token. For the web application flow, this should always be code.</td>
</tr>
</table>

<div id='authentication-callback-1' class="Anchor--hack"></div>

### 2. Authentication Callback

Once the user accepts your authorization request via TeamSnap, the authorization service will redirect the user back to the URI you specified in the `redirect_uri` parameter.

This request will have an appended `code` parameter that contains an authorization code eligible for exchange for a token. This code is only usable for 10 minutes and will expire after that.

`https://example.com/callback?code=00108f1794bac...`

<div id='exchange-code-for-token' class="Anchor--hack"></div>

### 3. Exchange Code for Token

The final step in this process is the token exchange.

<div class="panel panel-warning"><h1 class="panel-title panel-heading"><i class="fa fa-exclamation-triangle"></i> Token Exchange Security</h1><div class="panel-body">You should not, at any time, redirect the user to this URL. Token exchange should be performed on a trusted server ONLY to avoid exposing your client secret.</div></div>
\`POST https://auth.teamsnap.com/oauth/token\`

with the following parameters:

<table class="table table-condensed table-hover">
<tr>
  <th>Name</th>
  <th>Type</th>
  <th>Description</th>
</tr>
<tr>
  <td>client_id</td>
  <td>string</td>
  <td><b>Required.</b> The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.</td>
</tr>
<tr>
  <td>client_secret</td>
  <td>string</td>
  <td><b>Required.</b> The client_secret is the application secret you recieved from the TeamSnap Authorization Service when you registered your application.</td>
</tr>
<tr>
  <td>redirect_uri</td>
  <td>string</td>
  <td><b>Required if you specified a redirect_uri in the authorization request.</b> This redirect_uri MUST be the exact same as specified in the previous request.</td>
</tr>
<tr>
  <td>code</td>
  <td>string</td>
  <td><b>Required.</b> The authorization code recieved in the previous step for token exchange.</td>
</tr>
<tr>
  <td>grant_type</td>
  <td>string</td>
  <td><b>Required.</b> Should always be <code>authorization_code</code>.</td>
</tr>
</table>

and the following headers:

<table class="table table-condensed table-hover">
<tr>
  <th>Name</th>
  <th>Type</th>
  <th>Description</th>
</tr>
<tr>
  <td>content-length</td>
  <td>integer</td>
  <td><b>Required.</b> If the post doesn't have a body, make sure the content-length is 0.</td>
</tr>
</table>

<div id='token-authentication-flow' class="Anchor--hack"></div>

## Token Authentication Flow

Also commonly known as 2-Leg OAuth, the token authentication flow is for use when you do not have available a non-client server to perform token exchange. The steps are as follows:

<div id='redirect-user-to-teamsnap-2' class="Anchor--hack"></div>

### 1. Redirect User to TeamSnap

In your application, you should redirect the user to the appropriate authentication URL:

`GET https://auth.teamsnap.com/oauth/authorize`

with the appropriate parameters:

<table class="table table-condensed table-hover">
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>client_id</td>
<td>string</td>
<td><b>Required.</b> The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.</td>
</tr>
<tr>
<td>redirect_uri</td>
<td>string</td>
<td>The URL where you want users to be sent after authorization. This URI <b>MUST</b> be a subpath of a URI specified when you registered your application.</td>
</tr>
<tr>
<td>scope</td>
<td>string</td>
<td>A space-seperated list of scopes (permissions) your application requires.</td>
</tr>
<tr>
<td>response_type</td>
<td>string</td>
<td>code or token. For the token authentication flow, this should always be token.</td>
</tr>
</table>

<div id='authentication-callback-2' class="Anchor--hack"></div>

### 2. Authentication Callback

Once the user accepts your authorization request via TeamSnap, the authorization service will redirect the user back to the URI you specified in the `redirect_uri` parameter.

This request will have an appended `access_token` parameter passed as an HTML fragment that contains an authorization token eligible for immediate use.

`https://example.com/callback#access_token=00108f1794bac...`

<div id='using-oauth-2-credentials' class="Anchor--hack"></div>

## Using OAuth 2 Credentials

You will need to pass the authorization token you obtained to TeamSnap's API via the `Authorization` HTTP header:
`Authorization: Bearer [TOKEN]`

<div id='scopes' class="Anchor--hack"></div>

### Scopes

These are the scopes available via the OAuth 2 service:

* `read` - Default
* `write` - Full write access.
* `write_members` - Write access for members, contacts, and related sub-objects.
* `write_teams` - Write access for team information.
* `write_events` - Write access for team schedule (games and events).
* `write_users` - Write access for user information.

To use multiple scopes, pass a space-seperated list to the scope parameter during authorization.

<div id='revoking-an-access-token' class="Anchor--hack"></div>

## Revoking an Access Token

To revoke a user's Access Token, you may do that by submitting a POST to:

`https://auth.teamsnap.com/oauth/revoke`

and passing the following in as `POST` form data:

<b>IMPORTANT</b> Due to caching strategies employed on the TeamSnap platform, it may take up to 5 minutes for a revocation to bbe fully reflected on the platform.

<table class="table table-condensed table-hover">
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>token</td>
<td>string</td>
<td><b>Required.</b> The token that you are revoking.</td>
</tr>
<tr>
<td>client_id</td>
<td>string</td>
<td><b>Required.</b> The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.</td>
</tr>
<tr>
<td>client_secret</td>
<td>string</td>
<td><b>Required.</b> The client_secret is the application secret you recieved from the TeamSnap Authoirization Service when you registered the application.</td>
</tr>
</table>

Creating OAuth 2 Credentials

OAuth 2 Endpoints

1. Redirect User to TeamSnap

2. Authentication Callback

3. Exchange Code for Token

Web Application Flow

Token Authentication Flow

Scopes

Using OAuth 2 Credentials

Revoking an Access Token

Authorization


## Collection+JSON

The TeamSnap API is a hypermedia JSON API, using Collection+JSON. There are resources on the web available to describe Collection+JSON (including the official [Collection+JSON specification](http://amundsen.com/media-types/collection/)), so this document is only intended as a brief overview, and includes descriptions of TeamSnap API specific Collection+JSON extensions in use in our API.

<div id='basics' class="Anchor--hack"></div>

### Basics

There are 2 basic principles for Collection+JSON:

1. The API should be discoverable
1. The client should not be responsible for constructing URLs

<div id='discoverable-api' class="Anchor--hack"></div>

#### Discoverable API

Collection+JSON is designed to be inherently discoverable. Each response is always a collection, and each collection always contains all the pertinent actions performable on objects in that collection.

<div id='links-1' class="Anchor--hack"></div>

#### Links

A Collection+JSON client **should not** construct a URL because the Collection+JSON API makes no guarantee that URLs will remain static for the same actions on the API.

The API guarantees that the `rel` will remain static (unless there is a major version revision), but the `href` is subject to change. You should always use the `rel` to determine what `href` to follow.

```json
{
  "href": "https://apiv3.teamsnap.com/members/search?user_id=695269",
  "rel": "members"
}
```

In the example above, you can see that there are 2 components per link: the `rel` and the `href`. In this example, you would find this particular link via the `rel` `members`, and then navigate to the `href` provided: `https://apiv3.teamsnap.com/members/search?user_id=695269`.

It is sometimes helpful to think of Collection+JSON as a machine-optimized webpage. When you browse the internet, you generally do not construct your own URLs to a page of interest; instead, you click on existing links provided by the website author to navigate the website hierarchy as the website author intended.

<div id='rest' class="Anchor--hack"></div>

### REST

Collection+JSON is a RESTful specification. All interactions against the API follow this pattern:

<table class="table table-condensed table-hover">
<tr>
<th>Action</th>
<th>Verb</th>
<th></th>
</tr>
<tr>
<td>create</td>
<td><b>POST</b></td>
<td><small>Make a POST request against the <code>href</code> provided in the collection to create an object, using the <code>template</code> specified parameters</small>. Do not include any parameters that are not being set.</td>
</tr>
<tr>
<td>read</td>
<td><b>GET</b></td>
<td><small></small></td>
</tr>
<tr>
<td>update</td>
<td><b>PATCH</b></td>
<td><small>Make a PATCH request against the <code>href</code> provided for the specific object, using the <code>template</code> specified parameters</small>. Do not include any parameters that are not being updated.</td>
</tr>
<tr>
<td>destroy</td>
<td><b>DELETE</b></td>
<td><small>Make a DELETE request against the <code>href</code> provided for the specific object</small></td>
</tr>
</table>

<div id='response' class="Anchor--hack"></div>

### Response

There are multiple components in a Collection+JSON response body.

<div id='items' class="Anchor--hack"></div>

#### Items

Items are the meat of a Collection+JSON response. The `items` key in the `collection` body will contain an array of multiple JSON objects, and each object will contain `data` and a `href`, and can contain any of the other Collection+JSON components described later.

```json
"items": [
  {
  "data": [ "..." ],
  "href": "https://apiv3.teamsnap.com/users/695269",
  "links": [ "..." ]
  }
]
```

In the example above, the `items` key contains a solitary object, which itself contains `data`, a `href`, and `links`. Data is always specified in key value pairs as follows:

```json
"data": [
  {
    "name": "id",
    "value": 695269
  },
]
```

Each `data` object will contain a `name` and `value`, and can optionally contain a `type`. The `name` key represents the key of the key-value pair, while the `value` key represents the value of the key-value pair.

If a `type` is present, it will represent the data type of the key-value pair:

```json
{
  "name": "updated_at",
  "type": "DateTime",
  "value": "2014-10-01T09:19:36.000+00:00"
}
```

In the above example, the type is `DateTime` and indicates that the value is a DateTime (encoded in ISO 8601 Format).

<div id='links-2' class="Anchor--hack"></div>

#### Links

Links, as described above, indicate related objects that will be of interest. Links can be present in both the items in a collection, and on the collection itself.

```json
"links": [
  {
    "href": "https://apiv3.teamsnap.com/teams/search?user_id=695269",
    "rel": "teams"
  }
]
```

In the example above, the `links` array only contains one object. For links, the `rel` is the key and the `href` is the value of the key-value pair. Since the `href`s are subject to change at any time, **it is unwise to construct your own URLs!**

  <div id='queries' class="Anchor--hack"></div>

#### Queries

Queries are similar to links, in that they represent potential objects of interest. However, a query will require some construction (which is explicitly defined by the query object).

A query will contain a `data` array, an `href`, and a `rel`. As with links, you should rely on the `rel` to locate the specific query you are looking for.

```json
"queries": [
  {
    "data": [
      {
        "name": "id",
        "value": null
      }
    ],
    "href": "https://apiv3.teamsnap.com/users/search",
    "rel": "search"
  }
]
```

In the example above, the `queries` array contains a single query object. To construct this URL, you must take the `href` parameter, and then add the data parameters as URL parameters.

If we wanted to query for the user with the `id` of <kbd>40</kbd>, you would hit the following endpoint:

```bash
  OAUTH_ACCESS_TOKEN=your_oauth_access_token_here
  curl -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN" -X GET https://apiv3.teamsnap.com/users/search -d 'id=40'
```

If you are not using cURL, you will need to URL encode the parameters:

```
  GET https://apiv3.teamsnap.com/users/search?id=40
```

As with links, under no circumstances should you modify the `href` itself or rely on the `href` to remain static as it is subject to change at any time.

<div id='template' class="Anchor--hack"></div>

#### Template

A template is a recipe for updating or creating an object via the API. Each template will contain a `data` array, which will contain acceptable data to `POST` or `PATCH` against the collection or object `href`s.

```json
"template": {
  "data": [
    {
      "name": "first_name",
      "value": null
    }
  ]
}
```

In the template above, it contains a single datum. The client should use this datum to construct `POST` or `PATCH` form or multipart body encoded parameters.

Given the following (truncated) collection:

```json
{
  "collection": {
    "href": "https://apiv3.teamsnap.com/users",
    "items": [
      {
        "data": [
          {
            "name": "first_name",
            "value": "Charles"
          }
        ],
        "href": "https://apiv3.teamsnap.com/users/695269"
      }
    ],
    "template": {
      "data": [
        {
          "name": "first_name",
          "value": null
        }
      ]
    }
  }
}
```

If you wanted to create a new user, you would `POST` against the `href` specified in line 3:

```bash
  OAUTH_ACCESS_TOKEN=your_oauth_access_token_here
  HREF_OF_COLLECTION=https://apiv3.teamsnap.com/users
  # NOTE: The above href should be obtained from the response and not constructed manually.
  curl -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN" -X POST $HREF_OF_COLLECTION -d 'first_name=Bob'
```

and you will receive a response similar to the following:

```json
{
  "collection": {
    "href": "https://apiv3.teamsnap.com/users",
    "items": [
      {
        "data": [
          {
            "name": "first_name",
            "value": "Bob"
          }
        ],
        "href": "https://apiv3.teamsnap.com/users/1234567"
      }
    ],
    "template": {
      "data": [
        {
          "name": "first_name",
          "value": null
        }
      ]
    }
  }
}
```

If you wanted to modify the user instead, you would `PATCH` against the `href` specified in the object itself (on line 12):

```bash
  OAUTH_ACCESS_TOKEN=your_oauth_access_token_here
  HREF_OF_OBJECT=https://apiv3.teamsnap.com/users/695269
  # NOTE: The above href should be obtained from the response and not constructed manually
  curl -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN" -X PATCH $HREF_OF_OBJECT -d 'first_name=Robert'
```

and you would receive a response similar to the following:

```json
{
  "collection": {
    "href": "https://apiv3.teamsnap.com/users",
    "items": [
      {
        "data": [
          {
            "name": "first_name",
            "value": "Robert"
          }
        ],
        "href": "https://apiv3.teamsnap.com/users/1234567"
      }
    ],
    "template": {
      "data": [
        {
          "name": "first_name",
          "value": null
        }
      ]
    }
  }
}
```

<div id='extensions' class="Anchor--hack"></div>

### Extensions

The Collection+JSON spec supports the addition of extensions. These are the extensions in use for TeamSnap's API:

<div id='command-templates' class="Anchor--hack"></div>

#### Command Templates

The [Command Templates extension](https://github.com/collection-json/extensions/blob/master/command-templates.md) allows the discovery of commands in the Collection+JSON response. These commands are generally actions that don't fit cleanly in the normal RESTful responses, such as disabling a user or inviting a new team member.

```json
{
  "commands": [
    {
      "href": "/users/disable",
      "rel": "disable",
      "name": "Disable",
      "prompt": "Disable user",
      "data": [{ "name": "id", "value": "", "prompt": "User id to disable" }]
    }
  ]
}
```

<div id='type' class="Anchor--hack"></div>

#### Type

The [Type extension](https://gist.github.com/semmons99/0e02ece6e079cfac27c0) allows the specification of a type for any data attribute in the Collection+JSON response.

```json
{
  "name": "updated_at",
  "type": "DateTime",
  "value": "2014-10-01T09:19:36.000+00:00"
}
```

<div id='deprecated' class="Anchor--hack"></div>

#### Deprecated

The [Deprecated extension](https://github.com/collection-json/extensions/blob/master/deprecate.md) allows for an OPTIONAL deprecated property on items within the data array to indicate that the item is being removed. The value of the property SHOULD be a boolean value of true or false.

```json
data: [
  {
    "name": "old_name",
    "value": "Robert Tables",
    "prompt": "'old_name' is deprecated and will be removed in a future version, use 'new_name' instead."
    "deprecated": true
  },{
    "name": "new_name",
    "value": "Robert Tables",
    "prompt": "Name"
  }
]
```

<div id='read-only' class="Anchor--hack"></div>

#### Read-only

The [Read-only extension](https://github.com/collection-json/extensions/blob/master/read-only.md) informs the client that some collection items are read-only, while still allowing others to be updated and also new items to be created.

```json
{ "collection":
  {
    "version":"1.0",
    "href":"http://example.org/issues/",
    "items":[
       {
          "href":"http://example.org/issues/1",
          "read-only":true,
          "data":[
             { "name":"title", "value":"some non-updatable issue"}
          ]
       },
       {
          "href":"http://example.org/issues/2",
          "read-only":false,
          "data":[
             { "name":"title", "value":"some updatable issue"}
          ]
       },
       {
          "href":"http://example.org/issues/3",
          "data":[
             { "name":"title", "value":"some other updatable issue"}
          ]
       }
    ],
    "template": {(...)}
  }
}
```

<div id='example' class="Anchor--hack"></div>

### Example

The following is an example of a full Collection+JSON response.

```json
{
  "collection": {
    "href": "https://apiv3.teamsnap.com/users",
    "items": [
      {
        "data": [
          {
            "name": "id",
            "value": 695269
          },
          {
            "name": "type",
            "value": "user"
          },
          {
            "name": "first_name",
            "value": "Angus"
          },
          {
            "name": "last_name",
            "value": "McGillicuddy"
          },
          {
            "name": "email",
            "value": "angus.mcgillicudy@example.com"
          },
          {
            "name": "is_admin",
            "value": false
          },
          {
            "name": "facebook_id",
            "value": null
          },
          {
            "name": "facebook_access_token",
            "value": null
          },
          {
            "name": "receives_newsletter",
            "value": false
          },
          {
            "name": "birthday",
            "value": "1987-05-01"
          },
          {
            "name": "updated_at",
            "type": "DateTime",
            "value": "2014-10-01T09:19:36.000+00:00"
          },
          {
            "name": "created_at",
            "type": "DateTime",
            "value": "2012-11-12T17:05:51.000+00:00"
          }
        ],
        "href": "https://apiv3.teamsnap.com/users/695269",
        "links": [
          {
            "href": "https://apiv3.teamsnap.com/apn_devices/search?user_id=695269",
            "rel": "apn_devices"
          },
          {
            "href": "https://apiv3.teamsnap.com/gcm_devices/search?user_id=695269",
            "rel": "gcm_devices"
          },
          {
            "href": "https://apiv3.teamsnap.com/members/search?user_id=695269",
            "rel": "members"
          },
          {
            "href": "https://apiv3.teamsnap.com/teams/search?user_id=695269",
            "rel": "teams"
          }
        ]
      }
    ],
    "links": [
      {
        "href": "https://apiv3.teamsnap.com/apn_devices",
        "rel": "apn_devices"
      },
      {
        "href": "https://apiv3.teamsnap.com/gcm_devices",
        "rel": "gcm_devices"
      },
      {
        "href": "https://apiv3.teamsnap.com/members",
        "rel": "members"
      },
      {
        "href": "https://apiv3.teamsnap.com/teams",
        "rel": "teams"
      },
      {
        "href": "https://apiv3.teamsnap.com/",
        "rel": "root"
      },
      {
        "href": "https://apiv3.teamsnap.com/me",
        "rel": "self"
      }
    ],
    "queries": [
      {
        "data": [
          {
            "name": "id",
            "value": null
          }
        ],
        "href": "https://apiv3.teamsnap.com/users/search",
        "rel": "search"
      }
    ],
    "template": {
      "data": [
        {
          "name": "first_name",
          "value": null
        },
        {
          "name": "last_name",
          "value": null
        },
        {
          "name": "password",
          "value": null
        },
        {
          "name": "birthday",
          "value": null
        },
        {
          "name": "email",
          "value": null
        },
        {
          "name": "facebook_id",
          "value": null
        },
        {
          "name": "facebook_access_token",
          "value": null
        }
      ]
    },
    "version": "3.12.0"
  }
}
```


Discoverable API

Links

Basics

REST

Items

Queries

Template

Response

Command Templates

Type

Deprecated

Read-only

Extensions

Collection+JSON

Why OAuth?

Creating the Application

Redirect Request

Token Exchange

OAuth 2

First Request

Finding the Team

Listing Members

Updating Data

Updating the Team

Creating Data

Creating a Team Member

Creating Contact Information

Creating a Member Email Address

Creating a Member Phone Number

Inviting Members

TeamSnap API

Next Steps

Example

<h1>Overview</h1>
<p>This document describes the resources that make up the TeamSnap API.</p>
<h2>Getting Started</h2>
<div id='location' class="Anchor--hack"></div>
<h3>Location</h3>
<p>All API access is over HTTPS, and available via <a href="https://api.teamsnap.com/v3/"><code>https://api.teamsnap.com/v3/</code></a>.
It is highly recommended that you enforce certificate validation to ensure the security of your services and your users.</p>
<div id='schema' class="Anchor--hack"></div>
<h3>Schema</h3>
<p>TeamSnap's API is a <a href="http://amundsen.com/media-types/collection/">Collection+JSON</a> API. This differs from your normal RESTful style JSON API in a few very important ways:</p>
<ol>
<li>The client should not construct any URIs.</li>
<li>Caching of URIs is permitted; however, if an error is encountered, this cache should be cleared.</li>
<li>Every JSON object returned will be a collection.</li>
</ol>
<p>More information on how Collection+JSON works and how it applies to this API is available on the Collection+JSON page of this documentation.</p>
<div id='response-codes' class="Anchor--hack"></div>
<h4>Response Codes</h4>
<p>The most common response codes will be in the <code>200</code> and <code>400</code> ranges.</p>
<p>Successful Calls:</p>
<ul>
<li><code>200 OK</code> Call completed successfully.</li>
<li><code>201 CREATED</code> Object created successfully.</li>
<li><code>204 NO RESPONSE</code> Call completed, no response required.</li>
</ul>
<p>Unsuccessful Calls:</p>
<ul>
<li><code>401 UNAUTHORIZED</code> You are not authorized to access this resource. Try re-authorizing.</li>
<li><code>404 NOT FOUND</code> This resource does not exist, or you may be unauthorized. Try re-authorizing; if that fails, clear your URI cache.</li>
<li><code>411 Length Required</code> You need to add a Content Length header to your request.</li>
<li><code>429 TOO MANY REQUESTS</code> You have reached your rate limit.</li>
<li><code>500</code> Server took a brief vacation.</li>
</ul>
<div id='date-an-time' class="Anchor--hack"></div>
<h4>Date and Time</h4>
<p>All dates and times (including timestamps) are in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601 Format</a>.</p>
<div id='null-data' class="Anchor--hack"></div>
<h4>Null Data</h4>
<p>Blank fields are sent as <code>null</code> instead of being omitted from responses.</p>
<div id='versioning' class="Anchor--hack"></div>
<h4>Versioning</h4>
<p>The TeamSnap API versioning scheme adheres to the guidelines set out in <a href="http://semver.org/spec/v2.0.0.html">SemVer 2.0.0</a>. The version of the API is available in each request under the <code>version</code> field. Version is global across the API, resources are not versioned individually.</p>
<div id='constructing-a-request' class="Anchor--hack"></div>
<h3>Constructing a Request</h3>
<p>To construct a request, you will need to obtain an authorization token.</p>
