Users

The user object

Manage employees and contractors in your organization.

List users

Lists all users in your organization with pagination and optional filtering.

You can filter the results by exact email address or employee ID. Use pagination parameters to control the number of results returned per page.

Requires the permission users:read on the key.

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

Parameters

Responses

Problems this endpoint can return

This endpoint returns no domain-specific problems.

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

{
  "page": 1,
  "pageSize": 10,
  "itemsCount": 2,
  "items": [
    {
      "id": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
      "email": "[email protected]",
      "firstName": "Anna",
      "lastName": "Holm",
      "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
      "employeeId": "EMP-0142",
      "costCode": "CC-4100"
    },
    {
      "id": "3e5d1b42-7c90-4a18-b6f3-0d9e2a4c7f85",
      "email": "[email protected]",
      "firstName": "Jonas",
      "lastName": "Berg",
      "teamId": null,
      "employeeId": null,
      "costCode": null
    }
  ]
}

Create a new user

Creates a new user in your organization. Use this endpoint to onboard employees or contractors who need mobile numbers or telecommunications resources.

Once created, the user can be assigned to teams, associated with billing entities, and provisioned with SIM cards through the user-plans endpoint.

Requires the permission users:create on the key.

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

Parameters

Request body

Responses

Problems this endpoint can return

curl -X POST "https://api.telgea.com/v1/users" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "firstName": "Anna",
  "lastName": "Holm",
  "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
  "costCode": "CC-4100",
  "employeeId": "EMP-0142"
}'

{
  "id": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "email": "[email protected]",
  "firstName": "Anna",
  "lastName": "Holm"
}

Update a user

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

You can update basic information like name, as well as organizational assignments like team membership, cost center codes, and employee IDs.

Requires the permission users:update on the key.

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

Parameters

Request body

Responses

Problems this endpoint can return

curl -X PATCH "https://api.telgea.com/v1/users/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "firstName": "Anna",
  "lastName": "Holm-Jensen",
  "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
  "costCode": "CC-4100",
  "employeeId": "EMP-0142"
}'

{
  "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"
}

Delete a user

Permanently deletes a user from your organization.

Important Restrictions: - Cannot delete users with active phone numbers (must terminate user plan first) - Cannot delete admin users - Cannot delete yourself

Before deleting, ensure the user's local number is in SUSPENDED, DEACTIVATED state, or doesn't exist.

Requires the permission users:delete on the key.

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

Parameters

Responses

Problems this endpoint can return

curl -X DELETE "https://api.telgea.com/v1/users/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "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 a user's cost threshold and spend

Where a user stands against their cost threshold on one usage type: the threshold in force for them (their own, else their team's, else the organization's), their spend this month against it, and whether the usage is paused for crossing it.

The spend is converted into the threshold's currency at the day's exchange rate, so it is approximate; usage already under way may take it past the threshold before it ends.

Thresholds are set with PUT /v1/cost-thresholds. A usage type with no threshold support yet answers 422.

Scope: users:read.

Requires the permission users:read on the key.

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

Parameters

Responses

Problems this endpoint can return

curl -X GET "https://api.telgea.com/v1/users/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01/cost-thresholds/VOICE" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "threshold": {
    "id": "5d0b2c1e-7f3a-4b6c-9e8d-2a1f0c3b4d5e",
    "usageType": "VOICE",
    "scope": "team",
    "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
    "userId": null,
    "maxAmount": 50,
    "currency": "EUR",
    "period": "monthly",
    "validFrom": "2026-10-01T00:00:00.000Z",
    "validTo": null
  },
  "spend": {
    "amount": 12.4,
    "currency": "EUR",
    "periodStart": "2026-10-01T00:00:00.000Z"
  },
  "pausedUntil": null
}