> For the complete documentation index, see [llms.txt](https://docs.hesh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hesh.app/manuals/public-api/users.md).
# Users
## List 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\` — defaults \`page = 1\`, \`limit = 25\`, max \`limit = 100\`.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PublicUsersPageDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicUserListItemDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","meta"]},"PublicUserListItemDto":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string","description":"Convenience concatenation of `first_name` + \" \" + `last_name`."},"email":{"type":"string"}},"required":["id","first_name","last_name","full_name","email"]},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"number","description":"Total number of items"},"lastPage":{"type":"number","description":"Last page number"},"currentPage":{"type":"number","description":"Current page number"},"perPage":{"type":"number","description":"Items per page"},"prev":{"type":"number","description":"Previous page number","nullable":true},"next":{"type":"number","description":"Next page number","nullable":true}},"required":["total","lastPage","currentPage","perPage","prev","next"]}}},"paths":{"/api/v1/public/users":{"get":{"description":"\nReturns 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`.\n\n### Query\n\n- `search` — optional case-insensitive substring match on the concatenated full name (`CONCAT(first_name, ' ', last_name)`).\n- `page` / `limit` — defaults `page = 1`, `limit = 25`, max `limit = 100`.\n","operationId":"PublicUsersController_listUsers_v1","parameters":[{"name":"search","required":false,"in":"query","description":"Case-insensitive substring match on `first_name last_name`.","schema":{"maxLength":100,"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUsersPageDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"List users","tags":["Users"]}}}}
```
## Create a single user
> Creates a new user.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PublicUserRequestDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier for the user (e.g., UUID)"},"email":{"type":"string","format":"email","description":"The user's email address"},"first_name":{"type":"string","minLength":1,"maxLength":10,"description":"The user's first name"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"The user's last name"},"phone":{"type":"string","maxLength":50,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"],"default":"Active"}},"required":["external_user_id","email","first_name","last_name"]},"PublicUserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique internal identifier of the user"},"email":{"type":"string","format":"email","description":"The user's email address"},"avatar_id":{"type":"string","nullable":true,"description":"URL to the user's avatar image"},"first_name":{"type":"string","description":"The user's first name"},"last_name":{"type":"string","description":"The user's last name"},"external_user_id":{"type":"string","nullable":true,"description":"External identifier for the user assigned by third-party system"},"full_name":{"type":"string","description":"The user's full name (first name + last name)"},"phone":{"type":"string","nullable":true,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"]},"created_at":{"format":"date-time","type":"string","description":"Timestamp when the user was created"},"userVacations":{"type":"array","description":"User active vacation/day off periods","items":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time","description":"The start date of the vacation"},"end_at":{"type":"string","format":"date-time","description":"The end date of the vacation"}}}}},"required":["id","email","avatar_id","first_name","last_name","external_user_id","created_at"]}}},"paths":{"/api/v1/public/users":{"post":{"description":"Creates a new user.","operationId":"PublicUsersController_publicCreate_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserResponseDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Create a single user","tags":["Users"]}}}}
```
## Update a single user
> Updates an existing user matched by external\_user\_id. All fields except external\_user\_id are optional — only provided fields are updated.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"UpdatePublicUserRequestDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier for the user (used to match the user)"},"email":{"type":"string","format":"email","description":"The user's email address"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"The user's first name"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"The user's last name"},"phone":{"type":"string","maxLength":50,"description":"The user's phone number"}},"required":["external_user_id"]},"PublicUserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique internal identifier of the user"},"email":{"type":"string","format":"email","description":"The user's email address"},"avatar_id":{"type":"string","nullable":true,"description":"URL to the user's avatar image"},"first_name":{"type":"string","description":"The user's first name"},"last_name":{"type":"string","description":"The user's last name"},"external_user_id":{"type":"string","nullable":true,"description":"External identifier for the user assigned by third-party system"},"full_name":{"type":"string","description":"The user's full name (first name + last name)"},"phone":{"type":"string","nullable":true,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"]},"created_at":{"format":"date-time","type":"string","description":"Timestamp when the user was created"},"userVacations":{"type":"array","description":"User active vacation/day off periods","items":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time","description":"The start date of the vacation"},"end_at":{"type":"string","format":"date-time","description":"The end date of the vacation"}}}}},"required":["id","email","avatar_id","first_name","last_name","external_user_id","created_at"]}}},"paths":{"/api/v1/public/users":{"put":{"description":"Updates an existing user matched by external_user_id. All fields except external_user_id are optional — only provided fields are updated.","operationId":"PublicUsersController_updateUser_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePublicUserRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserResponseDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Update a single user","tags":["Users"]}}}}
```
## Create users in batch
> Creates multiple users in a single request. Skips users that already exist (matched by email or phone).
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"UsersExchangeDto":{"type":"object","properties":{"users":{"description":"An array containing user objects with the following fields: external_user_id, email, first_name, last_name, and phone","type":"array","items":{"type":"string"}}},"required":["users"]},"PublicUserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique internal identifier of the user"},"email":{"type":"string","format":"email","description":"The user's email address"},"avatar_id":{"type":"string","nullable":true,"description":"URL to the user's avatar image"},"first_name":{"type":"string","description":"The user's first name"},"last_name":{"type":"string","description":"The user's last name"},"external_user_id":{"type":"string","nullable":true,"description":"External identifier for the user assigned by third-party system"},"full_name":{"type":"string","description":"The user's full name (first name + last name)"},"phone":{"type":"string","nullable":true,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"]},"created_at":{"format":"date-time","type":"string","description":"Timestamp when the user was created"},"userVacations":{"type":"array","description":"User active vacation/day off periods","items":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time","description":"The start date of the vacation"},"end_at":{"type":"string","format":"date-time","description":"The end date of the vacation"}}}}},"required":["id","email","avatar_id","first_name","last_name","external_user_id","created_at"]}}},"paths":{"/api/v1/public/users/batch":{"post":{"description":"Creates multiple users in a single request. Skips users that already exist (matched by email or phone).","operationId":"PublicUsersController_createBatch_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersExchangeDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicUserResponseDto"}}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Create users in batch","tags":["Users"]}}}}
```
## Disable a user by external\_user\_id
> Sets the user status to Inactive.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DisableUserByExternalIdDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier of the user to disable"}},"required":["external_user_id"]},"MessageDto":{"type":"object","properties":{"message":{"type":"string","description":"Message returned from API confirming the operation"}},"required":["message"]}}},"paths":{"/api/v1/public/users/disable":{"patch":{"description":"Sets the user status to Inactive.","operationId":"PublicUsersController_disableUser_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisableUserByExternalIdDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Disable a user by external_user_id","tags":["Users"]}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.hesh.app/manuals/public-api/users.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.