Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hotosm/tasking-manager/llms.txt

Use this file to discover all available pages before exploring further.

Teams in HOT Tasking Manager are named groups of contributors that belong to a single organisation. They can be assigned to mapping projects with a specific role (Mapper, Validator, or Project Manager), and their membership can be open, by-request, or invite-only. The endpoints below cover the full lifecycle of a team: creation, retrieval, updates, deletion, membership management, and project assignments.

​
Team CRUD

​
List Teams


GET /api/v2/teams/ Returns all teams visible to the authenticated user. Results can be filtered by team name, organisation, or by a user’s relationship to the team (member, manager, or pending request). Supports optional pagination. Authentication: Required Query Parameters
​
team_name
string
Filter teams by name (partial match).
​
member
integer
User ID — returns only teams where this user is an active member.
​
manager
integer
User ID — returns only teams where this user holds the MANAGER role.
​
member_request
integer
User ID — returns teams to which this user has submitted a pending join request.
​
team_role
string
Filter by team role on a project (e.g. MAPPER, VALIDATOR, PROJECT_MANAGER).
​
organisation
integer
Filter by organisation ID.
​
omitMemberList
boolean
default:"false"
When true, the response omits the full members array.
​
fullMemberList
boolean
default:"true"
When false, members are limited to 10 per role.
​
paginate
boolean
default:"false"
Enable paginated results.
​
page
integer
default:"1"
Page number when pagination is enabled.
​
perPage
integer
default:"10"
Number of results per page when pagination is enabled.
Response 200 OK 
{
  "teams": [
    {
      "teamId": 42,
      "name": "HOT Mappers",
      "organisationId": 1,
      "organisation": "Humanitarian OpenStreetMap Team",
      "joinMethod": "BY_REQUEST",
      "visibility": "PUBLIC",
      "description": "General mapping team for HOT projects",
      "members": [
        {
          "username": "jane_mapper",
          "function": "MANAGER",
          "active": true,
          "pictureUrl": "https://example.com/avatar.jpg",
          "joinedDate": "2024-01-15T10:00:00Z"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 1,
    "pages": 1
  }
}

​
Create a Team


POST /api/v2/teams/ Creates a new team under an organisation. The authenticated user must be an admin or an organisation manager to create a team. Authentication: Required (admin or org manager) Request Body
​
name
string
required
Display name for the team.
​
organisation_id
integer
required
ID of the organisation this team belongs to.
​
description
string
A short description of the team’s purpose.
​
visibility
string
required
Team visibility. One of PUBLIC or PRIVATE.
​
joinMethod
string
required
How users can join the team. One of ANY, BY_REQUEST, or BY_INVITE.
Response 201 Created 
{ "teamId": 42 }

curl -X POST https://tasking-manager-api.example.com/api/v2/teams/ \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HOT Mappers",
    "organisation_id": 1,
    "description": "General purpose mapping team",
    "visibility": "PUBLIC",
    "joinMethod": "BY_REQUEST"
  }'
Only users who are admins or managers of the specified organisation can create teams. A 403 Forbidden response is returned if the user lacks permission.

​
Get Team by ID


GET /api/v2/teams/{team_id}/ Retrieves full details for a single team, including its members list unless omitMemberList=true is passed. Authentication: Required Path Parameters
​
team_id
integer
required
The unique numeric team ID.
Query Parameters
​
omitMemberList
boolean
default:"false"
Set to true to exclude member details from the response.
Response 200 OK 
{
  "teamId": 42,
  "name": "HOT Mappers",
  "organisationId": 1,
  "organisation": "Humanitarian OpenStreetMap Team",
  "joinMethod": "BY_REQUEST",
  "visibility": "PUBLIC",
  "description": "General purpose mapping team",
  "members": [
    {
      "username": "jane_mapper",
      "function": "MANAGER",
      "active": true,
      "joinRequestNotifications": false,
      "pictureUrl": "https://example.com/avatar.jpg",
      "joinedDate": "2024-01-15T10:00:00Z"
    }
  ]
}

​
Update a Team


PATCH /api/v2/teams/{team_id}/ Updates one or more fields of an existing team. The requesting user must be a team manager or an organisation admin. Authentication: Required (team manager or org admin) Path Parameters
​
team_id
integer
required
The unique numeric team ID.
Request Body — all fields are optional
​
name
string
New name for the team.
URL of a logo image.
​
description
string
Updated description.
​
joinMethod
string
One of ANY, BY_REQUEST, or BY_INVITE.
​
visibility
string
One of PUBLIC or PRIVATE.
​
members
array
Full replacement list of team members. Each item must include username and function (MANAGER or MEMBER).
Response 200 OK 
{ "Status": "Updated" }

​
Delete a Team


DELETE /api/v2/teams/{team_id}/ Permanently deletes a team. The team must not have any associated projects. Authentication: Required (team manager) Path Parameters
​
team_id
integer
required
The unique numeric team ID.
Response 200 OK — team deleted successfully. Error Responses
StatusMeaning
401Missing or invalid authentication token
403User is not a team manager
404Team not found

​
Team Actions

​
Request to Join a Team


POST /api/v2/teams/{team_id}/actions/join/ Submits a join request for the authenticated user. Behaviour depends on the team’s joinMethod: immediate membership for ANY, or a pending request for BY_REQUEST. Authentication: Required Path Parameters
​
team_id
integer
required
ID of the team to join.
Response 200 OK 
{ "Success": "Join request successful" }

​
Accept or Reject a Join Request


PATCH /api/v2/teams/{team_id}/actions/join/ Allows a team manager to accept or reject a pending join request, or allows a user to respond to an invitation. Authentication: Required Path Parameters
​
team_id
integer
required
ID of the team.
Request Body
​
username
string
required
Username of the user whose request is being acted upon.
​
type
string
required
The action type. Use join-response when a manager is acting on a join request, or invite-response when a user is responding to an invitation.
​
action
string
required
Either accept or reject.
​
role
string
default:"member"
The role to assign if accepting. One of MANAGER or MEMBER.
Response 200 OK 
{ "Success": "True" }
Only team managers can respond to join-response requests. Any authenticated user can respond to invite-response requests directed at them.

​
Leave a Team


POST /api/v2/teams/{team_id}/actions/leave/ Removes a user from the team. A team manager can remove any member; a regular member can only remove themselves. Authentication: Required Path Parameters
​
team_id
integer
required
ID of the team.
Request Body
​
username
string
required
Username of the member to remove.
Response 200 OK 
{ "Success": "User removed from the team" }

​
Add a Member Directly


POST /api/v2/teams/{team_id}/actions/add/ Allows a team manager to add a user directly without requiring a join request. Authentication: Required (team manager) Path Parameters
​
team_id
integer
required
ID of the team.
Request Body
​
username
string
required
Username of the user to add.
​
role
string
Role to assign: MANAGER or MEMBER. Defaults to MEMBER if omitted.
Response 200 OK 
{ "Success": "User added to the team" }

​
Message All Team Members


POST /api/v2/teams/{team_id}/actions/message-members/ Sends an in-app message to every active member of the team. The operation is dispatched as a background task. Authentication: Required (team manager) Path Parameters
​
team_id
integer
required
ID of the team.
Request Body
​
subject
string
required
Subject line of the message.
​
message
string
required
Body of the message. Must not be empty.
Response 200 OK 
{ "Success": "Message sent successfully" }

​
Download Join Requests (CSV)


GET /api/v2/teams/join_requests/ Downloads a CSV file of users who have submitted join requests (inactive members) for a given team. Authentication: Required Query Parameters
​
team_id
integer
required
ID of the team to query.
Response — text/csv file with columns: Username, Date Joined (UTC), Team Name.

​
Project–Team Associations

​
List Teams for a Project


GET /api/v2/projects/{project_id}/teams/ Returns all teams currently assigned to a project, including each team’s role. Authentication: Required Path Parameters
​
project_id
integer
required
ID of the project.
Response 200 OK 
{
  "teams": [
    {
      "teamId": 42,
      "name": "HOT Mappers",
      "role": "MAPPER"
    }
  ]
}

​
Assign a Team to a Project


POST /api/v2/projects/{project_id}/teams/{team_id}/ Assigns a team to a project with a specified role. The requesting user must be both a team manager and a project manager. Authentication: Required (team manager + project manager) Path Parameters
​
project_id
integer
required
ID of the project.
​
team_id
integer
required
ID of the team to assign.
Request Body
​
role
string
required
The role for the team on this project. One of MAPPER, VALIDATOR, or PROJECT_MANAGER.
Response 201 Created 
{ "Success": "Team 42 assigned to project 7 with role MAPPER" }

​
Update a Team’s Role on a Project


PATCH /api/v2/projects/{team_id}/projects/{project_id}/ Changes the role of an already-assigned team on a project. The requesting user must be a project manager. Authentication: Required (project manager) Path Parameters
​
team_id
integer
required
ID of the team.
​
project_id
integer
required
ID of the project.
Request Body
​
role
string
required
New role for the team. One of MAPPER, VALIDATOR, or PROJECT_MANAGER.
Response 201 
{ "Status": "Team role updated successfully." }

​
Remove a Team from a Project (via project manager)


DELETE /api/v2/projects/{team_id}/projects/{project_id}/ Removes a team from a specific project. The caller must be a project manager. Authentication: Required (project manager) Path Parameters
​
team_id
integer
required
ID of the team to remove.
​
project_id
integer
required
ID of the project.
Response 200 OK 
{ "Success": true }

​
Remove a Team from a Project (via team manager)


DELETE /api/v2/teams/projects/{project_id}/teams/{team_id}/ Unlinks a team from a specific project. The caller must be a team manager. Authentication: Required (team manager) Path Parameters
​
project_id
integer
required
ID of the project.
​
team_id
integer
required
ID of the team to remove.
Response 200 OK 
{ "Success": true }

DELETE /api/v2/teams/projects/teams/{team_id}/unlink Removes the specified team from every project it is currently assigned to. All unlinking operations are executed inside a single database transaction — if any check fails, no changes are committed. Authentication: Required (team manager) Path Parameters
​
team_id
integer
required
ID of the team to unlink everywhere.
Response 200 OK 
{
  "Success": true,
  "Message": "Team id-42 unlinked from projects: 7, 12, 15"
}

DELETE /api/v2/teams/projects/unlink Accepts a list of project/team pairs and removes each assignment in a single atomic transaction. All permission checks run before any database write. Authentication: Required (team manager for every team in the list) Request Body
​
items
array
required
Array of objects, each containing project_id (integer) and team_id (integer).
{
  "items": [
    { "project_id": 7,  "team_id": 42 },
    { "project_id": 12, "team_id": 42 }
  ]
}
Response 200 OK 
{
  "Success": true,
  "Message": "Unlinked teams: (project 7, team 42), (project 12, team 42)"
}

​
Data Models

TeamVisibility — PUBLIC | PRIVATE TeamJoinMethod — ANY | BY_REQUEST | BY_INVITE TeamMemberFunctions — MANAGER | MEMBER TeamRoles (project assignments) — READ_ONLY | MAPPER | VALIDATOR | PROJECT_MANAGER
The joinMethod field controls who may enter the team. ANY grants immediate access on request; BY_REQUEST creates a pending entry that a manager must approve; BY_INVITE requires a manager to explicitly add the user.

Build docs developers (and LLMs) love

Get started for freeTalk to us