TeamForm Public API

TeamForm offers a public API which customers and integrators can use to access TeamForm data.

Documents are published as an OpenAPI (swagger) specification.

For customers using a branded URL please access specs via http://yourcompany.teamform.co/api-docs or access via the ? Support icon within the app:

Open

A link to the API documentation can be found under the section of the left menu.

For customers without a branded url, the docs can be found at http://app.teamform.co/api-docs

How can I get an API secret / access?

• API credentials can be managed by TeamForm admins via Settings → Tenant settings → API key manager:

Open

Screen to browse and Generate API keys in the Tenant Settings.

• Upon creation of new API credentials, you will receive a client_id and a client_secret.

• Both pieces of information should be treated like a password - keep them secret, and store them securely. TeamForm will only show the client_secret once after the successful creation of new credentials.

Why do people use the API?

• The most common use case for the API is to integrate with downstream systems that need team and membership data and as a mechanism to export data for the purposes of reporting and analytics in a customer data warehouse / lake.

• We are continuing to evolve the API over time as we discuss new use cases with customers.

Where can I find my tenant and workspace IDs?

• This information is visible by doing the following steps

• On the left hand menu (towards the bottom) click on the Question mark icon ？

• From there you will be presented with API doc guidance (bottom section) and the associated tenant and workspace IDs respectively. These are needed for you to create your API queries.

Open

How do I get a bearer token and how does it work (e.g. expiry etc.)

• What is bearer authentication / bearer token https://swagger.io/docs/specification/authentication/bearer-authentication/

• How do I get a bearer token once I have my API secret? Make the following call (token expires each 24 hours)

Making your first query

• Calls are structured https://api.teamform.co/<tenant id>/api/<api call>

• For example, Get Teams is https://api.teamform.co/<tenant id>/api/getTeams

Considerations for using the API

• Data is real time (vs access via TeamForm reporting which has a ~1hr lag)

• Can be integrated into Enterprise applications or reporting suites such as PowerBI and Tableau

• Excessive calls can impact performance of a customer TeamForm instance. By default, the api is rate limited to 20 requests per second, so individual calls should be less than this.

What does a typical API call flow look like, once I have my key and ID?

• to begin, use the secret key and Client ID to make a request for a TeamForm API access token.

  • this access token will automatically expire after 24 hours, see above for an example.

• you can now start making requests! On each request, you must include your access token, gained above. For example, to make a cURL request to the searchTeams endpoint, that will list all the teams in your active workspace:

  • export API_TOKEN="<access token>" export TENANT_ID="<your tenant id, from the authorizer step above>" curl --request POST \ --url https://api.teamform.co/${TENANT_ID}/api/searchTeams \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer ${API_TOKEN}" \ --data '{ "search": "", "size": 10 }'

    Note:

    • you’ll also need to add in your <tenant id> to this example, in the --url section.

    • the region ID must be added to the --url when making calls outside of the Asia Pacific

I want to get all people and all teams, what is the best way to do this?

• to bulk fetch team members, use the /searchPeople endpoint

• to bulk fetch teams, use the /searchTeams endpoint. This also provides teams that have no team members, eg are structural.

• To link people to teams, use

  • getTeamsMemberships (provide list of Teams, gets people for each team) or

  • getPeopleMemberships (provide list of people, get teams of which they are members).

  • Recommended done in batches of <1000 people or teams to reduce api gateway load (Requires automation of api calls to cycle through a full list of people or teams, noting gateway limit of 20 requests per second for all calls. if this is exceeded a 504 GATEWAY TIMEOUT error will be issued. reduce the batch size and try again)

• to bulk fetch tags, use

  • getPeopleTags to get the tags applied to people

  • getTeamTags to get the tags applied to teams

  • noting that depending on the tag configuration in teamform, the same type of tag could be applied to both people and teams