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?

...

• 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/OS/pages/2924085317/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 (e.g.)

  • 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 team hierarchy, use getTeams, using same approach aboveto bulk fetch tags, use getPeopleTags and get TeamTagstags, 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