User

User's represent the end-customers that interact with a merchant's brand. Users complete purchases, receive campaigns, and can hold balances.

POST/user/register

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

POST

/user/register

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"
      }
  }

POST/user/authenticate

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

POST

/user/authenticate

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"
        }
    }
}

POST/user/logout

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

POST

/user/logout

curl -G https://api.spoonity.com/user/logout?session_key={session_key}

Response

{}

POST/user/password-reset/reset

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

POST

/user/password-reset/reset

curl -G https://api.spoonity.com/user/password-reset/reset \
-d '{
    "email_address": "brandin@spoonity.com",
    "vendor": 1
}'

Response

{}

POST/user/password-reset/apply

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

POST

/user/password-reset/apply

curl -G https://api.spoonity.com/user/password-reset/apply \
-d '{
    "token": "8ac39a5f61785061a6c4a1c8abe8dd9c,
    "password": "Spoonity1"
}'

Response

{}

GET/user/profile

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

GET

/user/profile

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": {}
}

PUT/user/profile

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

PUT

/user/profile

curl -G https://api.spoonity.com/user/profile?session_key={session_key} \
-d '{
    "phone_number": {
        "number": "1234567890",
        "code": "1"
    }
}'

Response

{}

DELETE/vendor/{vendor_id}/customers/{user_id}/submit

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

DELETE

/vendor/{vendor_id}/customers/{user_id}/submit

curl -G https://api.spoonity.com/vendor/{vendor_id}/customers/{user_id}/submit?session_key={session_key}

Response

{}

DELETE/vendor/{vendor_id}/customers

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

DELETE

/vendor/{vendor_id}/customers

curl -G https://api.spoonity.com/vendor/{vendor_id}/customers \
--request DELETE \
-d '{
    "code": "aca0a733c0ba5a8afde59ce6d6f4dbf3"
}'

Response

{}

GET/user/isValidated

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

GET

/user/isValidated

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
    }
}

GET/user/activate

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

GET

/user/activate

curl -G https://api.spoonity.com/user/activate?session_key={session_key}&token={token}

Response

{}

GET/user/activate/email

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

GET

/user/activate/email

curl -G https://api.spoonity.com/user/activate/email?session_identifier={session_identifier}

Response

{}

GET/user/activate/sms

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 country parameter.

Name
country
Type
string
Description
The two letter ISO 3166-1 code that indicates which country this phone number is registered in.

Request

GET

/user/activate/sms

curl -G https://api.spoonity.com/user/activate/sms?session_identifier={session_identifier}&phone=1234567890&country=CA

Response

{}

GET/user/email/exists

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

GET

/user/email/exists

curl -G https://api.spoonity.com/user/email/exists?email={email}&vendor={vendor}

Response

{
    "exists": true,
    "vendor": {
        "id": 1044383,
        "name": "Cookie Hut"
    }
}

GET/user/mobile/exists

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

GET

/user/mobile/exists

curl -G https://api.spoonity.com/user/mobile/exists?mobile={mobile}&vendor={vendor}

Response

{
    "available": false
}

GET/user/cedula/exists

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

GET

/user/cedula/exists

curl -G https://api.spoonity.com/user/cedula/exists?cedula={cedula}&vendor={vendor}

Response

{
    "exists": false,
    "valid": true,
    "vendor": {
        "id": 101331,
        "name": "Sweet & Coffee"
    }
}

POST/user/token/request

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

POST

/user/token/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": {}
}