---
title: "Register User"
method: POST
path: "/auth/register"
tags: ["auth"]
---

# Register User

`POST /auth/register`

Register the authenticated user in our system.

This endpoint should be called by the frontend after Supabase authentication
to create the user record in our Users service. It uses the Supabase user ID
(from JWT 'sub' claim) as the primary key.

Safe to call multiple times. If user already exists, returns 200 OK.
The response includes the frontend's next routing step:
- next_step="email" for phone-only users who must collect a primary email
- next_step="app" for complete users

Requires authentication via Bearer token (Supabase JWT).

## Request body

- RegisterUserRequest — Request body for authenticated user registration.
  - `tracking` RegistrationTrackingData — Tracking data sent FROM THE FRONTEND during registration.
    - `meta` MetaTrackingData — Meta-specific tracking data sent from the frontend.
      - `fbp` string, nullable
      - `fbc` string, nullable
      - `event_id` string, nullable
    - `attribution` AttributionData — First, latest, and separately preserved latest paid attribution.
      - `first_touch` AttributionTouch — A single captured attribution touch.
        - `attribution_version` integer
        - `captured_at` string, date-time, nullable
        - `landing_path` string, nullable
        - `referrer_path` string, nullable
        - `capture_state` 'observed_no_referrer', nullable
        - `utm_source` string, nullable
        - `utm_medium` string, nullable
        - `utm_campaign` string, nullable
        - `utm_content` string, nullable
        - `utm_term` string, nullable
        - `utm_id` string, nullable
        - `utm_adgroup` string, nullable
        - `utm_asset_group` string, nullable
        - `utm_creative` string, nullable
        - `utm_content_id` string, nullable
        - `utm_placement` string, nullable
        - `fbclid` string, nullable
        - `twclid` string, nullable
        - `gclid` string, nullable
        - `gbraid` string, nullable
        - `wbraid` string, nullable
        - `partnership_code` string, nullable
        - `transaction_id` string, nullable
        - `creative_id` string, nullable
      - `last_touch` AttributionTouch — A single captured attribution touch.
        - `attribution_version` integer
        - `captured_at` string, date-time, nullable
        - `landing_path` string, nullable
        - `referrer_path` string, nullable
        - `capture_state` 'observed_no_referrer', nullable
        - `utm_source` string, nullable
        - `utm_medium` string, nullable
        - `utm_campaign` string, nullable
        - `utm_content` string, nullable
        - `utm_term` string, nullable
        - `utm_id` string, nullable
        - `utm_adgroup` string, nullable
        - `utm_asset_group` string, nullable
        - `utm_creative` string, nullable
        - `utm_content_id` string, nullable
        - `utm_placement` string, nullable
        - `fbclid` string, nullable
        - `twclid` string, nullable
        - `gclid` string, nullable
        - `gbraid` string, nullable
        - `wbraid` string, nullable
        - `partnership_code` string, nullable
        - `transaction_id` string, nullable
        - `creative_id` string, nullable
      - `last_paid_touch` AttributionTouch — A single captured attribution touch.
        - `attribution_version` integer
        - `captured_at` string, date-time, nullable
        - `landing_path` string, nullable
        - `referrer_path` string, nullable
        - `capture_state` 'observed_no_referrer', nullable
        - `utm_source` string, nullable
        - `utm_medium` string, nullable
        - `utm_campaign` string, nullable
        - `utm_content` string, nullable
        - `utm_term` string, nullable
        - `utm_id` string, nullable
        - `utm_adgroup` string, nullable
        - `utm_asset_group` string, nullable
        - `utm_creative` string, nullable
        - `utm_content_id` string, nullable
        - `utm_placement` string, nullable
        - `fbclid` string, nullable
        - `twclid` string, nullable
        - `gclid` string, nullable
        - `gbraid` string, nullable
        - `wbraid` string, nullable
        - `partnership_code` string, nullable
        - `transaction_id` string, nullable
        - `creative_id` string, nullable
    - `event_source_url` string, nullable
  - `promo_code` string, nullable
  - `referral_code` string, nullable
  - `sms_opted_in` boolean
  - `timezone` string, nullable

## Response `201`

Successful Response

- RegisterUserResponse — Response after idempotent registration/session completion.
  - `id` string, uuid, required
  - `status` string, required
  - `account_state` 'pending_email' | 'complete', required
  - `next_step` 'email' | 'app', required
  - `is_new_user` boolean, required
  - `forwarding_slug` string, required
  - `reply_slug` string, nullable
  - `created_at` string, date-time, required

## Other responses

- `422` — Validation Error

## Changes

> 15 revisions in range; 1 not diffed.

- **2026-09-16** `ca05fbc4893d` — 21 info
  - added the new optional request property `anyOf[subschema #1: RegisterUserRequest]/tracking/anyOf[subschema #1: RegistrationTrackingData]/attribution/anyOf[subschema #1: AttributionData]/first_touch/anyOf[subschema #1: AttributionTouch]/capture_state`
  - added the new optional request property `anyOf[subschema #1: RegisterUserRequest]/tracking/anyOf[subschema #1: RegistrationTrackingData]/attribution/anyOf[subschema #1: AttributionData]/first_touch/anyOf[subschema #1: AttributionTouch]/utm_adgroup`
  - added the new optional request property `anyOf[subschema #1: RegisterUserRequest]/tracking/anyOf[subschema #1: RegistrationTrackingData]/attribution/anyOf[subschema #1: AttributionData]/first_touch/anyOf[subschema #1: AttributionTouch]/utm_asset_group`
  - added the new optional request property `anyOf[subschema #1: RegisterUserRequest]/tracking/anyOf[subschema #1: RegistrationTrackingData]/attribution/anyOf[subschema #1: AttributionData]/first_touch/anyOf[subschema #1: AttributionTouch]/utm_content_id`
  - …17 more
- **2026-09-10** `09ac75a22f0e` — 1 info
  - added the new optional request property `anyOf[subschema #1: RegisterUserRequest]/tracking/anyOf[subschema #1: RegistrationTrackingData]/attribution/anyOf[subschema #1: AttributionData]/last_paid_touch`

[Change history](https://skmtc.dev/helloaxel/apis/client-api-gateway/changes/auth/register/post.md)

---

[API](https://skmtc.dev/helloaxel/apis/client-api-gateway.md) · [All operations](https://skmtc.dev/helloaxel/apis/client-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/helloaxel/apis/client-api-gateway/revisions/e5f778e80f9a?raw)