---
title: "Create a new user"
method: POST
path: "/v1/users"
tags: ["Users"]
---

# Create a new user

`POST /v1/users`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/users`
- Auth: API key in header `x-api-key`

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.

## Headers

- `idempotency-key` 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.

## Request body

- CreateUserBody
  - `email` string, email, required: Email address of the new user. Unique within your organization.
  - `firstName` string, required: First name
  - `lastName` string, required: Last name
  - `teamId` string, uuid: Team to assign the user to. Omitted, the user joins the default team, Unassigned.
  - `costCode` string: Cost center code for billing purposes
  - `employeeId` string: External employee identifier

## Response `200`

User created successfully. Returns the created user object including the auto-generated user ID.

- CreateUserResponse
  - `id` string, required: UUID of the created user. Use it to provision a plan, submit a port-in, or update the user.
  - `email` string, email, required: Email address as stored.
  - `firstName` string, required: First name as stored.
  - `lastName` string, required: Last name as stored.

## Other responses

- `400`: Request failed schema validation, or was refused by a business rule
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to create users
- `404`: `teamId` names no team in your organization
- `409`: No user was created: another user already holds this email address.
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)