> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Create user account

> Onboard a user, creating their account and custodial wallet, so they can hold credentials you issue.

## Overview

Before you can issue a credential to someone, they need an account in your organisation. Onboarding creates two things at once: an identity record and the custodial wallet attached to it. After this step the user can sign in, accept credential offers, and respond to presentation requests.

You do this once per user, the first time you onboard them.

## Endpoint

```
POST https://test.didxtech.com/consumer-onboarding/api/users
```

## Request

```bash theme={null}
curl -X POST "https://test.didxtech.com/consumer-onboarding/api/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "johndoe",
    "firstName": "John",
    "lastName": "Doe",
    "externalIdentifier": "PARTNER-ID-12345"
  }'
```

### Request body

You must supply **at least one of `email` or `username`**. The rest are optional.

#### `email` *(optional)*

The user's email address. If supplied, it's used for password-recovery flows and as the default sign-in identifier.

#### `username` *(optional)*

A handle for the user. May contain only alphanumeric characters, dots, underscores, or hyphens. Useful when the user doesn't have (or doesn't want to share) an email, or when you want stable, human-readable identifiers in your own system.

If you omit `username`, the platform derives one from the email.

#### `firstName`, `lastName` *(optional)*

The user's name as you'd like it shown in their wallet and in consent dialogs. Update later if you need to.

#### `externalIdentifier` *(optional)*

Your own id for the user (CRM id, partner reference number, or anything stable on your side). Stored against the account so you can look the user up by it later (see [Lookup and IdP linking](#lookup-and-idp-linking)). Doesn't have to be unique across organisations, but should be unique within yours.

## Response

**HTTP 201 Created**

```json theme={null}
{
  "email": "user@example.com",
  "username": "johndoe",
  "tempPassword": "!w&3WgYeEGMv"
}
```

| Field          | Notes                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `email`        | Echoed back if you supplied one.                                                                                                                                                           |
| `username`     | The username on the account, either what you supplied or one derived from the email.                                                                                                       |
| `tempPassword` | A one-time password the user will need on first sign-in. **Always present.** Communicate it to the user out-of-band (e.g. email it yourself) and require them to change it on first login. |

## Error responses

| Status | When you'll see it                                                                                                                              |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Validation failed: neither `email` nor `username` was supplied, the email format is invalid, or the username doesn't match the allowed pattern. |
| `401`  | Missing or invalid bearer token.                                                                                                                |
| `409`  | Conflict: the username is taken by another organisation, or the supplied email and username belong to different existing users.                 |

## What happens next

* The user receives the `tempPassword`. You're responsible for getting it to them, typically via email.
* On first sign-in they're required to change it.
* Any credentials you issue to them appear as pending offers in their wallet, awaiting their acceptance.

## Lookup and IdP linking

Related endpoints on the same `consumer-onboarding` API:

* `GET /users`. List users in your organisation.
* `GET /users/by-external-identifier/{externalIdentifier}`. Find a user by the `externalIdentifier` you supplied at onboarding.
* `GET /users/{username}/external-identifier`. Read the external identifier stored against an existing user.
* `PATCH /users/{username}/idp-link`. Link the account to an external identity provider.

Full schemas live in the [Consumer Onboarding API reference](/products/didx-me/api-reference/v1/consumer-onboarding).