Link Search Menu Expand Document

Adding a user

Returns an OK code and a JSON for the user. A sample 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-30T00:00:00+00:00",
         "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":"foo@bar.com",
         "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,
         "referring_user":{ 
            "id":3593704,
            "referral_code":"gizyvl"
         },
         "referral_code":"ptola9"
      },
      "result_type":"add-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
  • 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)

Introduction

This API call adds information about a new user.

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.
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 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 (integer, optional) The referral code of the user which referred the user. If this is indeed a valid referral_code this will return the id of the referring user.
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. 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.

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.

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:

{"client_channel":"pos"}

Updating an existing user

If the add-user endpoint finds 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.
  • It is possible to use any of the username, member_number or authentication_point_identifier parameters to update an existing user. Therefore developers coding clients should take care not to update attributes which should be immutable in e.g. a remote system.
  • 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.
  • 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.

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