---
title: "Add User"
method: POST
path: "/api/user"
tags: ["User"]
---

# Add User

`POST /api/user`

Add a new user

- **username**: 3 to 32 characters, can include a-z, 0-9, and underscores.
- **status**: User's status, defaults to `active`. Special rules if `on_hold`.
- **expire**: UTC timestamp for account expiration. Use `0` for unlimited.
- **data_limit**: Max data usage in bytes (e.g., `1073741824` for 1GB). `0` means unlimited.
- **data_limit_reset_strategy**: Defines how/if data limit resets. `no_reset` means it never resets.
- **proxies**: Dictionary of protocol settings (e.g., `vmess`, `vless`).
- **inbounds**: Dictionary of protocol tags to specify inbound connections.
- **note**: Optional text field for additional user information or notes.
- **on_hold_timeout**: UTC timestamp when `on_hold` status should start or end.
- **on_hold_expire_duration**: Duration (in seconds) for how long the user should stay in `on_hold` status.
- **next_plan**: Next user plan (resets after use).

## Request body

- UserCreate
  - `proxies` object
  - `expire` integer, nullable
  - `data_limit` integer, nullable — data_limit can be 0 or greater
  - `data_limit_reset_strategy` 'no_reset' | 'day' | 'week' | 'month' | 'year'
  - `inbounds` object
  - `note` string, nullable
  - `sub_updated_at` string, date-time, nullable
  - `sub_last_user_agent` string, nullable
  - `online_at` string, date-time, nullable
  - `on_hold_expire_duration` integer, nullable
  - `on_hold_timeout` string, date-time, nullable
  - `auto_delete_in_days` integer, nullable
  - `next_plan` NextPlanModel
    - `data_limit` integer, nullable
    - `expire` integer, nullable
    - `add_remaining_traffic` boolean
    - `fire_on_either` boolean
  - `username` string, required
  - `status` 'active' | 'on_hold'

## Response `200`

Successful Response

- UserResponse
  - `proxies` object, required
  - `expire` integer, nullable
  - `data_limit` integer, nullable — data_limit can be 0 or greater
  - `data_limit_reset_strategy` 'no_reset' | 'day' | 'week' | 'month' | 'year'
  - `inbounds` object
  - `note` string, nullable
  - `sub_updated_at` string, date-time, nullable
  - `sub_last_user_agent` string, nullable
  - `online_at` string, date-time, nullable
  - `on_hold_expire_duration` integer, nullable
  - `on_hold_timeout` string, date-time, nullable
  - `auto_delete_in_days` integer, nullable
  - `next_plan` NextPlanModel
    - `data_limit` integer, nullable
    - `expire` integer, nullable
    - `add_remaining_traffic` boolean
    - `fire_on_either` boolean
  - `username` string, required
  - `status` 'active' | 'disabled' | 'limited' | 'expired' | 'on_hold', required
  - `used_traffic` integer, required
  - `lifetime_used_traffic` integer
  - `created_at` string, date-time, required
  - `links` string[]
  - `subscription_url` string
  - `excluded_inbounds` object
  - `admin` Admin
    - `username` string, required
    - `is_sudo` boolean, required
    - `telegram_id` integer, nullable
    - `discord_webhook` string, nullable
    - `users_usage` integer, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `409` — Conflict
- `422` — Validation Error

---

[API](https://skmtc.dev/atrvatam/apis/marzbanapi.md) · [All operations](https://skmtc.dev/atrvatam/apis/marzbanapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/atrvatam/marzbanapi/revisions/0aa31d6bd001/schema)