# 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"},"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":"object","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":"object","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":"object","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"]}}}}
```

## Create a single user

> Creates a new user.

```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"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":"object","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":"object","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":"object","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_create_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 email or phone. Updates fields: first\_name, last\_name, phone, external\_user\_id, status. Avatar is not affected.

```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"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":"object","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":"object","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":"object","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 email or phone. Updates fields: first_name, last_name, phone, external_user_id, status. Avatar is not affected.","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/PublicUserRequestDto"}}}},"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"]}}}}
```

## 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"},"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: 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:

```
GET https://docs.hesh.app/manuals/public-api/users.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.