User Registration

This document outlines the process for registering a new user. The registration involves validating credentials, checking username availability, and completing user setup.

User Credentials

Step 1: Validate User Credentials

To verify if the username already exists, send a POST request to the following endpoint:

POST /api/1/user/credentials/continue?locale={{locale}}

Request Payload

{
    "username": "<USERNAME>",
    "password": "<PASSWORD>"
}

Response Scenarios

A. Credentials are Invalid
If the provided username and password are invalid, the response will be:

{
    "completed": false,
    "continue": false
}

In this case, an additional request is required to check if the username is available.

Step 2: Check Username Availability

Send a POST request to the following endpoint:

POST /api/1/user/credentials/available?locale={{locale}}

Request Payload

{
    "username": "<USERNAME>"
}

Response

• If the username is available (not taken), the response will be:

{
    "available": true
}

• If the username is already in use, the response will be:

{
    "available": false
}

If the username is available, proceed to creating user credentials.

Step 3: Create User Credentials

To create new user credentials, send a POST request to:

POST /api/1/user/credentials?locale={{locale}}

Request Payload

{
    "username": "<USERNAME>",
    "password": "<PASSWORD>"
}

This will successfully create the user credentials.

The response would then contain the nonce needed to complete the registration process

{
    "user_id": "<USER_ID>",
    "new_user": true,
    "nonce": "<NONCE>"
}

Step 4: Handle Incomplete Registration

When the credentials is valid, and the user did not complete registration, the response would be as follows. Please take note of the nonce needed to complete the registration process

{
    "completed": false,
    "continue": true,   
    "nonce": "<NONCE>"
}

Determine Next Registration Step

Using the nonce from the response, determine the next registration step by sending a GET request to:

GET /api/1/user/complete-step?locale={{locale}}&auth_nonce=<NONCE>

Response

{
    "continue_from": <STEP_NUMBER>,
    "step": "<STEP_NAME>"
}

Supported Step Names

• user-credentials
• user-person
• user-optins
• customer-card

When the credentials is valid, and the user has completed registration, the response would be as follows and the user is required to proceed with logging-in Response

{
    "completed": true,
    "continue": false
}

User Person

All calls in this section require the client_access_token to be included in the request header.

Step 1: Retrieve Person Fields

To fetch the available person fields, send a GET request to the following endpoint:

GET /api/1/user/person/fields?locale={{locale}}

Response

A successful request returns a response containing the available fields and their properties:

{
    "general": {
        "firstName": {
            "name": "string",
            "validators": [...],
            "is_editable": true
        },
        "infix": {
            "name": "string",
            "validators": [...],
            "is_editable": true
        },
        "lastName": {
            "name": "string",
            "validators": [...],
            "is_editable": true
        },
        "gender": {
            "name": "select",
            "choices": [
                "f",
                "m"
            ],
            "default": null,
            "validators": [...],
            "is_editable": true
        }
    }
}

Step 2: Create User Person

Using the nonce obtained from the User Credentials step and the fields retrieved in the previous call, send a POST request to create a new user person:

POST /api/1/user/person?locale={{locale}}

Request Payload

{
    "auth_nonce": "<NONCE>",
    "firstName": "John",
    "infix": "J",
    "lastName": "Doe",
    "gender": "m"
}

Response

A successful request will return an HTTP 201 response confirming the creation of the user:

{
    "person": {
        "user_id": "<USER_ID>",
        "email": "<EMAIL>",
        "firstName": "John",
        "infix": "J",
        "lastName": "Doe",
        "gender": "m",
        "updated": "2025-03-12 00:00:00.000",
        "created": "2025-03-12 00:00:00.000"
    }
}

Step 3: Determine Next Registration Step

Once the user person is created, determine the next step by sending a GET request:

GET /api/1/user/complete-step?locale={{locale}}&auth_nonce=<NONCE>

This will guide the client on the next action required for user registration. This can require you to either setup customer card or optins before completing the user.

Completing the User

Every step on the User registration flow would need to call the endpoint

 GET /api/1/user/complete-step?locale=locale&auth_nonce=<NONCE>

to determine which step is lacking or incomplete. If all the steps have been completed, this endpoint would return a HTTP 204 Response with an empty body.

To complete the registration process a call to endpoint

 POST /api/1/user/complete?locale={{locale}}

using the nonce in the payload would initiate the activation process. This endpoint would return a HTTP 204 response Payload

{
    "auth_nonce":"<NONCE>"
}

Activating the account

An activation_nonce would be sent to the user’s email. This activation_nonce would be used to activate the user by calling the endpoint POST

 /api/1/user/activator/uniquelink?locale={{locale}}

with the payload

Payload

{
    "nonce": "<ACTIVATION_NONCE>"
}