| Excerpt | ||
|---|---|---|
| ||
Sign-up, authentication, verification, and changing a verified mobile number |
| Note |
|---|
This page assumes you are familiar with Basic Sign-up and API Interaction |
Sign-up and verification
Adding SMS-verification to your app can prevent users from creating multiple entity accounts from a single device. At its simplest, adding SMS-verification functionality just adds a single verification step to the basic sign-up process, which starts with endpoint 1001: Create account:Sign-up and verification
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"firstName": "Alan",
"lastName": "Turing",
"userName": "a_turing",
"password": "3n1gm4",
"mobile": "12345678"
} |
...
The mobile number must be unique. To ensure this, the mobile number is sanitised and saved with its country-code prefix (45 in this example). If the mobile number is invalid or not unique, a 403400 response will be returned - see 1001: Create account for ApiStatusSubCode values.
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"code": "0827"
} |
| Note |
|---|
Remember that if Data Isolation is enabled, the |
When a valid 204 response is received, the entity is verified.
Authentication, before and after verification
As can be seen above, the dpKey is required to verify the entity. If the dpKey is lost before the verification is complete, it can be retrieved using endpoint 2001: Authenticate:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
ApiStatusSubCode: 403.2 DpKey: 12345 |
| Note |
|---|
Remember that if Data Isolation is enabled, the |
The ApiStatusSubCode header value 403.2 means that the entity is unverified, and when this ApiStatusSubCode is received, the DpKey header will also be included.
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"dpKey": 12345,
"firstName": "Alan",
"lastName": "Turing",
"userName": "a_turing",
"mobile": "4512345678",
"state": 0
} |
Changing mobile number
Before verification
If an SMS is not received for verification, it may be because the mobile number was entered incorrectly. Use endpoint 1003: Update account data to change the mobile number, and have another verification code SMS sent:
...
200.1 | A verification SMS has been sent |
200.2 | The daily verification limit of 5 SMS verifications has been reached for this user. No SMS has been sent! This should be communicated to the user, so they know they need to wait until the next day before trying again. |
200.3 | The minimum time of 2 minutes has not passed since the last verification was sent to this number. No SMS has been sent! This should be communicated to the user, so they know they need to wait before trying again. |
After verification
The default API behaviour is to prevent verified mobile numbers from being changed. In this case, mobile fields sent to endpoint 1003: Update account data will simply be ignored.
...
The successful update returns status code 200. If a mobile number field was included in the update, and the new number is different to the existing number, and updating verified mobile numbers mobile numbers is enabled for the contract, then an ApiStatusSubCode of 200.1 or , 200.2 or 200.3 will be included in the response, as described above.
...