Skip to main content

Registration — full walkthrough

There are two ways to create a consumer account. Which one applies is decided by your touchpoint's configuration (email/phone verification policy) — not something you choose per request. Both end with the same result: a customerId and a Customer JWT.

A · Instant registration​

The fastest path — no proof of contact details. The account is created immediately; email/phone are stored unverified (the consumer can verify them later, see Verifications).

Enabled when both Email and Phone verification are OFF on the touchpoint.

TP=(-H "X-Touchpoint-Code: <code>" -H "X-Touchpoint-Key: <key>" -H "Content-Type: application/json")

curl -sX POST "$BASE/api/v1/register" "${TP[@]}" -d '{
  "type": "PERSON",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "country": "AR",
  "password": "Secret123!"
}'
# → 201 { "customerId": "...", "token": "<Customer JWT>" }

If the touchpoint actually requires a verified channel, this call is rejected instead:

// 409
{ "code": "VERIFICATION_REQUIRED", "error": "...", "channel": "EMAIL" }

— switch to the verified flow below.

B · Verified registration​

The consumer proves an email or phone before the account exists. Three calls:

Enabled when the channel to prove (Email or Phone) is REQUIRED_BEFORE_REGISTRATION.

1. Start — send the one-time code​

curl -sX POST "$BASE/api/v1/register/start" "${TP[@]}" -d '{
  "channel": "EMAIL",
  "destination": "ada@example.com"
}'
# → 200 { "registrationToken": "..." }

2. Verify — confirm the code​

curl -sX POST "$BASE/api/v1/register/verify" "${TP[@]}" -d '{
  "registrationToken": "<token from step 1>",
  "channel": "EMAIL",
  "code": "123456"
}'
# → 200

A wrong code returns 400 INVALID_OTP with an attemptsLeft field — show the consumer how many tries remain. A bogus or expired token returns 400 INVALID_REGISTRATION_TOKEN.

3. Complete — create the account​

curl -sX POST "$BASE/api/v1/register/complete" "${TP[@]}" -d '{
  "registrationToken": "<same token>",
  "type": "PERSON",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "country": "AR",
  "password": "Secret123!"
}'
# → 201 { "customerId": "...", "token": "<Customer JWT>" }

Skipping straight to complete before verifying — or verifying a different channel than the one the touchpoint requires — is rejected the same way as instant registration: 409 VERIFICATION_REQUIRED with a channel field. A registration token can only be used once; reusing a consumed token returns 400 INVALID_REGISTRATION_TOKEN.

Known limit

A touchpoint that marks both Email and Phone as REQUIRED_BEFORE_REGISTRATION can't be satisfied by this single-channel session flow today.

PERSON vs COMPANY​

type determines which profile fields apply — firstName/lastName for PERSON, companyName for COMPANY. Sending the wrong shape for the type returns 400 VALIDATION_ERROR.

Duplicate accounts​

Registering with an email/cellphone that already belongs to another customer on this business returns 409 DUPLICATE_CUSTOMER with a field telling you which value collided.

Verifying a channel after registration​

An instant-registration consumer with an unverified email/phone can verify it later, once logged in — see Login & profile.