Skip to main content

​
Overview

Teams are groups within organizations that can be assigned as collaborators on projects. Teams provide a convenient way to manage access for groups of users.

​
List Teams

curl -X GET "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/organizations/{organization_name}/teams/ List all teams within an organization.

​
Path Parameters

​
organization_name
string
required
The username of the organization

​
Response

Returns an array of team objects.
​
team
string
Team name (without organization prefix)
​
organization
string
Organization username
​
members
array
Array of member usernames in this team
[
  {
    "team": "field_team",
    "organization": "acme_org",
    "members": ["jane_smith", "bob_wilson"]
  },
  {
    "team": "admin_team",
    "organization": "acme_org",
    "members": ["john_doe"]
  }
]

​
Create Team

curl -X POST "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "survey_team"
  }'
POST /api/v1/organizations/{organization_name}/teams/ Create a new team within an organization.

​
Path Parameters

​
organization_name
string
required
The username of the organization

​
Request Body

​
team
string
required
Team name (without organization prefix). The full team username will be @{organization_name}/{team_name}

​
Response

Returns the created team object. 
{
  "team": "survey_team",
  "organization": "acme_org",
  "members": []
}

​
Error Responses

{
  "error": "A team with this name already exists."
}

​
Get Team

curl -X GET "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/{team_name}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/organizations/{organization_name}/teams/{team_name}/ Retrieve details of a specific team.

​
Path Parameters

​
organization_name
string
required
The username of the organization
​
team_name
string
required
The team name (without organization prefix)

​
Response

Returns a single team object. 
{
  "team": "field_team",
  "organization": "acme_org",
  "members": ["jane_smith", "bob_wilson"]
}

​
Update Team

curl -X PUT "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/{team_name}/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "field_survey_team"
  }'
PUT /api/v1/organizations/{organization_name}/teams/{team_name}/ Update a team’s name.

​
Path Parameters

​
organization_name
string
required
The username of the organization
​
team_name
string
required
The current team name (without organization prefix)

​
Request Body

​
team
string
required
New team name (without organization prefix)

​
Response

Returns the updated team object. 
{
  "team": "field_survey_team",
  "organization": "acme_org",
  "members": ["jane_smith", "bob_wilson"]
}

​
Error Responses

{
  "error": "A team with this name already exists."
}

​
Delete Team

curl -X DELETE "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/{team_name}/" \
  -H "Authorization: Token YOUR_TOKEN"
DELETE /api/v1/organizations/{organization_name}/teams/{team_name}/ Delete a team from the organization.

​
Path Parameters

​
organization_name
string
required
The username of the organization
​
team_name
string
required
The team name to delete (without organization prefix)

​
Response

Returns HTTP 204 No Content on success.

​
List Team Members

curl -X GET "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/{team_name}/members/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/organizations/{organization_name}/teams/{team_name}/members/ List all members of a specific team.

​
Path Parameters

​
organization_name
string
required
The username of the organization
​
team_name
string
required
The team name (without organization prefix)

​
Response

Returns an array of team member objects.
​
member
string
Username of the team member
[
  {
    "member": "jane_smith"
  },
  {
    "member": "bob_wilson"
  }
]

​
Add Team Member

curl -X POST "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/{team_name}/members/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member": "alice_johnson"
  }'
POST /api/v1/organizations/{organization_name}/teams/{team_name}/members/ Add a user to a team.

​
Path Parameters

​
organization_name
string
required
The username of the organization
​
team_name
string
required
The team name (without organization prefix)

​
Request Body

​
member
string
required
Username or email of the user to add to the team

​
Response

Returns the created team member object. 
{
  "member": "alice_johnson"
}

​
Error Responses

{
  "member": ["User \"alice_johnson\" does not exists."]
}

{
  "member": ["Team member \"alice_johnson\" already exists."]
}

​
Remove Team Member

curl -X DELETE "https://app.qfield.cloud/api/v1/organizations/{organization_name}/teams/{team_name}/members/{member_username}/" \
  -H "Authorization: Token YOUR_TOKEN"
DELETE /api/v1/organizations/{organization_name}/teams/{team_name}/members/{member_username}/ Remove a user from a team.

​
Path Parameters

​
organization_name
string
required
The username of the organization
​
team_name
string
required
The team name (without organization prefix)
​
member_username
string
required
Username of the member to remove

​
Response

Returns HTTP 204 No Content on success.

​
Team Usage

Teams are useful for:

​
Project Collaboration

Add entire teams as project collaborators instead of individual users: 
curl -X POST "https://app.qfield.cloud/api/v1/collaborators/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collaborator": "@acme_org/field_team",
    "role": "editor"
  }'

​
Access Management

When you add a user to a team, they automatically inherit access to all projects where the team is a collaborator.

​
Team Naming

Team usernames follow the format @{organization}/{team_name}:
  • Organization: acme_org
  • Team name: field_team
  • Full team username: @acme_org/field_team
When making API calls:
  • Use just the team name (e.g., field_team) for team-specific endpoints
  • Use the full team username (e.g., @acme_org/field_team) when adding teams as collaborators

Build docs developers (and LLMs) love

Get started for freeTalk to us