Skip to main content
POST
/
api
/
v1
/
users
Register User
curl --request POST \
  --url https://api.example.com/api/v1/users \
  --header 'Content-Type: application/json' \
  --data '
{
  "username": "<string>",
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "role": {}
}
'
{
  "201": {},
  "400": {},
  "409": {},
  "500": {},
  "id": "<string>",
  "username": "<string>",
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "role": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "active": true
}

​
Endpoint

POST /api/v1/users
Registers a new user in the system. All fields are required and will be validated before the user is created.

​
Request Body

​
username
string
required
Unique username for the user. Must be between 3 and 50 characters.Validation:
  • Required
  • Min length: 3 characters
  • Max length: 50 characters
Example: jdoe
​
email
string
required
User’s email address. Must be a valid email format.Validation:
  • Required
  • Must be a valid email address
Example: jdoe@example.com
​
firstName
string
required
User’s first name.Validation:
  • Required
  • Max length: 100 characters
Example: John
​
lastName
string
required
User’s last name.Validation:
  • Required
  • Max length: 100 characters
Example: Doe
​
role
enum
required
User’s role in the system.Validation:
  • Required
  • Must be one of: ADMIN, USER, GUEST
Example: USER

​
Response

​
id
UUID
Unique identifier for the user, automatically generated.Example: 0f4df2de-fffb-4a24-9891-381ecf4f0f87
​
username
string
The user’s username.Example: jdoe
​
email
string
The user’s email address.Example: jdoe@example.com
​
firstName
string
The user’s first name.Example: John
​
lastName
string
The user’s last name.Example: Doe
​
role
string
The user’s role.Example: USER
​
createdAt
string
ISO 8601 timestamp when the user was created.Example: 2024-01-15T10:30:00
​
updatedAt
string
ISO 8601 timestamp when the user was last updated.Example: 2024-01-15T10:30:00
​
active
boolean
Whether the user account is active. New users are active by default.Example: true

​
Status Codes

​
201
Created
User created successfully
​
400
Bad Request
Validation error - one or more required fields are missing or invalid
​
409
Conflict
User with the provided username already exists
​
500
Internal Server Error
An unexpected error occurred

​
Example Request

curl -X POST http://localhost:8080/api/v1/users \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "jdoe",
    "email": "jdoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "USER"
  }'

​
Example Response

{
  "id": "0f4df2de-fffb-4a24-9891-381ecf4f0f87",
  "username": "jdoe",
  "email": "jdoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "USER",
  "createdAt": "2024-01-15T10:30:00",
  "updatedAt": "2024-01-15T10:30:00",
  "active": true
}

​
Error Response Examples

​
Validation Error (400)

{
  "type": "about:blank",
  "title": "Validation Failed",
  "status": 400,
  "detail": "username: username is required; email: email must be a valid email address",
  "timestamp": "2024-01-15T10:30:00"
}

​
User Already Exists (409)

{
  "type": "about:blank",
  "title": "User Already Exists",
  "status": 409,
  "detail": "User with username 'jdoe' already exists",
  "timestamp": "2024-01-15T10:30:00"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us