Link Search Menu Expand Document

Adding a user

Contents

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.

Version Change details
>= 1.4.10 Update gender parameter to support male, female, nonbinary, transgender, agender, genderqueer, genderfluid, bigender, twospirit, androgynous, pangender, neutrois, demigender and other.

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:

Parameter Description
X-Spaaza-MyPrice-App-Hostname (mandatory in the case of privileged authentication, must not be passed otherwise) The hostname of the app which the user is associated with.
X-Spaaza-Request (optional) Can be used to record signup channel (see below)

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
address_housenumber (string, optional) The street number or house name of the user’s postal address.
address_housenumber_extension (string, optional) The extension of the street number of the user’s postal address, for example “Apartment 21”
address_line_2 (string, optional) The second line of the user’s postal address, which can be used to denote e.g. a neighbourhood or village.
address_line_3 (string, optional) The third line of the user’s postal address, which can be used to denote e.g. a village or borough
address_postalcode (string, optional) The user’s postal or zipcode.
address_regionstate (string, optional) The region or state of the user’s postal address.
address_streetname (string, optional) The street name of the user’s postal address.
address_towncity (string, optional) The user’s postal city.
affiliate_code (string, optional) Any affiliate code to be used in connection with a campaign such as an invite-a-friend campaign which causes secondary logic to be applied on creation of the user, such as creating a voucher for another user.
authentication_point_identifier (string, optional) The id of the user in a third-party identity system such as a webstore. Highly recommended in the case that e.g. an update to the member’s email address will be made by the source of identity if that source is not Spaaza - in this case the authentication_point_identifier can be used as a unique identifier for the customer.
authentication_point_multi_id (integer, optional) In a Spaaza scenario where multiple identity sources (“authentication points”) are present, this associates a user account with one of the authentication points
auxiliary_identifier (string, optional) An auxiliary identifier string used by the retailer or other organisation. This value is returned in displays and is searchable in Spaaza analytics, but is not generally used as a primary identifier in API endpoints.
birthday (string, optional) The birth date of the user. ISO 8601 (YYYY-MM-DD) or ISO 8601 extended (e.g. 1983-07-27T00:00:00+00:00 or 1983-07-27T00:00:00Z) are the default allowed formats. Dates in other formats (“D/M/YYYY”, “DD/MM/YYYY”, “D-M-YYYY” and “DD-MM-YYYY” can be used instead - see the birthday_field_format parameter). If the birthday parameter is supplied in ISO 8601 extended format any timezone offset will be converted to UTC.
birthday_field_format (string, mandatory if supplying birthday parameter in a format other than ISO 8601 or ISO 8601 extended) The format of the birthday parameter supplied if not in ISO 8601 or ISO 8601 extended format. Allowed values are “DD-MM-YYYY”, “D-M-YYYY”, “DD/MM/YYYY” and “D/M/YYYY”. Any other value implies ISO 8601/ISO 8601 extended format.
branch_business_owner_code (string, optional) A retailer-specific branch code used by the retailer to identify the individual branch in a chain in which the new account is being created (the “signup store”), if it is being created in a branch. If the store_id value is also supplied, then store_id takes precedence (see below). In order to use the branch_business_owner_code field there must be a record of the branch code in the Spaaza database.
chain_id (integer, mandatory when using admin authentication) The id of the chain (retailer) to which the user is connected.
country_code (string, optional) The ISO ALPHA-2 country code of the user.
first_name (string, optional) The first name of the user.
gender (string, optional) The gender of the user. Allowed values are male, female, nonbinary, transgender, agender, genderqueer, genderfluid, bigender, twospirit, androgynous, pangender, neutrois, demigender and other.
home_store_id (integer, optional) Home store id in the Spaaza system for which the new account was created
is_employee (boolean, optional) Whether the user is an employee of a chain. The defualt value if this paramter is not supplied is false.
language (string, optional) The preferred IETF BCP 47 language code (eg. en-GB, nl, nl-BE, etc.) for a user. The language code should consist of an ISO 639 language tag (e.g. nl) followed by optional subtags (e.g. BE), using hyphens as separators, for example nl-BE.
last_name (string, optional) The last name of the user.
mailing_list_sub_offered (boolean, optional) Whether a subscription to the mailing list was offered to the user. If this parameter is not supplied a default value of false is applied.
mailing_list_subscribed (boolean, optional) Whether the user is subscribed to the mailing list. If this parameter is not supplied a default value of false is applied.
member_number¹ (string, optional) The unique membership number or code for the shopper within the membership or loyalty programme. By default, this is auto-generated by Spaaza. If this parameter is supplied it must be in an assigned range and will override the Spaaza-generated member number. In most cases this is numeric, but string values are allowed.
opt_in_secondary (boolean, optional) Generic opt in field to be used by the retailers, for recording opt ins that the standard fields don’t allow.
password (string, optional) The password for the user.
phone_number (string, optional) The contact number for a user.
printed_mailing_list_subscribed (boolean, optional) Whether the user is subscribed to the mailing list for printed mail such as catalogues.
programme_opted_in (boolean, optional) Whether the customer is opted in to the programme or not. Note that if this chain requires a user to be opted into a programme, the programme will only work for the user if this is set to true. If this parameter is not supplied, a default value of false is applied.
referral_code (string, optional) The referral code of another user who referred this user. If the referral_code is valid (i.e. is recognised as belonging to another user) this will return the id of the referring user in the referring_user section of the response.
registered (boolean, optional) Whether the user is registered. The definition of the term ‘registered’ is flexible. The default value if this parameter is not supplied is true.
store_id (integer, optional) Spaaza ID of the branch in which the new account was created (the “signup store”), assuming it was created in a branch. NOTE that this parameter should only be used if you know the Spaaza ID of the branch - in most cases the branch_business_owner_code parameter is used. NOTE this parameter takes precedence over the branch_business_owner_code parameter (even if sent as blank) - see above.
update_if_exists (boolean, optional) If the user being added already exists, this flag can be used to update the existing user with the parameters supplied instead of returning an error. Only works if using admin or privileged authentication. Care should be taken when using this parameter. See the Updating an Existing User section below for more details.
username¹ (string, optional) The username of the user in email address format. Note that if no username parameter is passed, a dummy email address will be created.

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

Header Description
X-Spaaza-Request (string, optional) A JSON-encoded string using the ‘client_channel’ key to denote the signup channel of the user. Allowed values are mobile, pos and import.

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:

Code Name and Description HTTP Status Code
1 username_invalid
The username is incorrectly formatted. Your username should be a valid email address.
400
2 password_invalid
The password is invalid. Your password should be 6 characters or more.
400
3 http_vars_missing
This script is missing some required variables which must be submitted.
400
6 no_valid_session
The user needs to be logged in and a valid session key needs to be sent
401
7 user_username_invalid
The user_username passed must be a valid email address
400
68 permission_denied_or_non_existent
This user has insufficient permissions for this object or the object does not exist.
500
96 gender_value_error
The gender value submitted must be one of m/M or f/F.
500
151 fb_graph_api_access_failed
Failed to contact the Facebook Graph API.
500
152 fb_oauth_exception
OAuth problem accessing Facebook with your access token.
400
153 fb_graph_misc_exception
Facebook reports a miscellaneous error accessing the Graph API.
500
217 chain_id_not_found
No record has been found for that chain_id
400
228 auth_method_invalid
The given auth_method parameter has an invalid value.
500
234 user_already_exists
There is already an account using this email address. Please login or use a different email address.
400
237 date_value_error
The submitted date must be in the format YYYY-mm-dd.
500
274 magento_oauth_exception
Wij hebben een technisch probleem. Onze support team is op de hoogte gebracht
400
275 magento_unexpected_response
Unexpected response from Magento
400
265 authorization_invalid
The given authorization header is invalid.
400
266 access_token_invalid
The given access token is invalid.
401
267 no_valid_user
A valid username needs to be specified
401
272 hasher_type_invalid
Invalid hasher_type, must be integer 1-3 in length
400
278 postalcode_invalid
The postal code submitted is in an invalid format
400
290 mailing_list_not_activated
The mailing-list for this app is not activated
401
291 mailing_list_subscribed_boolean_required
The mailing_list_subscribed parameter must be boolean
401
292 mailing_list_sub_offered_boolean_required
The mailing_list_sub_offered parameter must be boolean
401
316 parameter_supplied_not_boolean
One of the parameters supplied must be boolean and is not
400
321 programme_opted_in_boolean_required
The programme_opted_in parameter must be boolean
400
322 secondary_email_invalid
The secondary email is incorrectly formatted.
400
417 string_parameter_too_long
One of the parameters passed is too long
400
420 country_code_invalid
The country code must be in ISO ALPHA-2 two-letter format
400
424 access_denied
Access is denied
400
426 member_number_range_invalid
member_number value received is higher than set max allowed value for myprice app
400
434 too_many_duplicate_objects
Too many duplicate objects have been detected
400
435 insufficient_objects
Insufficient objects have been detected
400