Skip to main content
POST
/
teams
/
upsert
Upsert Team
curl --request POST \
  --url https://api.village.do/v1/teams/upsert \
  --header 'Content-Type: application/json' \
  --header 'user-identifier: <user-identifier>' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "name": "Engineering Team",
  "team_id": "app-123-engineering-team",
  "logo": "https://example.com/team-logo.png"
}
'
{
  "id": "app-123-engineering-team",
  "name": "Engineering Team",
  "logo": "https://example.com/team-logo.png",
  "invite_link": "https://village.do/invite/xyz789"
}

Authorizations

​
x-access-token
string
header
required

JWT token obtained from /users/authorization endpoint

Headers

​
user-identifier
string
required

Specify the user making the request. This identifier should match the one you used when integrating the user with Village. Not needed when using user token authentication.

Body

application/json
​
name
string
required

Name of the team

Example:

"Engineering Team"

​
team_id
string

Optional. Team identifier for update operations. If provided, updates existing team; if omitted, creates new team.

Example:

"app-123-engineering-team"

Logo URL for the team (optional)

Example:

"https://example.com/team-logo.png"

Response

Team created or updated successfully

​
id
string

Unique identifier for the team

Example:

"app-123-engineering-team"

​
name
string

Name of the team

Example:

"Engineering Team"

​
logo
string | null

Logo URL for the team

Example:

"https://example.com/team-logo.png"

​
invite_link
string

Invite link for the team

Example:

"https://village.do/invite/xyz789"