Users
Returns active users in the tenant, paginated. Excludes hard-deleted and soft-deleted users. Each entry carries id, first_name, last_name, a convenience full_name (first_name + " " + last_name), and email.
Query
search— optional case-insensitive substring match on the concatenated full name (CONCAT(first_name, ' ', last_name)).page/limit— defaultspage = 1,limit = 25, maxlimit = 100.
Case-insensitive substring match on first_name last_name.
125Tenant id (uuid v4)
Returned when the rate limit is exceeded
GET /api/v1/public/users HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "text",
"first_name": "text",
"last_name": "text",
"full_name": "text",
"email": "text"
}
],
"meta": {
"total": 1,
"lastPage": 1,
"currentPage": 1,
"perPage": 1,
"prev": 1,
"next": 1
}
}Creates a new user.
Tenant id (uuid v4)
External identifier for the user (e.g., UUID)
550e8400-e29b-41d4-a716-446655440000The user's email address
example@gmail.comThe user's first name
VovaThe user's last name
SmithThe user's phone number
38000Current status of the user account
ActiveExample: ActivePossible values: Unique internal identifier of the user
550e8400-e29b-41d4-a716-446655440000The user's email address
example@gmail.comURL to the user's avatar image
https://example.com/avatar.jpgThe user's first name
VovaThe user's last name
SmithExternal identifier for the user assigned by third-party system
ext_user_123456The user's full name (first name + last name)
Vova SmithThe user's phone number
+1234567890Current status of the user account
ActivePossible values: Timestamp when the user was created
2024-09-02T21:00:00.000ZReturned when the rate limit is exceeded
POST /api/v1/public/users HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 161
{
"external_user_id": "550e8400-e29b-41d4-a716-446655440000",
"email": "example@gmail.com",
"first_name": "Vova",
"last_name": "Smith",
"phone": "38000",
"status": "Active"
}{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "example@gmail.com",
"avatar_id": "https://example.com/avatar.jpg",
"first_name": "Vova",
"last_name": "Smith",
"external_user_id": "ext_user_123456",
"full_name": "Vova Smith",
"phone": "+1234567890",
"status": "Active",
"created_at": "2024-09-02T21:00:00.000Z",
"userVacations": [
{
"start_at": "2026-01-01T00:00:00.000Z",
"end_at": "2026-01-01T00:00:00.000Z",
"type": "day_off"
}
]
}Updates an existing user matched by external_user_id. All fields except external_user_id are optional — only provided fields are updated.
Tenant id (uuid v4)
External identifier for the user (used to match the user)
550e8400-e29b-41d4-a716-446655440000The user's email address
example@gmail.comThe user's first name
VovaThe user's last name
SmithThe user's phone number
38000Unique internal identifier of the user
550e8400-e29b-41d4-a716-446655440000The user's email address
example@gmail.comURL to the user's avatar image
https://example.com/avatar.jpgThe user's first name
VovaThe user's last name
SmithExternal identifier for the user assigned by third-party system
ext_user_123456The user's full name (first name + last name)
Vova SmithThe user's phone number
+1234567890Current status of the user account
ActivePossible values: Timestamp when the user was created
2024-09-02T21:00:00.000ZReturned when the rate limit is exceeded
PUT /api/v1/public/users HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 143
{
"external_user_id": "550e8400-e29b-41d4-a716-446655440000",
"email": "example@gmail.com",
"first_name": "Vova",
"last_name": "Smith",
"phone": "38000"
}{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "example@gmail.com",
"avatar_id": "https://example.com/avatar.jpg",
"first_name": "Vova",
"last_name": "Smith",
"external_user_id": "ext_user_123456",
"full_name": "Vova Smith",
"phone": "+1234567890",
"status": "Active",
"created_at": "2024-09-02T21:00:00.000Z",
"userVacations": [
{
"start_at": "2026-01-01T00:00:00.000Z",
"end_at": "2026-01-01T00:00:00.000Z",
"type": "day_off"
}
]
}Creates multiple users in a single request. Skips users that already exist (matched by email or phone).
Tenant id (uuid v4)
An array containing user objects with the following fields: external_user_id, email, first_name, last_name, and phone
Unique internal identifier of the user
550e8400-e29b-41d4-a716-446655440000The user's email address
example@gmail.comURL to the user's avatar image
https://example.com/avatar.jpgThe user's first name
VovaThe user's last name
SmithExternal identifier for the user assigned by third-party system
ext_user_123456The user's full name (first name + last name)
Vova SmithThe user's phone number
+1234567890Current status of the user account
ActivePossible values: Timestamp when the user was created
2024-09-02T21:00:00.000ZReturned when the rate limit is exceeded
POST /api/v1/public/users/batch HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 18
{
"users": [
"text"
]
}[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "example@gmail.com",
"avatar_id": "https://example.com/avatar.jpg",
"first_name": "Vova",
"last_name": "Smith",
"external_user_id": "ext_user_123456",
"full_name": "Vova Smith",
"phone": "+1234567890",
"status": "Active",
"created_at": "2024-09-02T21:00:00.000Z",
"userVacations": [
{
"start_at": "2026-01-01T00:00:00.000Z",
"end_at": "2026-01-01T00:00:00.000Z",
"type": "day_off"
}
]
}
]Sets the user status to Inactive.
Tenant id (uuid v4)
External identifier of the user to disable
550e8400-e29b-41d4-a716-446655440000Message returned from API confirming the operation
The operation was done successfullyReturned when the rate limit is exceeded
PATCH /api/v1/public/users/disable HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 59
{
"external_user_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"message": "The operation was done successfully"
}Matches the user by external_user_id, then downloads the image at url and sets it as the user's avatar. Downloading happens asynchronously in the background — a 200 response means the update was scheduled, not that it has completed yet.
Tenant id (uuid v4)
External identifier of the user whose avatar is being set
550e8400-e29b-41d4-a716-446655440000Url of the avatar image to download
https://example.com/photos/user-avatar.jpgMessage returned from API confirming the operation
The operation was done successfullyReturned when the rate limit is exceeded
POST /api/v1/public/users/avatar HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 110
{
"external_user_id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/photos/user-avatar.jpg"
}{
"message": "The operation was done successfully"
}Matches the user by external_user_id and clears their avatar. Idempotent — if the user has no avatar set, this is a no-op. The underlying file is deleted from storage only if nothing else references it.
Tenant id (uuid v4)
External identifier of the user whose avatar is being removed
550e8400-e29b-41d4-a716-446655440000Message returned from API confirming the operation
The operation was done successfullyReturned when the rate limit is exceeded
DELETE /api/v1/public/users/avatar HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 59
{
"external_user_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"message": "The operation was done successfully"
}Takes a list of { external_user_id, avatar_url } rows (e.g. from a one-off import file) and, for each one, downloads the image and sets it as that user's avatar — synchronously, so the outcome of every row is in the response.
A row is skipped (never overwrites anything) when:
user_not_found— no user in Hesh has thisexternal_user_id.duplicate_external_user_id— more than one Hesh user has thisexternal_user_id;detailslists the matched internal user ids for manual review.user_inactive— the matched user's status is not Active.avatar_already_set— the user already has an avatar; existing avatars are never replaced.url_unreachable— the url could not be downloaded (unreachable, too large, or not an image);detailscarries the error.
Runs synchronously (not queued), so a large list will take proportionally longer to respond — keep batches reasonably sized (max 1000 rows per request).
Tenant id (uuid v4)
Number of input rows processed
Number of users whose avatar was actually updated
Returned when the rate limit is exceeded
POST /api/v1/public/users/avatars/sync HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 129
{
"items": [
{
"external_user_id": "550e8400-e29b-41d4-a716-446655440000",
"avatar_url": "https://example.com/photos/user-avatar.jpg"
}
]
}{
"total": 1,
"updated": 1,
"skipped": [
{
"external_user_id": "text",
"avatar_url": "text",
"reason": "user_not_found",
"details": "text"
}
]
}Last updated