Adding a user

Overview

• Call name: add-user
• Endpoint URL: https://api0.spaaza.com/internal/add-user
• Request methods: POST
• Request Content-Type: multipart/form-data or application/x-www-form-urlencoded or application/json*
• Response Content-Type: application/json
• Auth required: yes
• X-Spaaza-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication
• X-Spaaza-Request header: optional and can be used for to record signup channel (see below)

* In the case of a JSON payload (application/json) all parameters are top-level elements.

Introduction

This API call adds information about a new user.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Permissions and Authentication

• Admin authentication: the performing user needs to be logged in and have assign access to the entity (business or chain) to which the user is connected.
• Privileged authentication: the use of privileged authentication is permitted for this endpoint.

Headers

The following headers can/must be passed to the API call:

HTTP Parameters

The following HTTP parameters can be passed to the API:

¹ If the chain configuration allows it, it is possible to auto-assign a dummy username (email address) on creation of a user. See the section entitled ‘Creating a user with a dummy username’ below.

Recording Signup Channel

It is possible to set a header to record the “signup channel” of the user:

Example header payload:

{"client_channel":"pos"}

Updating an existing user

If there is already an existing user with the same username, member_number or authentication_point_identifier value, the default behaviour is to return a user_already_exists error with a HTTP 400 response code. When using admin or privileged authentication it is possible to override the default behaviour and update the user account using the parameters supplied in the HTTP POST to add-user.

In order to update an existing user either privileged authentication or admin authentication with assign access must be used.

When a user has been updated instead of created the updated_existing_user flag in the response is set to true and the user_type attribute returns as registered instead of new.

The following points should be noted when using the update_if_exists functionality:

• The functionality detects existing user accounts which have the same username, member_number or authentication_point_identifier attributes as the parameters supplied.
• If multiple different existing customers are found based on the username, member_number or authentication_point_identifier parameters supplied, the endpoint returns a too_many_duplicate_objects error.
• It is possible to use any of the username, member_number or authentication_point_identifier parameters to update an existing user. Therefore, when working on clients, developers should take care not to update attributes which should be immutable in e.g. a remote system.
• Using the update_if_exists parameter also executes updates on remote authentication points such as a webstore, where applicable, and assuming the add-user request does not originate from the remote authentication point.
• Care should be taken when sending empty parameters in an add-user request with update_if_exists set to true because those parameters will be set to null or empty if they are already populated.

Creating a user with a dummy username (email address)

If a chain’s configuration allows it, it is possible to assign a dummy email address to an end-user. This is done as follows:

• The chain must have a domain configured to use with dummy email addresses, e.g. customers.example.com
• The username parameter must not be passed in the request
• The member_number parameter must be passed in the request and be in an assigned range of custom numbers for the chain

Example:
The chain is configured with a dummy email domain of customers.example.com. The request is passed to the endpoint without the username parameter, and with the member_number parameter set to 123456789. The user will be assigned a username of 123456789@customers.example.com.

Adding a user

The following shows an example CURL request. This endpoint is also represented in the Spaaza Spaaza POSTMAN collection.

curl --location --request POST 'https://apistage0.spaaza.com/internal/add-user' \
--header 'X-Spaaza-API-version: 1.4.2' \
--header 'X-Spaaza-Session-User-Id: 123456' \
--header 'X-Spaaza-Session-Key: 3d0a11e194bc377a293cd64655e26b3363a3afaec6e7056b3102cf471f1ff034' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'chain_id=55552' \
--data-urlencode 'country_code=NL' \
--data-urlencode 'first_name=Josephine' \
--data-urlencode 'last_name=Smit' \
--data-urlencode 'member_number=123456789' \
--data-urlencode 'programme_opted_in=1' \
--data-urlencode 'username=customer_1@domain.example.com'

The endpoint returns JSON showing the details associated with the user. An example response is shown below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "user_info": {
            "address_housenumber": "46",
            "address_housenumber_extension": "B",
            "address_latitude": null,
            "address_line_2": null,
            "address_line_3": null,
            "address_longitude": null,
            "address_postalcode": "1015CB",
            "address_regionstate": "Any State",
            "address_streetname": "Any Street",
            "address_towncity": "Amsterdam",
            "authentication_point": null,
            "authentication_point_identifier": "99911166488945",
            "auxiliary_identifier": null,
            "average_basket_value": 42.65,
            "birthday": "1981-07-21",
            "business_group": null,
            "country_code": "NL",
            "created_date": "2024-01-31 15:15:43",
            "days_since_last_purchase": null,
            "entity_code": {
                "code": "3935159",
                "type": "regular"
            },
            "favorite_store": null,
            "first_name": "Joe",
            "frequency": 2,
            "gender": "M",
            "id": 3935159,
            "is_employee": false,
            "is_influencer": false,
            "language": null,
            "last_modified_date": "2024-01-31 15:15:43",
            "last_name": "Smith",
            "loyalty_status": {
                "date_reached": null,
                "last_review_date": "2024-01-31T15:15:43+00:00",
                "loyalty_level_id": null,
                "monetary_balance_current": 0,
                "next_review_date": null,
                "points_balance_current": 5,
                "points_to_proceed_next_level": null,
                "points_to_remain_current_level": null
            },
            "mailing_list": {
                "mailing_list_sub_offered": false,
                "mailing_list_subscribed": true,
                "printed_mailing_list_subscribed": true
            },
            "member_number": "3935159",
            "monetary": 1,
            "number_of_purchases": 17,
            "obfuscated": false,
            "offline_shopper": null,
            "online_shopper": null,
            "opt_in_programme": {
                "join_date": "2024-01-31T15:15:43+00:00",
                "programme_opted_in": true
            },
            "opt_in_secondary": false,
            "overall": null,
            "phone_number": "+31655222555",
            "points_wallet_total": 0,
            "push_notification_subscription": {
                "subscribed": false,
                "subscriptions": []
            },
            "recency": 5,
            "referral_channel": null,
            "referral_code": "gzo85d",
            "referred": true,
            "referring_user": {
                "authentication_point_identifier": null,
                "campaign_id": 2539,
                "id": 3930871,
                "referral_channel": null,
                "referral_code": "4t38p9"
            },
            "registered": true,
            "signup_channel": null,
            "signup_store": {
                "signup_store_id": 1383,
                "signup_store_name": "MOCO Museum store"
            },
            "stores": null,
            "total_cashback_balance": 0,
            "updated_existing_user": false,
            "user_id": 3935159,
            "user_type": "new",
            "username": "somedude0.11073246009398896@spaaza.com"
        },
        "result_type": "add-user"
    }
}

Possible error responses

The following represents a list of possible error responses for the add-user endpoint: