# Add user

<mark style="color:blue;">`POST`</mark> `/users`

### **Overview**

Stores a **new user’s information** in the database.

This operation is commonly performed immediately after user **creation or authentication**, allowing the system to accurately track and manage users.

**Typical use cases**

* Saving a **newly registered user**
* Ensuring **user consistency** across services

### Header

| Name                               | Value              |
| ---------------------------------- | ------------------ |
| Content-Type                       | `application/json` |
| Authorization <sup>(API Key)</sup> | `Bearer <API Key>` |

### Body

<table><thead><tr><th width="237">Name</th><th width="159">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>email</code> </td><td>string</td><td>Email of the user</td></tr><tr><td><code>userId</code> <sub>(optinal)</sub></td><td>string</td><td>User identifier (user_id). <br>Optional on create — if not provided, a system-generated ID will be used<br><br><a href="user/user_id-and-klaim_id" class="button secondary">More description</a></td></tr><tr><td><code>name</code> <sub>(optinal)</sub></td><td>string</td><td>Name of the user</td></tr><tr><td><code>metadata</code> <sub>(optinal)</sub></td><td>object</td><td><p>A set of <strong>custom key-value pairs</strong> to be stored in the user’s profile.</p><p><br><a href="user/metadata" class="button secondary">More description</a></p></td></tr></tbody></table>

### Response

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "resource created successfully",
    "user_id": "testUserId",
    "klaim_id": "1753306133860_A36dL",
    "email": "test@email.com",
    "credit_balance": 0,
    "created_at": 1753306133860,
    "name": "Test API",
    "metadata": {
        "test": "field"
    }
}
```

{% endtab %}

{% tab title="400" %}
If the required email field is missing from the request body, an error will occur.

```
{
    "message": "missing required fields"
}
```

{% endtab %}

{% tab title="409" %}
A conflict error occurs when a user with the same email or user\_id already exists in the app.

{% code title="Email Already Exists" %}

```
{
    "message": "Email already exists"
}
```

{% endcode %}

{% code title="UserID Already Exists" %}

```
{
    "message": "User ID already exists"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}