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

# Create User

This endpoint creates a user, but it also facilitates signing an existing
platform user up with the client brand in scenarios where the SSO flow wouldn't
be appropriate (i.e., the user is not signing in to an authenticated
experience).

If a user with the specified email already exists, it signs the user up with the
client brand before returning a 400 level error. This endpoint also returns
authorization information for a successfully created user, including an
access\_token that can be used to access other API endpoints. Experiences
utilizing this endpoint must adhere to the
[legal requirements for user creation](/consumer/usage/legal).

<Note>
  Please review proper request headers [here](/consumer/usage/headers).
</Note>

### Body

<ParamField body="email" type="string" required>
  The user's email
</ParamField>

<ParamField body="phone" type="string">
  The user's phone number in [E.164 format](https://www.twilio.com/docs/glossary/what-e164),
  with the country code prefix (e.g. `+14157582345`). Phones submitted
  without the country code prefix are stored as-is — this endpoint does
  not normalize them — and will fail later phone-based lookups (such as
  Partner Auth Token) that depend on E.164 parsing.
</ParamField>

<ParamField body="first_name" type="string" required>
  The user's first name
</ParamField>

<ParamField body="last_name" type="string" required>
  The user's last name
</ParamField>

<ParamField body="birth_date" type="hash">
  The user's birthday information

  <Expandable title="birth_date">
    <ParamField body="year" type="integer" deprecated="true">
      The user's birth year
    </ParamField>

    <ParamField body="month" type="integer">
      The user's birth month
    </ParamField>

    <ParamField body="day" type="integer">
      The user's birth day
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="zip_code" type="string">
  The user's zip code
</ParamField>

<ParamField body="signup_program_id" type="string">
  The Program ID to associate with this user signup. This is used to track which signup program the user enrolled through. The program must be active and belong to the merchant. If the program is invalid, it will be silently ignored without preventing user creation. Only applied to new users; existing users will not have their signup\_program\_id updated.
</ParamField>

<Note>
  This endpoint permits minimal requests that only contain an `email` parameter
  for the purposes of signing up an existing platform user with the client
  brand. If the email belongs to an existing user, it signs the user up with the
  brand before returning a 400 level error.
</Note>

<RequestExample>
  ```bash Create a new user theme={null}
  curl https://api.thanxsandbox.com/users/ \
    -X POST \
    -H "Content-Type: application/json"  \
    -H "Accept-Version: v4.0" \
    -H "Accept: application/json" \
    -H "X-ClientId: ${client_id}" \
    -d '{
      "user": {
        "email": "jane.smith@example.com",
        "phone": "+14158672345",
        "first_name": "Jane",
        "last_name":  "Smith",
        "birth_date": {
          "month": 8,
          "day": 14
        },
        "zip_code": "12345"
      }
    }'
  ```

  ```bash Create user with signup program theme={null}
  curl https://api.thanxsandbox.com/users/ \
    -X POST \
    -H "Content-Type: application/json"  \
    -H "Accept-Version: v4.0" \
    -H "Accept: application/json" \
    -H "X-ClientId: ${client_id}" \
    -d '{
      "user": {
        "email": "jane.smith@example.com",
        "phone": "+14158672345",
        "first_name": "Jane",
        "last_name":  "Smith",
        "birth_date": {
          "month": 8,
          "day": 14
        },
        "zip_code": "12345",
        "signup_program_id": "awe833ke24"
      }
    }'
  ```

  ```bash User does not existing theme={null}
  curl https://api.thanxsandbox.com/users/ \
    -X POST \
    $STANDARD_HEADERS \
    -d '{
      "user": {
        "email": "jane.smith@example.com"
      }
    }'
  ```

  ```bash Without SSO theme={null}
  curl https://api.thanxsandbox.com/users/ \
    -X POST \
    $STANDARD_HEADERS \
    -d '{
      "user": {
        "email": "jane.smith@example.com"
      }
    }'
  ```
</RequestExample>

### Response

<ResponseField name="user" type="User">
  The newly created user

  <Expandable title="User">
    <Snippet file="entities/user.mdx" />
  </Expandable>
</ResponseField>

<ResponseField name="authorization" type="Authorization">
  The authorization type of the created user

  <Expandable title="Authorization">
    <ResponseField name="token_type" type="string">
      The type of token, usually "Bearer"
    </ResponseField>

    <ResponseField name="scope" type="string">
      This will be 'passwordless'
    </ResponseField>

    <ResponseField name="created_at" type="integer">
      The number of seconds since the epoch
    </ResponseField>

    <ResponseField name="access_token" type="string">
      The user's access token, for use in accessing other API endpoints
    </ResponseField>

    <ResponseField name="refresh_token" type="string">
      If needed, a refresh token to get another access token
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "user": {
      "id": "wroeiu2304hfwf",
      "email": "jane.smith@example.com",
      "phone": "+14158672345",
      "first_name": "Jane",
      "last_name": "Smith",
      "birth_date": {
        "year": 1987,
        "month": 8,
        "day": 14
      },
      "zip_code": "12345"
    },
    "authorization": {
      "token_type": "Bearer",
      "scope": "passwordless",
      "created_at": 1577836800,
      "access_token": "945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd",
      "refresh_token": "c74334301a7c74d21b714c905fd3047177dab56de6a86899e6f6b7f71bab7d55"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "USER_NAME_REQUIRED",
      "message": "First and last name are required fields."
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "User account exists"
    }
  }
  ```
</ResponseExample>