Registering an account
In order for users to fully take advantage of a merchant's loyalty program, they must register. Registration requires the user to provide some basic personal information and create an account using their email address and a password.
This account will then serve as their digital identity, holding their balances, transaction history, and more.
The registration workflow
The typical registration workflow follows a consistent pattern:
- create an account
- authenticate for the first time
- optionally verify the account
- sign out
- go through a forgot password flow
Many of the above steps are optional except for the creating an account and authentication steps.
Support requests
The Spoonity API also includes several support requests for assisting in creating intuitive UX patterns for users when registering.
Check if email already exists
You can use the /user/email/exists API to check if an email has already been registered for a merchant.
Check if email already exists
curl -G https://api.spoonity.com/user/email/exists?email={email}&vendor={vendor}
Check if phone number already exists
You can use the /user/mobile/exists API to check if a phone number has already been registered for a merchant.
Check if phone number already exists
curl -G https://api.spoonity.com/user/mobile/exists?mobile={mobile}&vendor={vendor}
Check if cedula already exists
You can use the /user/cedula/exists API to check if a cedula has already been registered for a merchant.
Check if cedula already exists
curl -G https://api.spoonity.com/user/cedula/exists?cedula={cedula}&vendor={vendor}
These requests can be helpful if you want to redirect a user to a sign in or forgot password flow from a registration flow.
Registration and authentication
The core user management workflow involves two requests: one to create a new account, and another to generate a session linked to that account which can be used to authenticate API requests on behalf of a user.
Creating the account
Accounts are created using the POST /user/register request. The most important requirements are an email address and a password, which is used in subsequent requests to authenticate the account.
Creating the account
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
}'
Authenticating
Registered users can authenticate using the POST /user/authenticate request. This request will return a session token which can be used to authenticate subsequent API requests.
Authenticating
curl -G https://api.spoonity.com/user/authenticate \
-d '{
"email_address": "john.doe@example.com",
"password": "abc123",
"vendor": 1
}'
Verifying the account
In some cases, merchants may opt to require their users to verify their accounts before they can take full advantage of the program.
The Spoonity platform supports account verification through email or SMS.
All phone numbers must be verified before they can be used within the platform. This requirement applies even if a merchant does not require account verification.
Check if account is verified
The GET /user/isValidated API can be used to check the current verification status of an account. The response from this request can be used to determine how to render the frontend.
Check if account is verified
curl -G https://api.spoonity.com/user/isValidated?session_key={session_key}
Complete verification
Verification is completed by providing the verification code to the GET /user/activate API. The verification code will have been received by the user via whichever medium they are using to verify (email or SMS) and is provided to the API as the token parameter.
Complete verification
curl -G https://api.spoonity.com/user/activate?session_key={session_key}&token={token}
Resend verification code
Sometimes, the user either doesn't receive the code, or the code expires before the user can use it to verify their account.
In these cases, the resend verification APIs can be used to resend the verification token to the user.
Resend email verification
curl -G https://api.spoonity.com/user/activate/email?session_identifier={session_identifier}
SMS codes can also be resent.
When resending an SMS verification, the request also accepts optional phone and country parameters, which can be used to update the phone number to send the code to.
Note that this API is heavily rate limited in order to reduce abuse. Your integration should only allow infrequent opportunities for the user to resend SMS verification codes.
Resend SMS verification
curl -G https://api.spoonity.com/user/activate/sms?session_identifier={session_identifier}
Signing out
Sessions can be managed using the log out API. Your integration should take steps to ensure that user sessions are properly closed when prompted by the user.
Close the user's session
Users can invalidate their own sessions using the POST /user/logout API.
Close the user's session
curl -G https://api.spoonity.com/user/logout?session_key={session_key}
Recovering a password
If a user ever forgets their password, then can make use of the password recovery subflow to reset it.
The first step of this process triggers an email which includes a link to a web page or mobile app where the user can reset their password, and an underlying security token needed to validate the request.
The second step allows the user to set a new password.
Send a password reset email
Begin by sending an API request to POST /user/password-reset/reset. This will send a password reset email to the email address included in the request.
Send a password reset email
curl -G https://api.spoonity.com/user/password-reset/reset \
-d '{
"email_address": "brandin@spoonity.com",
"vendor": 1
}'
Set a new password
Next, send a request to POST /user/password-reset/apply. This should include the user's new intended password, and the security token which would have been included in the email generated by the previous step.
Set a new password
curl -G https://api.spoonity.com/user/password-reset/apply \
-d '{
"token": "8ac39a5f61785061a6c4a1c8abe8dd9c,
"password": "Spoonity1"
}'