Create a New Customer Account via POST /auth/register

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

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:

string

required

Given name. Between 1 and 100 characters.

string

required

Family name. Between 1 and 100 characters.

string

required

Mobile number in E.164 format, e.g. +14155552671. Must match ^\+[1-9]\d{1,14}$.

string

required

Valid email address. Must not already be registered — the API returns 409 if it is.

string

required

Minimum 8 characters. Must contain at least one uppercase letter, one lowercase letter, one digit, and one special character (e.g. !, @, #).

Example Request

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"
  }'

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();

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())

Success Response — `201 Created`

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

{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "email_verified": false
  }
}

boolean

Always true for successful responses.

object

Show data fields

string

Opaque public identifier for the newly created user account, prefixed usr_.

boolean

Always false immediately after registration. Becomes true after the user clicks the verification link.

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.

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

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

Example `409` Conflict

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "email already registered"
  }
}

Auth & Sessions

Account

Catalog

Cart & Checkout

Reviews

Create a New Customer Account via POST /auth/register

Endpoint

Request Body

Example Request

Success Response — `201 Created`

Error Responses

Example `400` Validation Error

Example `409` Conflict

Next Steps

Verify Your Email

Get a CSRF Token

​Endpoint

​Request Body

​Example Request

​Success Response — 201 Created

​Error Responses

​Example 400 Validation Error

​Example 409 Conflict

​Next Steps

Verify Your Email

Get a CSRF Token

Endpoint

Request Body

Example Request

Success Response — `201 Created`

Error Responses

Example `400` Validation Error

Example `409` Conflict

Next Steps