Create User
###########

Creates a new user account with associated locations.

.. code-block:: none
    :caption: Service Endpoint

    POST https://api.groupvan.com/internal/users/create


Request
-------

Parameters
~~~~~~~~~~

``username`` :bdg:`string` :bdg-danger:`required`
    Unique username for the new account

``first_name`` :bdg:`string` :bdg-danger:`required`
    User's first name

``last_name`` :bdg:`string` :bdg-danger:`required`
    User's last name

``email`` :bdg:`string` :bdg-danger:`required`
    User's email address. Must be a valid email format and not already in use.

``address`` :bdg:`string` :bdg-danger:`required`
    Street address. Must be a valid address (validated via Google).

``city`` :bdg:`string` :bdg-danger:`required`
    City

``state`` :bdg:`string` :bdg-danger:`required`
    State

``zip`` :bdg:`string` :bdg-danger:`required`
    Zip code

``employee_id`` :bdg:`string` :bdg-danger:`required`
    Employee ID

``catalog_region_id`` :bdg:`string` :bdg-danger:`required`
    Catalog region ID. Must be a valid region. See :doc:`catalog_regions` for available regions.

``account_id`` :bdg:`string` :bdg-danger:`required`
    Account ID

``phone_number`` :bdg:`string`
    Phone number. Must match the pattern ``+?1?\d{10}`` if provided. Defaults to empty string.

``company_name`` :bdg:`string`
    Company name. Defaults to empty string.

``terminal_pin`` :bdg:`string`
    Terminal PIN. Defaults to null.

``locations`` :bdg:`array` :bdg-danger:`required`
    Array of locations to assign to the user. Must contain at least one location with ``sort_order: 1``
    and ``can_order: true``. All ``sort_order`` values must be unique and greater than 0.

    ``id`` :bdg:`string` :bdg-danger:`required`
        Location ID. Must be a valid location for the member.

    ``can_order`` :bdg:`boolean` :bdg-danger:`required`
        Whether the user can place orders from this location. The primary location (``sort_order: 1``)
        must have this set to ``true``.

    ``sort_order`` :bdg:`integer` :bdg-danger:`required`
        Display order for the location. Must be a unique positive integer. The location with
        ``sort_order: 1`` is the primary location.

Example
~~~~~~~

.. code-block:: json

    {
        "username": "jsmith",
        "first_name": "John",
        "last_name": "Smith",
        "email": "jsmith@example.com",
        "address": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip": "62701",
        "employee_id": "EMP001",
        "phone_number": "5551234567",
        "catalog_region_id": "region1",
        "account_id": "acct1",
        "company_name": "Smith Auto",
        "locations": [
            {
                "id": "loc1",
                "can_order": true,
                "sort_order": 1
            },
            {
                "id": "loc2",
                "can_order": false,
                "sort_order": 2
            }
        ]
    }


Response
--------

Success
~~~~~~~

.. code-block:: json

    {
        "username": "jsmith",
        "user_id": 12345
    }

A welcome email with login credentials is sent to the user's email address upon successful creation.

Errors
~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Error
     - Status
     - Description
   * - Invalid catalog region id
     - 400
     - The provided ``catalog_region_id`` is not valid
   * - Username already exists
     - 400
     - The provided ``username`` is already in use
   * - Email already exists
     - 400
     - The provided ``email`` is already in use
   * - Invalid address
     - 400
     - The address could not be validated
   * - Invalid user locations
     - 400
     - One or more location IDs are not valid for the member