Link Search Menu Expand Document

Adding a user


  • Call name: add-user
  • Endpoint URL:
  • 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-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.


This API call adds information about a new user.

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.


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

Parameter Description
X-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, mandatory or optional depending on the setup of the member programme) 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, if it is being created in a branch. If the store_id value is also supplied, then store_id takes precedence. 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.
fb_access_token (string, mandatory in the case that the user is being added on the basis of their Facebook account details) The Facebook access token of the user.
first_name (string, optional) The first name of the user.
gender (string, optional) The gender of the user. Allowed values are M and F in either upper or lower case.
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, mandatory unless the user is being added on the basis of their Facebook account details) 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. If this 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 except in cases where Spaaza is the source of authentication for the member) 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) The programme subscription status of the user. Note that if this chain has a programme using an opt-in value and this parameter is not supplied, a default value of true 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, assuming it was created in a branch.
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, mandatory unless the fb_access_token parameter is being used to add a user on the basis of their Facebook account details) The username of the user in email address format.

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

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:


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

The chain is configured with a dummy email domain of 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

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 '' \
--header 'X-Spaaza-API-version: 1.4.2' \
--header 'session_user_id: 123456' \
--header '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 ''

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": {
            "id": 123123,
            "user_id": 123123,
            "authentication_point_identifier": "10555454555",
            "first_name": "Foo",
            "last_name": "Bar",
            "gender": "M",
            "birthday": "1986-01-30",
            "country_code": "NL",
            "address_streetname": "Herengracht",
            "address_housenumber": "504",
            "address_housenumber_extension": "II",
            "address_line_2": "Grachtengordel",
            "address_line_3": "Centrum",
            "address_towncity": "Amsterdam",
            "address_regionstate": "Noord-Holland",
            "address_postalcode": "1017 CB",
            "username": "",
            "phone_number": "+31-220445641",
            "member_number": "178546",
            "language": "en-GB",
            "opt_in_secondary": true,
            "mailing_list": {
                "mailing_list_sub_offered": true,
                "mailing_list_subscribed": false,
                "printed_mailing_list_subscribed": true
            "entity_code": {
                "type": "custom",
                "code": "123123"
            "opt_in_programme": {
                "programme_opted_in": true,
                "join_date": "2019-04-02T03:05:42+00:00"
            "signup_store": {
                "signup_store_id": 1383,
                "signup_store_name": "ACME Inc"
            "home_store": {
                "home_store_id": 2774,
                "home_store_name": "Herengracht HQ"
            "registered": true,
            "is_employee": false,
            "user_type": "new",
            "updated_existing_user": false,
            "loyalty_status": {
                "campaign_id": 2095,
                "name": "Level 1",
                "description": "Level 1 in the Programme",
                "loyalty_level_id": 2,
                "points_to_proceed_next_level": 500,
                "points_to_remain_current_level": 220,
                "maintenance_points_level": 200,
                "last_review_date": "2019-04-04T00:05:22+00:00",
                "next_review_date": "2020-04-04T00:05:22+00:00",
                "date_reached": "2019-06-06T08:06:14+00:00"
            "frequency": 3,
            "recency": 5,
            "monetary": 2,
            "overall": 532,
            "stores": null,
            "online_shopper": true,
            "offline_shopper": false,
            "average_basket_value": "119.30",
            "days_since_last_purchase": 6,
            "number_of_purchases": 4,
            "referral_channel": "store",
            "referral_code": "ptola9",
            "referring_user": {
                "authentication_point_identifier": "2152416",
                "campaign_id": 2067,
                "id": 3593704,
                "referral_channel": "webshop",
                "referral_code": "b09zy7"
        "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.
2 password_invalid
The password is invalid. Your password should be 6 characters or more.
3 http_vars_missing
This script is missing some required variables which must be submitted.
6 no_valid_session
The user needs to be logged in and a valid session key needs to be sent
7 user_username_invalid
The user_username passed must be a valid email address
68 permission_denied_or_non_existent
This user has insufficient permissions for this object or the object does not exist.
96 gender_value_error
The gender value submitted must be one of m/M or f/F.
151 fb_graph_api_access_failed
Failed to contact the Facebook Graph API.
152 fb_oauth_exception
OAuth problem accessing Facebook with your access token.
153 fb_graph_misc_exception
Facebook reports a miscellaneous error accessing the Graph API.
217 chain_id_not_found
No record has been found for that chain_id
228 auth_method_invalid
The given auth_method parameter has an invalid value.
234 user_already_exists
There is already an account using this email address. Please login or use a different email address.
237 date_value_error
The submitted date must be in the format YYYY-mm-dd.
274 magento_oauth_exception
Wij hebben een technisch probleem. Onze support team is op de hoogte gebracht
275 magento_unexpected_response
Unexpected response from Magento
265 authorization_invalid
The given authorization header is invalid.
266 access_token_invalid
The given access token is invalid.
267 no_valid_user
A valid username needs to be specified
272 hasher_type_invalid
Invalid hasher_type, must be integer 1-3 in length
278 postalcode_invalid
The postal code submitted is in an invalid format
290 mailing_list_not_activated
The mailing-list for this app is not activated
291 mailing_list_subscribed_boolean_required
The mailing_list_subscribed parameter must be boolean
292 mailing_list_sub_offered_boolean_required
The mailing_list_sub_offered parameter must be boolean
316 parameter_supplied_not_boolean
One of the parameters supplied must be boolean and is not
321 programme_opted_in_boolean_required
The programme_opted_in parameter must be boolean
322 secondary_email_invalid
The secondary email is incorrectly formatted.
417 string_parameter_too_long
One of the parameters passed is too long
420 country_code_invalid
The country code must be in ISO ALPHA-2 two-letter format
424 access_denied
Access is denied
426 member_number_range_invalid
member_number value received is higher than set max allowed value for myprice app
434 too_many_duplicate_objects
Too many duplicate objects have been detected
435 insufficient_objects
Insufficient objects have been detected