Skip to main content

​
Add Team Member

Add an existing user to a team with a specific role.

​
Endpoint

POST /api/teams/{teamId}/users

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Path Parameters

​
teamId
string
required
Team UUID

​
Request Body

​
userId
string
required
UUID of the user to add to the team
​
role
string
required
Role to assign to the user. Must be one of:
  • team-member - Can view and edit team resources
  • team-view-only - Read-only access to team resources
  • team-manager - Full permissions to manage team

​
Response

​
id
string
Team user relationship UUID
​
userId
string
User UUID
​
teamId
string
Team UUID
​
role
string
Assigned role
​
createdAt
string
ISO 8601 timestamp when user was added

​
Example Request

curl -X POST https://your-umami-instance.com/api/teams/660e8400-e29b-41d4-a716-446655440001/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "bb0e8400-e29b-41d4-a716-446655440006",
    "role": "team-member"
  }'

​
Example Response

{
  "id": "cc0e8400-e29b-41d4-a716-446655440007",
  "userId": "bb0e8400-e29b-41d4-a716-446655440006",
  "teamId": "660e8400-e29b-41d4-a716-446655440001",
  "role": "team-member",
  "createdAt": "2024-03-15T14:30:00.000Z"
}

​
Team Roles

​
team-manager
Full permissions including:
  • Manage team settings
  • Add/remove team members
  • Create/edit/delete team websites
  • View all team analytics
​
team-member
Standard permissions including:
  • View team websites and analytics
  • Edit team websites
  • Cannot manage team members or settings
​
team-view-only
Read-only permissions:
  • View team websites and analytics
  • Cannot edit anything

​
Error Responses

​
400
error
Bad Request - User is already a member of the team
​
401
error
Unauthorized - You must be the owner/manager of this team
​
404
error
Not Found - Team or user does not exist

​
Permissions

Only team owners and managers can add new members to the team.
The user must already exist in the Umami system. You cannot create new user accounts through this endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us