# Creating users

{% hint style="danger" %}
**`POST /users` requests are limited to a raw JSON payload size of 3 MB.**
{% endhint %}

## Endpoint

<mark style="color:blue;">`POST`</mark> `https://api.signitic.app/users`

## Headers

| Name                                        | Type   | Description  |
| ------------------------------------------- | ------ | ------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | Your API key |

`POST /users` creates new users and also updates existing users matched by email. The limit applies to the raw request body size, not to a fixed number of users.

## Request body

### Example

```json
{
  "users": [
    {
      "email": "user1@signitic.fr",
      "enabled": true,
      "path": {
        "group": "Marketing Direction",
        "parent_entity": "Company",
        "entity": "Paris Office"
      },
      "firstname": "Johanna",
      "lastname": "Doe",
      "phone": "+33 1 34 33 22 33",
      "mobile": "+33 6 34 33 22 33",
      "department": "Marketing",
      "jobtitle": "CEO",
      "formula": "Kind regards,<br/>John",
      "vcard_user": true,
      "calendar_link": "calendar.com",
      "github_link": "github.com",
      "linkedin_link": "linkedin.com",
      "whatsapp_link": "whatsapp.com",
      "facebook_link": "facebook.com",
      "instagram_link": "instagram.com",
      "twitter_link": "twitter.com",
      "xing_link": "xing.com",
      "messenger_link": "messenger.com",
      "threads_link": "threads.net",
      "strava_link": "strava.com",
      "address": "1600 Pennsylvania Avenue NW<br/>Washington, DC 20500,<br/>USA",
      "postal_code": "75008",
      "city": "Paris",
      "extra_1": "extra field 1",
      "extra_2": "extra field 2",
      "extra_10": "extra field 10",
      "extra_20": "extra field 20"
    }
  ]
}
```

### Path dispatch

`path` is resolved from top to bottom: `parent_entity` (or legacy `parent`), then `entity`, then `group`. Empty strings are ignored. Signitic reuses the deepest existing matching branch in the group tree and creates only the missing groups. If no part of the path exists, the full branch is created from the workspace root. The user is then assigned to the lowest group in the resolved path. Groups created this way are blank new groups, not copies of existing ones. Skipping a level is allowed, but not recommended because it makes dispatch harder to understand and debug.

Because dispatch is path-based, different segment combinations can resolve to the same final group.

### Notes

* `extra_1` to `extra_20` are supported.
* Social fields such as `xing_link`, `messenger_link`, `threads_link`, `strava_link`, and `bluesky_link` are accepted in the payload.

## Success response

### `200 OK`

```json
{
  "success": true,
  "code": 200,
  "value": {
    "added": 1,
    "edited": 0
  }
}
```

## Error responses

| Status | Internal code | When                                |
| ------ | ------------- | ----------------------------------- |
| 400    | `103`         | The request body is not valid JSON. |
| 401    | `99`          | The API key is missing or invalid.  |
| 422    | `104`         | The raw JSON payload exceeds 3 MB.  |