This article about using the Teamworks AMS API is aimed at technical users and software engineers. It is applicable to our clients and third party vendors.
The Teamworks AMS API facilitates the input and output of your AMS data. It allows you to view the configuration of the event and profile forms on your AMS site, as well as perform some basic administrative tasks like creating new user accounts.
This article provides an overview of the AMS API and its capabilities, including the following topics:
Prerequisites
Before you can begin using the AMS API, specific settings must be enabled for your AMS site. Please contact your Product Success Manager for more information.
To use the API, you will need an AMS account with the appropriate roles and groups for the data that you are authorized to access. Your AMS administrator can assist with setting this up.
You will need the following details:
- Username and password for your AMS account.
- The URL of your AMS site (e.g. https://example.smartabase.com/site).
- The version of your AMS instance, which can be found in the footer of the login screen (e.g. Version 6.12.6 shown in the screenshot below).
Documentation and getting started
Documentation is available upon request and, depending on the version of the endpoints (newer or older), comes either online or as a Postman collection. The documentation provides the specification for the API as well as code examples.
Using newer endpoints
Newer endpoints provide access to some existing new features that we have worked on recently.
Please contact your Product Success Manager to gain access to docs.smartabase.dev. The documentation will tell you how to authenticate and what you need to include in headers. Note that you will use a username and password to create a session for all subsequent API requests. The data is transmitted in JSON format.
Using older endpoints
Older endpoints facilitate CRUD operations on user data, including creating and updating accounts.
Please contact your Product Success Manager to request the documentation. Most older endpoints use basic authorization for each request, and data is transmitted in JSON format.
We recommend acquainting yourself with the AMS API using Postman. Although Postman is an independent third-party tool, it's a popular choice for working with APIs and can be invaluable. It allows you to engage with your AMS site through the API and obtain code snippets in your preferred programming language. For your convenience, we provide documentation as a Postman collection to assist you in getting started.
Over time, we will transition old API features to the newer version of the API and then deprecate them, but we will proactively communicate any plans to do so.
Development and testing
We highly recommend you begin using the AMS API with test data and accounts that do not belong to real people. This will reduce the risk of adding any incorrect data to someone’s account, deleting data by mistake or causing unnecessary load on your AMS site. Your AMS administrator will be able to set this up.
Further, you may wish to evaluate your use of the API on a separate instance of AMS reserved for development and testing. If you would like to look into this option, please contact your Product Success Manager.
Further reading
AMS is a complex product with many features. It is also a no-code platform, so the version you are working with has undoubtedly been used to create bespoke data structures, calculations and workflows. For example, your end users may have asked you to retrieve "training sessions" or "athlete classifications." You will not find these terms in this documentation or anywhere in the API because, as far as AMS is concerned, these are labels configured by your organization within events stored as event forms.
This can be hard to understand without a UI to guide you. Therefore, reviewing the Teamworks AMS Fundamentals course is highly recommended. It is free and designed to take no more than two hours. You can register for the course through the Teamworks AMS Academy.