POST api/bfg/v1/persons/username-recovery/request
Matches the person and sends the first email verification link. Every request with a valid mobile is counted for that brand and mobile before the person is matched, whether it matches or not. The attempt limit and lock window come from the brand profile UsernameRecoveryLockSettings (default LOCKED_HOURS=24;ATTEMPT=3). That many requests are allowed; the next one locks the mobile and its open person sessions for the lock window and returns 403 SESSION_LOCKED. A person who already completed recovery for the brand returns 403 REQUEST_NOT_ALLOWED. A locked person session returns 403 SESSION_LOCKED. An invalid mobile or other field error returns 400 FAILED and is not counted.
Request Information
URI Parameters
None.
Body Parameters
UsernameRecoveryRequest| Name | Description | Type | Additional information |
|---|---|---|---|
| brandId | integer |
Required |
|
| lastName | string |
Required String length: inclusive between 0 and 50 |
|
| dateOfBirth | date |
Required |
|
| mobileNumber | string |
Required String length: inclusive between 0 and 30 |
Request Formats
application/json, text/json
{
"brandId": 1,
"lastName": "sample string 2",
"dateOfBirth": "2026-11-17T11:17:46.7201544+11:00",
"mobileNumber": "sample string 4"
}
application/xml, text/xml
<UsernameRecoveryRequest xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TPP.B2B.Webservices2.Contracts2.BFG.UsernameRecovery"> <brandId>1</brandId> <dateOfBirth>2026-11-17T11:17:46.7201544+11:00</dateOfBirth> <lastName>sample string 2</lastName> <mobileNumber>sample string 4</mobileNumber> </UsernameRecoveryRequest>
Response Information
Resource Description
UsernameRecoveryResponse| Name | Description | Type | Additional information |
|---|---|---|---|
| isSuccess | boolean |
None. |
|
| uruid | globally unique identifier |
None. |
|
| emailVerification | UsernameRecoveryVerificationIssueResponse |
None. |
|
| errorCode | string |
None. |
|
| errorMessage | string |
None. |
Response Formats
application/json, text/json
{
"isSuccess": true,
"uruid": "93246550-66a4-437b-b4ab-a3e9a3fa60f1",
"emailVerification": {
"sentTo": "sample string 1",
"expiresAtUtc": "2026-11-17T11:17:46.7247607+11:00",
"issueCount": 3,
"issuesRemaining": 4,
"attemptCount": 5,
"attemptsRemaining": 6,
"cooldownSeconds": 7
},
"errorCode": "sample string 2",
"errorMessage": "sample string 3"
}
application/xml, text/xml
<UsernameRecoveryResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TPP.B2B.Webservices2.Contracts2.BFG.UsernameRecovery">
<emailVerification>
<attemptCount>5</attemptCount>
<attemptsRemaining>6</attemptsRemaining>
<cooldownSeconds>7</cooldownSeconds>
<expiresAtUtc>2026-11-17T11:17:46.7247607+11:00</expiresAtUtc>
<issueCount>3</issueCount>
<issuesRemaining>4</issuesRemaining>
<sentTo>sample string 1</sentTo>
</emailVerification>
<errorCode>sample string 2</errorCode>
<errorMessage>sample string 3</errorMessage>
<isSuccess>true</isSuccess>
<uruid>93246550-66a4-437b-b4ab-a3e9a3fa60f1</uruid>
</UsernameRecoveryResponse>
Error Response Information
Resource Description
UsernameRecoveryResponse| Name | Description | Type | Additional information |
|---|---|---|---|
| isSuccess | boolean |
None. |
|
| uruid | globally unique identifier |
None. |
|
| emailVerification | UsernameRecoveryVerificationIssueResponse |
None. |
|
| errorCode | string |
None. |
|
| errorMessage | string |
None. |
Error Response Formats
application/json, text/json
{
"isSuccess": true,
"uruid": "d4fd6e18-dfce-4044-b69e-dc75d2ce3924",
"emailVerification": {
"sentTo": "sample string 1",
"expiresAtUtc": "2026-11-17T11:17:46.7297597+11:00",
"issueCount": 3,
"issuesRemaining": 4,
"attemptCount": 5,
"attemptsRemaining": 6,
"cooldownSeconds": 7
},
"errorCode": "sample string 2",
"errorMessage": "sample string 3"
}
application/xml, text/xml
<UsernameRecoveryResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TPP.B2B.Webservices2.Contracts2.BFG.UsernameRecovery">
<emailVerification>
<attemptCount>5</attemptCount>
<attemptsRemaining>6</attemptsRemaining>
<cooldownSeconds>7</cooldownSeconds>
<expiresAtUtc>2026-11-17T11:17:46.7297597+11:00</expiresAtUtc>
<issueCount>3</issueCount>
<issuesRemaining>4</issuesRemaining>
<sentTo>sample string 1</sentTo>
</emailVerification>
<errorCode>sample string 2</errorCode>
<errorMessage>sample string 3</errorMessage>
<isSuccess>true</isSuccess>
<uruid>d4fd6e18-dfce-4044-b69e-dc75d2ce3924</uruid>
</UsernameRecoveryResponse>