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

# Step 1: Create Youth Account

> Provision a youth account and custodial wallet in the YoID system.

## Overview

The first step in the issuance workflow is creating a youth account. This provisions an identity in the **Consumers** realm and initialises a wallet tenant — giving the youth a place to receive and store credentials.

## 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": "[email protected]",
    "firstName": "Thandi",
    "lastName": "Molefe"
  }'
```

### Request Body

| Field                | Type   | Required | Description                             |
| -------------------- | ------ | -------- | --------------------------------------- |
| `email`              | string | No\*     | Youth's email address                   |
| `username`           | string | No\*     | Username (alphanumeric, `.`, `-`, `_`)  |
| `firstName`          | string | No       | Youth's first name                      |
| `lastName`           | string | No       | Youth's last name                       |
| `externalIdentifier` | string | No       | Your system's identifier for this youth |

<Warning>
  \*At least one of `email` or `username` must be provided. Behaviour varies depending on the combination — see the API Reference for full details.
</Warning>

## Response

The response differs depending on whether the youth is new or already exists.

### New User — HTTP 201 Created

```json theme={null}
{
  "data": {
    "email": "[email protected]",
    "username": "thandi.molefe",
    "tempPassword": "!w&3WgYeEGMv"
  }
}
```

| Field          | Description                        |
| -------------- | ---------------------------------- |
| `email`        | The youth's email address          |
| `username`     | The assigned username              |
| `tempPassword` | A temporary password for the youth |

### Existing User — HTTP 201 Created

If the youth already has an account, the API still returns `201` but with an **empty `tempPassword`**. This is not an error — proceed directly to credential issuance.

```json theme={null}
{
  "data": {
    "email": "[email protected]",
    "username": "thandi.molefe",
    "tempPassword": ""
  }
}
```

<Warning>
  The only way to detect an existing account is to check whether `tempPassword` is empty. If empty, skip sending onboarding emails.
</Warning>

## Idempotency

This endpoint is idempotent for the same email — it won't create duplicate accounts. It returns `201` in both new and existing cases.

A `409 Conflict` is returned if the username is already taken by a different email, or there's a mismatch between the provided email and username.

<Tip>
  Proceed to [Step 2: Create Credential Template](/api/issuers/create-credential-template) to define the structure of the credential you want to issue.
</Tip>