API Versions

AMS has three API versions, each with different authentication patterns, design philosophies, and capabilities. Most integrations use a combination of versions rather than sticking to one.

Quick Reference

v1 — Use This for Most Data Operations

V1 is the most widely used version and covers the majority of day-to-day integration needs. If you're pulling event data, writing event data, managing users, or working with profiles, you'll spend most of your time here.

Use v1 for:

• Reading event data (/api/v1/synchronise, /api/v1/eventsearch)
• Writing event data (/api/v1/eventimport, /api/v1/eventsimport)
• Reading and writing profile data
• User synchronisation and search
• Group listing and membership

Auth: HTTP Basic Auth — pass username and password on every request. Simple to implement, no session management required.

Note: V1 returns HTTP 200 for successful data operations. Check the response body for a state field to confirm success — import and sync endpoints return "state": "SUCCESSFULLY_IMPORTED" or similar on success, and "state": "FAILED" on failure. Authentication failures return HTTP 401; inaccessible forms return HTTP 403.

v2 — Use This for User and Group Management

V2 gives you more control than v1 for administrative operations, particularly around user creation and group management. The key capability v1 lacks is the ability to set the active flag when creating a user — v2's person/save endpoint handles this.

Use v2 for:

• Creating users with the active flag set (/api/v2/person/save)
• Creating and managing groups (/api/v2/group/save)
• Assigning subgroups (/api/v2/subgroup/save)
• Database form operations
• Deleting multiple events in one call
• File upload status

Auth: Session-based — requires two calls before you can do anything else. See the Authentication guide for the full flow. Store the applicationId from the login response — it's required as a parameter in some v2 write operations such as creating groups.

v3 — Use This for Discovery and Modern Queries

V3 is the most modern version and uses proper HTTP verbs (GET, POST) with standard error response codes. It's best for discovering what's available on an instance and for querying groups and athletes.

Use v3 for:

• Listing all available forms (GET /api/v3/forms/summaries)
• Retrieving form schemas (GET /api/v3/forms/{type}/{id})
• Querying groups and their athletes (GET /api/v3/group-athletes)
• Retrieving event change history

Auth: Same session-based flow as v2 — the session token works across both.

Note: V3 returns standard HTTP status codes (404, 422) with a structured error body, making error handling straightforward compared to v1 and v2.

Typical Integration Pattern

Most integrations combine all three versions in a predictable way:

1. Authenticate using v1 Basic Auth or the v2 session flow depending on what you need
2. Discover forms using v3 (/api/v3/forms/summaries + schema endpoint) — do this once and cache the results
3. Sync users using v1 (/api/v1/usersynchronise) — cache and update incrementally
4. Read/write data using v1 event and profile endpoints
5. Manage users and groups using v2 when you need the extra control

💡

If you only need to read data from AMS, you can often get away with v1 alone. V2 and v3 become necessary when you need to manage users, discover form structures programmatically, or handle errors more gracefully.

A Note on Future Versions

A v4 API is in development, designed as a fully public REST API with OpenAPI 3.1 documentation, proper versioning, and improved developer experience. Documentation will be published when v4 is available. Existing v1–v3 integrations will continue to be supported.