User
User's represent the end-customers that interact with a merchant's brand. Users complete purchases, receive campaigns, and can hold balances.
Register
This request is responsible for creating a profile for a new user. This sets up an account with basic user information such as first and last names, the user's email address, and the user's preferred language.
Required attributes
- Name
first_name- Type
- string
- Description
The first name of the user that is registering.
- Name
last_name- Type
- string
- Description
The last name of the user that is registering.
- Name
anonymous- Type
- boolean
- Description
Always set to false.
- Name
email_address- Type
- string
- Description
The email the user wants linked to their account.
- Name
password- Type
- string
- Description
The password the user will use to access their account.
- Name
terms- Type
- boolean
- Description
Always set to true.
- Name
vendor- Type
- integer
- Description
The internal reference number associated with the specific vendor with which the user is registering.
Optional attributes
- Name
birthdate- Type
- integer
- Description
The user's date of birth as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
language- Type
- integer
- Description
An internal reference number that indicates the user's preferred language.
- Name
cedula- Type
- string
- Description
The cedula of the user that is registering, only needed in South America.
- Name
contact_consent- Type
- integer
- Description
An internal reference number that represents the user's consent to being contacted. Valid options for consent are:
- 0: No consent
- 1: Consent to receive email
- 2: Consent to receive SMS
- 3: Consent to receive both email and SMS
Response attributes
- Name
id- Type
- integer
- Description
An internal reference number associated with this user.
- Name
first_name- Type
- string
- Description
The first name the user registered with.
- Name
last_name- Type
- string
- Description
The last name this user registered with.
- Name
email_address- Type
- string
- Description
The email address this user registered with.
- Name
birthdate- Type
- integer
- Description
The user's date of birth if it was included as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
date_created- Type
- integer
- Description
The date this account was created as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
date_updated- Type
- integer
- Description
The date this account was last updated as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
status- Type
- object
- Description
An object that holds information about the current status of the user.
Request
curl -G https://api.spoonity.com/user/register \
-d '{
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@example.com",
"password": "abc123",
"terms": true,
"vendor": 1
}'
Response
{
"object": "user",
"id": "1000454652210",
"first_name": "Grace",
"last_name": "Duncan",
"email_address": "grace@spoonity.com",
"facebook_identifier": null,
"twitter_identifier": null,
"google_identifier": null,
"linkedin_identifier": null,
"birthdate": 845908004,
"date_created": 1558967253,
"date_updated": 1558967253,
"status": {
"id": 1,
"name": "Active"
}
}
Authenticate
This request authenticates a user's credentials and creates a login session. Here, information about the user as it applies to this vendor is returned. The session identifier value is crucial to accessing this current login session at any given time.
Required attributes
- Name
email_address- Type
- string
- Description
The email with which the user registered their account.
- Name
password- Type
- string
- Description
The password with which the user registered their account.
- Name
vendor- Type
- integer
- Description
The internal reference number for the vendor with which the user is attempting to log in.
Response attributes
- Name
first_login- Type
- boolean
- Description
A boolean value indicating if this is the user's first login to this vendor with this account.
- Name
online_order_token- Type
- string
- Description
Unique to this login session, allows a specific third party to access this same login session, in most cases this is safe to ignore.
- Name
session_identifier- Type
- string
- Description
A key unique to this current login session.
- Name
user_vendor- Type
- object
- Description
An object that contains information about the user that is specific to this vendor.
Request
curl -G https://api.spoonity.com/user/authenticate \
-d '{
"email_address": "john.doe@example.com",
"password": "abc123",
"vendor": 1
}'
Response
{
"first_login": false,
"object": "user_session",
"online_order_token": "edd13104b9e256cc12ab8f458db6cb34",
"vendor_user": null,
"session_identifier": "056930a5606663c59129029552932d9d",
"user_vendor": {
"language": null,
"object": "user_vendor",
"vendor": {
"id": 1,
"name": "Spoonity",
"object": "vendor"
},
"anonymous": false,
"reload_amount": 0,
"reload_threshold": 0,
"contact_consent": 0,
"created": 1468417320,
"billing_profile": null,
"tier": {
"object": "vendor_tier",
"id": 12,
"name": "Default",
"summary": "",
"description": ""
},
"tier_since": 1468417320,
"user": {
"object": "user",
"id": "582846",
"first_name": "brandin",
"last_name": "chiu"
}
}
}
Log out
This request uses the session identifier key that was generated in the user_authenticate request to log out of the session.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Request
curl -G https://api.spoonity.com/user/logout?session_key={session_key}
Response
{}
Reset password
With this request, the user can reset the password linked to their account. This request is used when a user indicates they forgot their password, so the user must only supply an email address to receive the reset information. An email is sent to the given address with a "token", which must be sent with the next request to finalize the password reset.
Required attributes
- Name
email_address- Type
- string
- Description
The email address for the account for which the password is being reset.
- Name
vendor- Type
- integer
- Description
The internal reference number for the vendor with which the user is resetting their password.
Request
curl -G https://api.spoonity.com/user/password-reset/reset \
-d '{
"email_address": "brandin@spoonity.com",
"vendor": 1
}'
Response
{}
Update password
The token sent in the email to the user is used in this request to access the user's account and apply the new password. Requiring this token adds an extra measure of security, as it means the user is authorized to access to the email that is linked to the account being changed. Without this, any user could change the password to any given account for which they know an email address, regardless of authorization to access that email or Spoonity account ownership.
Required attributes
- Name
token- Type
- string
- Description
The value that was sent to the customer via the email they entered in the previous request.
- Name
password- Type
- string
- Description
The new password for this user's account.
Request
curl -G https://api.spoonity.com/user/password-reset/apply \
-d '{
"token": "8ac39a5f61785061a6c4a1c8abe8dd9c,
"password": "Spoonity1"
}'
Response
{}
Retrieve user's profile
This request is used to get a user's profile information. The session_identifier that was produced on the user's login is used to fetch general information about the user such as their address, first and last names, push notification settings, contact consent settings, etc.
This request will also return any optional information that is linked to the user's account, such as a user's favourite location if this has been specified.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Response parameters
- Name
anonymous- Type
- boolean
- Description
A boolean, always set to false.
- Name
billing_profile- Type
- object
- Description
The user's billing profile that is selected for automatic reload, null if this feature is disabled.
- Name
contact_consent- Type
- integer
- Description
An internal reference number that represents the user's consent to be contacted by this vendor. Valid options for consent are:
- 0: No consent
- 1: Consent to receive email
- 2: Consent to receive SMS
- 3: Consent to receive both email and SMS
- Name
created- Type
- integer
- Description
The date this user's profile was created with this specific vendor, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
flagged- Type
- boolean
- Description
A boolean, true if this user's account has been flagged for suspicious or fraudulent behaviour.
- Name
id- Type
- integer
- Description
An internal reference number that links the user's account to this specific vendor.
- Name
is_verified- Type
- object
- Description
An object that indicates if the user is verified or not, similar to the response of the user_is_validated request in the "Registering an account" workflow.
- Name
language- Type
- object
- Description
An internal reference number indicating the language that the user has specified to use.
- Name
metadata- Type
- array
- Description
An array of objects that each store details about information that is surplus to the user's required profile data.
- Name
online_order_token- Type
- string
- Description
Unique to this login session, allows a specific third party to access this same login session, in most cases this is safe to ignore.
- Name
push_endpoints- Type
- array
- Description
Unique id that can be used to send the user push notifications.
- Name
referral_url- Type
- string
- Description
A url that this user can share with a new user to earn points or apply a discount to both accounts.
- Name
reload_amount- Type
- float
- Description
How much a user has indicated to reload automatically with automatic reload.
- Name
reload_threshold- Type
- float
- Description
The point at which the user's account will automatically reload.
- Name
status- Type
- object
- Description
An object that contains information about the current status of the user.
- Name
updated- Type
- integer
- Description
The last date this profile was updated, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
user- Type
- object
- Description
An object that contains information about the user whose profile is being read.
- Name
vendor- Type
- object
- Description
An object that is always returned empty, safe to ignore.
Request
curl -G https://api.spoonity.com/user/profile?session_key={session_key}
Response
{
"anonymous": false,
"billing_profile": null,
"contact_consent": 0,
"created": 1559131926,
"flagged": false,
"id": "2974107",
"is_verified": {
"status": true,
"methods": {
"No Verification": false,
"Email": true,
"Sms": true
}
},
"language": null,
"metadata": [
{
"user_metadata_id": "6770055",
"user_metadataField_id": 7,
"field": "Address",
"value": "123 Smith St",
"validation": null,
"input_type": null
},
],
"newsletters": {},
"object": "user_vendor",
"online_order_token": null,
"push_endpoints": {
"gcm": [],
"apns": []
},
"referral_url": "http://app-builder.spoonity.com/storage/microsite/deploy/breakfast-bonanza#/invite/grace1441",
"reload_amount": 0,
"reload_threshold": 0,
"status": {
"status_id": 1,
"name": "Active"
},
"updated": 1559225428,
"user": {
"object": "user",
"id": 1000454652210,
"cid": null,
"facebook_identifier": null,
"email_address": "grace@spoonity.com",
"first_name": "Grace",
"last_name": "Duncan",
"phone_number": "11234567890",
"passport_number": null,
"address": {
"address1": "123 Smith St",
"address2": "",
"city": "",
"region": null,
"country": null,
"postal_code": ""
},
"birthdate": 845856000,
"pet": {
"name": null,
"date_of_birth": null
},
"created": 1558967253,
"updated": 1559225428,
"status": {}
},
"vendor": {}
}
Update a user's profile
This request is used to update information on a user's account. If only one piece of information is being updated, only that parameter has to be sent with the request. If multiple pieces of information are being updated, multiple parameters can be sent with one request to do this.
This request can be used to change things such as a user's password, email, or address.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Optional attributes
- Name
address1- Type
- string
- Description
The user's updated address.
- Name
city- Type
- string
- Description
The user's updated city.
- Name
region- Type
- integer
- Description
The user's updated region as the internal reference number to this region.
- Name
country- Type
- integer
- Description
The user's updated country as the internal reference number to this region.
- Name
postal_code- Type
- string
- Description
The user's updated postal or zip code.
- Name
phone_number- Type
- object
- Description
An object that contains information necessary to update the user's phone number.
- Name
password- Type
- string
- Description
The user's updated password, must include parameter
current_password.
- Name
email_address- Type
- string
- Description
The user's updated email, must also include parameter
current_password.
- Name
language- Type
- object
- Description
The user's updated language preference as the internal reference number for this language.
- Name
contact_consent- Type
- integer
- Description
The user's updated consent preferences as the internal reference number to this preference. Valid options for consent are:
- 0: No consent
- 1: Consent to receive email
- 2: Consent to receive SMS
- 3: Consent to receive both email and SMS
- Name
first_name- Type
- string
- Description
The user's updated first name.
- Name
last_name- Type
- string
- Description
The user's updated last name.
- Name
status- Type
- object
- Description
An object that contains the information necessary to update the user's status.
- Name
metadata- Type
- object
- Description
An object that contains the information necessary to update a metadata value.
Request
curl -G https://api.spoonity.com/user/profile?session_key={session_key} \
-d '{
"phone_number": {
"number": "1234567890",
"code": "1"
}
}'
Response
{}
Trigger the deletion of a user's account
This request is called when a user indicates they would like to delete their account. An email is sent to the customer with a code that will allow them to confirm the deletion process.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Path parameters
- Name
vendor_id- Type
- integer
- Description
The internal reference number for the vendor.
- Name
user_id- Type
- integer
- Description
The internal reference number for the user.
Request
curl -G https://api.spoonity.com/vendor/{vendor_id}/customers/{user_id}/submit?session_key={session_key}
Response
{}
Finalize the deletion of a user's account
The code received by the user via their email is sent to our system using this request, along with the vendor with which this account is being deleted. This request is responsible for the actual deletion of the user's account.
Path parameters
- Name
vendor_id- Type
- integer
- Description
The internal reference number for the vendor.
Required attributes
- Name
code- Type
- string
- Description
The code that the user received via email.
Request
curl -G https://api.spoonity.com/vendor/{vendor_id}/customers \
--request DELETE \
-d '{
"code": "aca0a733c0ba5a8afde59ce6d6f4dbf3"
}'
Response
{}
Check if user is verified
This request checks if a user is validated at a specific vendor. The session key gives access to information about which user has activated this session and with what vendor, making it unnecessary to supply any other information.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Response parameters
- Name
isValidated- Type
- boolean
- Description
A boolean, true if the user is validated, false if not.
- Name
phone_number- Type
- string
- Description
The phone number associated with this user.
- Name
methods- Type
- array
- Description
An array verification methods that are enabled with this vendor, user must have at least one of these verified in order to be validated.
- Name
status- Type
- object
- Description
An object that holds information about the status of validation for this user.
Request
curl -G https://api.spoonity.com/user/isValidated?session_key={session_key}
Response
{
"isValidated": true,
"phone_number": null,
"methods": [
"Email",
"Sms"
],
"status": {
"No Verification": false,
"Email": true,
"Sms": false
}
}
Verify a user
This request activates a user's account. The user must have an active login session, and must have received an activation token in an email or SMS. This token is necessary to activate the account.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
- Name
token- Type
- string
- Description
Activate token that was sent to the user via email.
Request
curl -G https://api.spoonity.com/user/activate?session_key={session_key}&token={token}
Response
{}
Resend email verification
This request sends an email to the user currently logged into the given session, this email contains the information necessary to verify that email address.
Query parameters
- Name
session_identifier- Type
- string
- Description
Session token for an end-customer.
Note that the parameter name is not the usual session_key.
Request
curl -G https://api.spoonity.com/user/activate/email?session_identifier={session_identifier}
Response
{}
Resend SMS verification
This request sends an SMS message to the user currently logged into the given session, and contains the information necessary to verify the mobile number on the account. If the user would like to change the mobile number this SMS message is sent to, extra query parameters phone and country must be included.
Query parameters
- Name
session_identifier- Type
- string
- Description
Session token for an end-customer.
Note that the parameter name is not the usual session_key.
- Name
phone- Type
- string
- Description
Allows the user to change the phone number during SMS validation (in case of error). When this parameter is included, you must also include a
countryparameter.
- Name
country- Type
- string
- Description
The two letter ISO 3166-1 code that indicates which country this phone number is registered in.
Request
curl -G https://api.spoonity.com/user/activate/sms?session_identifier={session_identifier}&phone=1234567890&country=CA
Response
{}
Check if email has been used
This request determines if the given email is linked with any account at Spoonity.
Query parameters
- Name
email- Type
- string
- Description
The email that is being attempted to be found.
- Name
vendor- Type
- integer
- Description
The vendor with which the email is being checked.
Response parameters
- Name
exists- Type
- boolean
- Description
True if this email exists, false otherwise.
- Name
vendor- Type
- object
- Description
An object that contains information about the vendor this email was first registered with.
Request
curl -G https://api.spoonity.com/user/email/exists?email={email}&vendor={vendor}
Response
{
"exists": true,
"vendor": {
"id": 1044383,
"name": "Cookie Hut"
}
}
Check if phone number has been used
This request determines if a mobile phone number is linked with any account at Spoonity.
Query parameters
- Name
mobile- Type
- string
- Description
The desired mobile number to be found.
- Name
vendor- Type
- integer
- Description
The id of the vendor with which the mobile number is being checked.
Response parameters
- Name
available- Type
- boolean
- Description
True if this is a valid phone number that is available to be registered, false otherwise.
Request
curl -G https://api.spoonity.com/user/mobile/exists?mobile={mobile}&vendor={vendor}
Response
{
"available": false
}
Check if cedula has been used
This request determines if a cedula is linked to any account at Spoonity.
Query parameters
- Name
cedula- Type
- string
- Description
The cedula that is being searched.
- Name
vendor- Type
- integer
- Description
The vendor with which the cedula is being checked.
Response parameters
- Name
exists- Type
- boolean
- Description
True if the cedula exists in our system.
- Name
valid- Type
- boolean
- Description
True if the cedula provided is valid in the vendor's country of residence.
- Name
vendor- Type
- object
- Description
An object that contains information about the vendor this cedula was first registered with.
Request
curl -G https://api.spoonity.com/user/cedula/exists?cedula={cedula}&vendor={vendor}
Response
{
"exists": false,
"valid": true,
"vendor": {
"id": 101331,
"name": "Sweet & Coffee"
}
}
Generate a user barcode
This request returns a unique token and barcode for the user. This barcode can be used to identify the user on check in when placing an order.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Required attributes
- Name
token_type- Type
- integer
- Description
A static value that is always
2.
Response parameters
- Name
barcode- Type
- string
- Description
Raw image data that can be used to identify user on check in.
- Name
created- Type
- integer
- Description
The date this token was created, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
expiry- Type
- integer
- Description
The date this token will expire, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
id- Type
- integer
- Description
An internal reference number that is unique to each token.
- Name
status- Type
- object
- Description
An object that contains information about the current status of this token.
- Name
token- Type
- string
- Description
Holds the same information encoded in the barcode, in string form.
- Name
updated- Type
- integer
- Description
The last date this token was updated, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
Request
curl -G https://api.spoonity.com/user/token/reqest?session_key={session_key} \
-d '{
"token_type": 2
}'
Response
{
"barcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAawAAAEgAQMAAADSdNVMAAAABlBMVEX///8AAABVwtN+AAAAAXRSTlMAQObYZgAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAX5JREFUaIHt2kGOAyEMRFHfwPe/pW9AqsrZ9kiTsIn0UZRWA4+dZTdQRfvNdtS6u9oPvc0Z/fymsT7Vk/EznqFOTRoYDPY1m5nSX5Vm1rS4fWU9LQKDwe4xB6OiUU5a8ZkA3bh1x4HBYBeZwtMx6v9kQa9T6ThZBwaD3WOepHzoGtQl6LhjKmnRCAaD3WMOx3ZUpuQUHs+sfAe6OoXBYNdY16bD2c2VyKx2PPKYFmEw2AfspA51YqzeEHVNqqh1lP6RFmEw2P+Z0mHGs8ei6d3e4cy+S4IWBoPdZJv9kgcVrJ1w9TGCBytHeTAY7A47W4fWOwUqSnN+l8OEIBgMdo3p54+8cgo0yJs7E6bnKS3CYLAP2N5H8Zde+x5YNjfbFah3NF2QwmCwayx9tXdRlAa9p3needI3VfqpDIXBYB8wf+z5iM7QJwlbmfocbzc6YTDYNeZ9zLOpMfdTEqydvc7KvUsYDHaNbWachKrL0c7JXe6pqE8PGAz2LaP9YnsBwc/jtlK3UtoAAAAASUVORK5CYII=",
"created": 1559231008,
"expiry": 2147483647,
"id": "897652",
"status": {},
"token": "2eb31700aad7b757751d1bf66f3d2b0c",
"type": {},
"updated": 1559231008,
"user": {},
"vendor": {}
}