Page Comparison

...

For customers using a branded URL please access /api-docs to your customer URL or access via the ? Support icon within the app. :

...

How can I get an API secret / access?

• Please raise a support request via https://www.teamform.co/help

• Request an API secret, include the tenant and workspace (you will need to be a TeamForm administrator, or have obtained their permission to obtain api access)

  • Upon successful completion of your request, you will receive from TeamForm a client_id, and a client_secret.

  • Both pieces of information should be treated like a password - keep them secret, and only store them securely.

...

• 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 getTeams endpoint searchTeams endpoint, that will list all the teams in your active workspace:

  • Code Block
    language bash
    export API_TOKEN="<access token>" export TENANT_ID="<your tenant id, from the authorizer step above>" curl --request GETPOST \ --url https://api.teamform.co/<tenant id>/<tenant id>${TENANT_ID}/api/getTeamssearchTeams \ --header 'Content-Type: application/json' \ --header '"Authorization: Bearer <access token>'${API_TOKEN}" \ --data '<your request payload>{ "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 (see https://teamform.atlassian.net/wiki/spaces/TFW/pages/2852290854/What+is+the+TeamForm+Public+API#Making-your-first-query )

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 people, 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