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

# Create a New Customer Account via POST /auth/register

> Create a new customer account with email, password, and phone number. Returns a session cookie and queues an email verification message.

Registering creates a new customer account, authenticates you immediately by setting a session cookie, and queues a 24-hour email verification message to the address you provide. After a successful registration you are logged in — no separate login call is needed.

## Endpoint

```http theme={null}
POST https://api.example.com/api/v1/auth/register
```

This endpoint is **public** — no existing session or CSRF token is required.

## Request Body

Send a JSON body with the following fields:

<ParamField body="first_name" type="string" required>
  Given name. Between 1 and 100 characters.
</ParamField>

<ParamField body="last_name" type="string" required>
  Family name. Between 1 and 100 characters.
</ParamField>

<ParamField body="phone_number" type="string" required>
  Mobile number in [E.164 format](https://en.wikipedia.org/wiki/E.164), e.g. `+14155552671`. Must match `^\+[1-9]\d{1,14}$`.
</ParamField>

<ParamField body="email" type="string" required>
  Valid email address. Must not already be registered — the API returns `409` if it is.
</ParamField>

<ParamField body="password" type="string" required>
  Minimum 8 characters. Must contain at least one uppercase letter, one lowercase letter, one digit, and one special character (e.g. `!`, `@`, `#`).
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -i -X POST https://api.example.com/api/v1/auth/register \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number": "+14155552671",
      "email": "jane@example.com",
      "password": "S3cure!Pass"
    }'
  ```

  ```js JavaScript (fetch) theme={null}
  const response = await fetch(
    "https://api.example.com/api/v1/auth/register",
    {
      method: "POST",
      credentials: "include",          // required for the session cookie
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        first_name: "Jane",
        last_name: "Doe",
        phone_number: "+14155552671",
        email: "jane@example.com",
        password: "S3cure!Pass",
      }),
    }
  );
  const data = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  resp = requests.post(
      "https://api.example.com/api/v1/auth/register",
      json={
          "first_name": "Jane",
          "last_name": "Doe",
          "phone_number": "+14155552671",
          "email": "jane@example.com",
          "password": "S3cure!Pass",
      },
  )
  print(resp.json())
  ```
</CodeGroup>

## Success Response — `201 Created`

The account is created, the session cookie is set on the response, and a verification email is queued.

```json theme={null}
{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "email_verified": false
  }
}
```

<ResponseField name="success" type="boolean">
  Always `true` for successful responses.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data fields">
    <ResponseField name="public_id" type="string">
      Opaque public identifier for the newly created user account, prefixed `usr_`.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Always `false` immediately after registration. Becomes `true` after the user clicks the verification link.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The session is delivered as an **HttpOnly** cookie named `session` (SameSite=Lax). Because it is HttpOnly, your JavaScript code cannot read the cookie value directly — the browser attaches it automatically to every subsequent same-origin request. Store the `public_id` in your app state if you need to identify the user client-side.
</Note>

## Error Responses

| Status                  | Meaning                  | When it occurs                                                                                                                      |
| ----------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`       | Validation failed        | A required field is missing, `phone_number` is not valid E.164, `email` is malformed, or `password` does not meet complexity rules. |
| `409 Conflict`          | Email already registered | An account with that email address already exists. Prompt the user to log in or reset their password instead.                       |
| `429 Too Many Requests` | Rate limited             | Too many registration attempts from this IP in a short window. Wait before retrying.                                                |

### Example `400` Validation Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "password must include uppercase, lowercase, number and special character"
  }
}
```

### Example `409` Conflict

```json theme={null}
{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "email already registered"
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Verify Your Email" icon="envelope-circle-check" href="/api-reference/auth/email-verification">
    Confirm your email address using the token sent to your inbox.
  </Card>

  <Card title="Get a CSRF Token" icon="shield-halved" href="/authentication">
    Fetch a CSRF token before making any state-changing requests.
  </Card>
</CardGroup>