Adding a user

Contents

• Overview
• Introduction
• Version-specific information
• Permissions and Authentication
• Headers
• HTTP Parameters
• Recording Signup Channel
• Updating an existing user
• Creating a user with a dummy username (email address)
• Sample requests
• Possible error responses

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

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

This API endpoint adds 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

This API call requires a valid Spaaza session (see authentication). The session can be as follows:

• 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:

¹ 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 instead of having to make a separate call to the alter-user endpoint. This is done by setting the update_if_exists parameter to true.

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 no username parameter is passed, a dummy email address will automatically be assigned to an end-user. This is done in one of two ways:

Assigning a dummy email with a configured domain name

In this case, the dummy email address is assigned using a domain name configured in the chain settings. The domain name is appended to the member_number parameter to create the email address. The following conditions must be met for this to work

• 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

This is useful for assigning an existing range of member_number values to end-users, for example where a known range of physical loyalty cards is in use by customers, but the chain does not have email addresses for these customers. In that case, it is possible to continue to use the physical card, and update the customer email address (when it is known) at a later date.

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.

Assigning a dummy email with a Spaaza-generated domain name

In this case, the dummy email address is assigned using a Spaaza-generated domain name. The domain name is appended to the member_number parameter to create the email address. The following conditions must be met for this to work

• The chain must not have a domain configured to use with dummy email addresses
• The username parameter must not be passed in the request

This is useful for creating a user account with no known email address or member_number value. The dummy email address is generated by Spaaza and is unique to the user account. The created account is assigned a Spaaza user_id value and can be recognised in subsequent API calls by this value or one of the other identifier parameters such as member_number or authentication_point_identifier.

Sample requests

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: