Guides
  1. Getting Started

Understanding AMS Data Structures

AMS is a no-code platform, meaning your organisation's administrators and builders have configured its data structures — not Teamworks. This has an important implication for API users: you will not find terms like "Training Sessions" or "Athlete Classifications" anywhere in this documentation, because those are labels your organisation has applied to generic AMS constructs.

Understanding those constructs is essential before you build against the API.

Users

Every piece of data in AMS is saved against a User. Users represent both athletes and staff. Before you can read or write any data, you need a list of user IDs to work with.

Users belong to Groups, and your API account's access is determined by which groups it is a Coach of. If you can't see a user in the AMS web app with your API account, you won't be able to access their data via the API either.

💡

Always maintain a cached list of user IDs using /api/v1/usersynchronise rather than fetching the full user list on every call. See the Syncing Data to an External System recipe for details.

The Three Form Types

All data in AMS is stored in one of three form types. The form type determines which API endpoints you use to read and write data.

Events

Events are the primary data type in AMS. They represent time-stamped records saved against a user — think training sessions, wellness checks, GPS sessions, injury assessments, or any other ongoing data collection.

Key characteristics:

  • Every event has a start date, finish date, start time, and finish time
  • Multiple events of the same type can exist for the same user
  • Events support multi-row entry (a single event can contain a table of data)
  • Event forms can include calculated fields that derive values from historical data

Use /api/v1/synchronise to read events and /api/v1/eventimport to write them.

Profiles

Profiles are like a special event with only one record per user. They have no entry date and are intended for data that doesn't change over time — things like emergency contacts, passport details, shoe size, or sport-specific classifications.

Key characteristics:

  • Only one profile record exists per user per form
  • Writing to a profile overwrites the existing record — there is no merge
  • No timestamps

Use /api/v1/profilesearch to read profiles and /api/v1/profileimport to write them.

Databases

Despite the name, Databases in AMS are not relational databases. Think of them as managed lookup lists — dynamic collections of records saved against the application itself rather than against individual users.

They're typically used for standardised dropdown values that end users can manage through the UI (e.g. a list of injury types, exercise names, or medication codes). Other forms can reference database entries as a question type.

Use /api/v2/userdefineddatabase/findTableByDatabaseFormId to read and /api/v2/userdefineddatabase/save to write.

Form Names and Field Names are Instance-Specific

Because AMS is a no-code platform, every organisation has built their own forms with their own names. The API references forms and fields by their exact names as configured in your AMS instance — not by any standardised identifier.

For example, to read event data you pass a formName parameter:

{
  "formName": "GPS Session",
  "userIds": [1009]
}

The value "GPS Session" is whatever your organisation named that form. Another organisation might call the same concept "Catapult Data" or "Training Load".

⚠️

Form names and field names are case-sensitive and must match exactly as they appear in the AMS builder. Use GET /api/v3/forms/summaries to retrieve a list of all forms available to your account, and GET /api/v3/forms/{form_type}/{form_id} to inspect a form's exact field names.

Discovering Your Instance's Data Structure

Before building any integration, use the Forms endpoints to understand what data is available:

  1. Call GET /api/v3/forms/summaries to list all forms your account can access
  2. Note the id and name of each form you need
  3. Call GET /api/v3/forms/event/{form_id} to retrieve the full schema — all field names, types, and configuration

This schema discovery step is essential and should be repeated whenever a builder modifies a form your integration depends on.

Updated 7 days ago