.. index:: Users User

.. _user:

User
====

A Marktplaats user. Email, phoneNumber and postcode are only returned when the user resource you are retrieving represents the logged in user.

.. _Fields:

Fields
------

.. apifields::
    .. apifield::
        :name: userId
        :type: int
        :constraints: --
        :required: false
        :updateable: false
        :writable: false

        Uniquely identifies a user

    .. apifield::
        :name: locale
        :type: string
        :constraints: for Marktplaats only `nl-NL` allowed, for 2dehands: `nl-BE` and `fr-BE` allowed
        :required: false
        :updateable: true
        :writable: true

        The locale used for the user. This is only relevant for users on the 2dehands platform.

    .. apifield::
        :name: status
        :type: string
        :constraints: one of ``unconfirmed``, ``confirmed``
        :required: false
        :updateable: false
        :writable: true

        Status of this user. This field may be used :ref:`to create <create_activated_account>` a user account
        without the email confirmation.

    .. apifield::
        :name: email
        :type: string
        :constraints: valid email address unique within Marktplaats
        :required: true
        :updateable: true
        :writable: true

        The email address for this account

    .. apifield::
        :name: name
        :type: string
        :constraints: max. 30 chars
        :required: false
        :updateable: true
        :writable: true

        The name of the user

    .. apifield::
        :name: phoneNumber
        :type: string
        :constraints: --
        :required: false
        :updateable: true
        :writable: true

        .. include:: reference/phonenumber-requirements.rst

    .. apifield::
        :name: postcode
        :type: string
        :constraints: max. 6 chars
        :required: false
        :updateable: true
        :writable: true

        Postcode of the location where the user lives

    .. apifield::
        :name: confirmDate
        :type: ISO 8601 string
        :constraints: --
        :required: false
        :updateable: false
        :writable: false

        When the account was confirmed

    .. apifield::
        :name: trackingProgram
        :type: string
        :constraints: --
        :required: false
        :updateable: false
        :writable: false

        The name of user's tracking program, e.g. ``cps``

    .. apifield::
        :name: dealerPackage
        :type: string
        :constraints: should be ``NONE``, ``BASIC``, ``PLUS`` or ``PREMIUM``.
        :required: false
        :updateable: false
        :writable: false

        The name of user's dealer package or NONE if not present. Possible values for this field are ``NONE``, ``BASIC``, ``PLUS`` or ``PREMIUM``

    .. apifield::
        :name: billing
        :type: :ref:`Billing <billing>`
        :constraints: --
        :required: true

        The user's billing status.

Relations
---------

.. relations::
    .. relation::
        :name: mp:user-features
    .. relation::
        :name: mp:user-profile
    .. relation::
        :name: mp:change-email
        :availability: When you are the logged in user
    .. relation::
        :name: mp:user-advertisements
    .. relation::
        :name: mp:user-reviews
    .. relation::
        :name: mp:user-statistics

Reference
---------

.. endpoint:: GET /v1/users/{userId}

Get a user.


Errors
------

.. errors::
    .. error::
        :http: 400
        :code: validation-failure

        Validation of the user failed.
        There should be more information in the field errors.


Field errors
------------

.. fielderrors::
    .. error::
        :field: phoneNumber
        :code: input-invalid
        :description: The phonenumber is in an invalid format
    .. error::
        :field: postcode
        :code: input-invalid
        :description: The postcode is unknown or in an invalid format
    .. error::
        :field: email
        :code: email-in-use
        :description: The specified email is already in use


Examples
--------

.. include:: examples/get-user-example.rst

.. _update-user:

Updating a User
---------------

Using PUT or PATCH a user's info can be updated. See `Fields`_ for a complete overview of what user info can be updated.

N.B. When updating a user's info we DO NOT overwrite existing user info in the advertisements of the user.

Field errors
^^^^^^^^^^^^

.. fielderrors::
    .. error::
        :field: name
        :code: input-too-long
        :description: The supplied name is too long
    .. error::
        :field: name
        :code: input-invalid
        :description: The supplied name is empty or invalid
    .. error::
        :field: phoneNumber
        :code: input-invalid
        :description: The phonenumber has an invalid format
    .. error::
        :field: postcode
        :code: input-invalid
        :description: The postcode is unknown or has an invalid format


.. include:: examples/update-user-example.rst