# Create user

`POST https://api.agilitycredit.net/scim/v2/{tenantId}/Users`

Docs page: https://apidocs.agilitycredit.com/sso/scim-api/create-user · Tag: Users

Provision a new user. `userName` must be the user's work email and is **immutable**
once set. Returns:

- `201 Created` — new user provisioned.
- `200 OK` — user already existed (or had been deactivated) and was adopted or
  reactivated by SCIM. Treat both as success; retries are idempotent.

Authentication: `Authorization: Bearer <api key>`.

## Request body (`application/scim+json`), required

Schema: `User`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemas` | array of string | yes |  |
| `id` | string |  | Server-assigned UUID. Use it for all subsequent operations. |
| `externalId` | string |  | Client-assigned correlation ID. Stored verbatim. |
| `userName` | string (email) | yes | The user's work email. **Immutable** after creation — attempts to change it via PUT/PATCH are silently ignored. |
| `name` | object | yes |  |
| `name.givenName` | string | yes |  |
| `name.familyName` | string | yes |  |
| `name.formatted` | string |  | Computed by the server. |
| `emails` | array of object |  | Primary work email. The `value` must match `userName` and is immutable. |
| `emails[].value` | string (email) | yes |  |
| `emails[].type` | string: `work` |  |  |
| `emails[].primary` | boolean |  |  |
| `phoneNumbers` | array of object |  | Phone numbers. `value` must be E.164 (e.g. `+14155550100`). |
| `phoneNumbers[].value` | string | yes | E.164 phone number, e.g. `+14155550100`. |
| `phoneNumbers[].type` | string: `work`, `mobile` |  |  |
| `phoneNumbers[].primary` | boolean |  |  |
| `roles` | array of string: `admin`, `user`, `sales`, `sales_with_credit`, `api`, `accounting` |  | Roles assigned to the user. Only honoured when the tenant's role mapping source is `idp_attribute`. The attribute name is tenant-configurable; `roles` is the default. |
| `active` | boolean | yes | `false` deactivates (soft-delete); `true` reactivates a previously deactivated user. |
| `meta` | object |  |  |
| `meta.resourceType` | string: `User`, `Group`, `Schema`, `ServiceProviderConfig` |  |  |
| `meta.created` | string (date-time) |  |  |
| `meta.lastModified` | string (date-time) |  |  |
| `meta.location` | string |  |  |

Example:

```json
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "jane@acme.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "jane@acme.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+14155550100",
      "type": "work"
    }
  ],
  "roles": [
    "admin"
  ],
  "active": true,
  "externalId": "acme-hr-1234"
}
```

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | User already existed and was adopted or reactivated. | User |
| 201 | User created. | User |
| 400 | Payload validation failed. | Error |
| 503 | SCIM provisioning is disabled on the tenant. | Error |

### Error bodies

400:

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "userName or emails[0].value is required"
}
```

503:

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "503",
  "detail": "SCIM provisioning is disabled for this tenant"
}
```