Telgea Developer Docs

The team object

Group users for billing, access control, and reporting.

Field	Type	Description
`id`required	string	UUID of the team. `2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70`
`name`required	string	Team name. `Field Sales`
`emoji`required	string	Emoji shown next to the team name, or null. `🚀`
`costCode`required	string	Cost center code applied to all users in this team `CC-4100`
`memberCount`required	integer	Number of users currently in the team. `12`
`isDefault`required	boolean	Whether this is your organization's default team, Unassigned. Every user in no other team is in it, and it cannot be updated. `false`

List all teams

GET/v1/teams

Enterprise API

Retrieves a paginated list of all teams in your organization. Teams are organizational units used to group users for billing, access control, and reporting purposes.

Use the page and pageSize query parameters to navigate through large result sets.

Requires the permission teams:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`page`	query	integer	Page to return, starting at 1. `1`
`pageSize`	query	integer	Items per page, at most 50. Defaults to 50. `50`

Responses

Status	Meaning	Body
`200`	Successfully retrieved teams. Returns a paginated list with total count.	`ListTeamsResponse`
`400`	Request failed schema validation, or was refused by a business rule	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to list teams	`ForbiddenError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

This endpoint returns no domain-specific problems.

Response fields

200 ListTeamsResponse

Field Type Description

pagerequired

integer

The page these items came from.

1

pageSizerequired

integer

Items per page, as requested.

50

itemsCountrequired

integer

Total items across all pages. Divide by pageSize to get the number of pages.

142

itemsrequired array of TeamListItem Teams on this page.

Show 6 child fields of items

Field	Type	Description
`id`required	string	UUID of the team. `2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70`
`name`required	string	Team name. `Field Sales`
`emoji`required	string	Emoji shown next to the team name, or null. `🚀`
`costCode`required	string	Cost center code applied to all users in this team `CC-4100`
`memberCount`required	integer	Number of users currently in the team. `12`
`isDefault`required	boolean	Whether this is your organization's default team, Unassigned. Every user in no other team is in it, and it cannot be updated. `false`

GET/v1/teams

Request

curl -X GET "https://api.telgea.com/v1/teams" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "page": 1,
  "pageSize": 50,
  "itemsCount": 3,
  "items": [
    {
      "id": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
      "name": "Field Sales",
      "emoji": "🚀",
      "costCode": "CC-4100",
      "memberCount": 12,
      "isDefault": false
    },
    {
      "id": "7c2e9f10-4b83-4d55-a0e6-1f8b3d6c2a94",
      "name": "Support",
      "emoji": null,
      "costCode": null,
      "memberCount": 4,
      "isDefault": false
    },
    {
      "id": "2b8d4e61-9c37-4f02-b5a8-6e1d0c7f3a59",
      "name": "Unassigned",
      "emoji": "▫️",
      "costCode": null,
      "memberCount": 7,
      "isDefault": true
    }
  ]
}

Create a new team

POST/v1/teams

Enterprise API

Creates a new team in your organization. Teams help organize users into logical groups for billing, access control, and reporting.

After creating a team, you can assign users to it and associate it with billing entities for billing allocation.

Requires the permission teams:create on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`idempotency-key`	header	string	A value unique to this request, of 1 to 255 printable ASCII characters — a UUID is the usual choice. Retry with the same key within 24 hours and you get the original response back, even if it was a failure, and nothing is done twice. Send a new key whenever you change the request. Keys are private to your API key and organisation. `0b7e4f1c-6a2d-4c9e-8f35-d1a7b2c93e60`

Request body

Field	Type	Description
`name`required	string	Team name `Field Sales`
`emoji`	string	Emoji representing the team `🚀`
`costCode`	string	Cost center code applied to all users in this team `IT 5000`
`userIds`	array of string (uuid)	Existing user IDs to add to the team on creation

Responses

Status	Meaning	Body
`200`	Team created successfully. Returns the created team object including the auto-generated team ID.	`CreateTeamResponse`
`400`	Request failed schema validation, or was refused by a business rule	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to create teams	`ForbiddenError`
`404`	A user id in `userIds` is not in your organization	`NotFoundError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

Status	Problem	When
`404`	User not found	A request names a user that your organization does not have.

Response fields

200 CreateTeamResponse

Field	Type	Description
`id`required	string	UUID of the created team. `2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70`

POST/v1/teams

Request

curl -X POST "https://api.telgea.com/v1/teams" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Field Sales",
  "emoji": "🚀",
  "costCode": "IT 5000",
  "userIds": [
    "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01"
  ]
}'

Response

{
  "id": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70"
}

Update a team

PATCH/v1/teams/{teamId}

Enterprise API

Updates an existing team's information. All fields are optional - only provide the fields you want to update.

You can update basic information like name, emoji, and cost center code. Providing userIds replaces the team's full membership: users in the list are added, and users not in the list move to the default team, Unassigned.

The default team (isDefault: true in GET /v1/teams) cannot be updated.

Requires the permission teams:update on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`teamId`required	path	string (uuid)	UUID of the team. `2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70`
`idempotency-key`	header	string	A value unique to this request, of 1 to 255 printable ASCII characters — a UUID is the usual choice. Retry with the same key within 24 hours and you get the original response back, even if it was a failure, and nothing is done twice. Send a new key whenever you change the request. Keys are private to your API key and organisation. `0b7e4f1c-6a2d-4c9e-8f35-d1a7b2c93e60`

Request body

Field	Type	Description
`name`	string	Team name `Field Sales`
`emoji`	string	Emoji representing the team `🚀`
`costCode`	string	Cost center code applied to all users in this team `IT 5000`
`userIds`	array of string (uuid)	Full desired member list. When provided, replaces the team's membership: users not in the list are removed, new user IDs are added.

Responses

Status	Meaning	Body
`204`	Team updated successfully. No content returned.	none
`400`	Request failed schema validation, or was refused by a business rule	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to update teams	`ForbiddenError`
`404`	Team not found, or a user id in `userIds` is not in your organization	`NotFoundError`
`409`	This is your organization's default team, Unassigned, so it cannot be changed.	`ConflictError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

Status	Problem	When
`404`	User not found	A request names a user that your organization does not have.
`409`	Default team cannot be changed	A request renames or otherwise updates the default team, the team every user in no other team belongs to. GET /v1/teams marks it with `isDefault`.

PATCH/v1/teams/{teamId}

Request

curl -X PATCH "https://api.telgea.com/v1/teams/2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Field Sales EMEA",
  "emoji": "🌍",
  "costCode": "IT 5001",
  "userIds": [
    "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01"
  ]
}'

Response

{
  "type": "https://developer.telgea.com/errors/http/BAD_REQUEST",
  "title": "Bad request",
  "status": 400,
  "detail": "This request was refused, and no more specific code describes why.",
  "code": "BAD_REQUEST",
  "requestId": "req_123"
}

GET/v1/teams

Request

curl -X GET "https://api.telgea.com/v1/teams" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "page": 1,
  "pageSize": 50,
  "itemsCount": 3,
  "items": [
    {
      "id": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
      "name": "Field Sales",
      "emoji": "🚀",
      "costCode": "CC-4100",
      "memberCount": 12,
      "isDefault": false
    },
    {
      "id": "7c2e9f10-4b83-4d55-a0e6-1f8b3d6c2a94",
      "name": "Support",
      "emoji": null,
      "costCode": null,
      "memberCount": 4,
      "isDefault": false
    },
    {
      "id": "2b8d4e61-9c37-4f02-b5a8-6e1d0c7f3a59",
      "name": "Unassigned",
      "emoji": "▫️",
      "costCode": null,
      "memberCount": 7,
      "isDefault": true
    }
  ]
}

Need the raw schema? OpenAPI JSON