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

Sample:
{
  "brandId": 1,
  "lastName": "sample string 2",
  "dateOfBirth": "2026-11-17T11:17:46.7201544+11:00",
  "mobileNumber": "sample string 4"
}

application/xml, text/xml

Sample:
<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
NameDescriptionTypeAdditional information
isSuccess

boolean

None.

uruid

globally unique identifier

None.

emailVerification

UsernameRecoveryVerificationIssueResponse

None.

errorCode

string

None.

errorMessage

string

None.

Response Formats

application/json, text/json

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

Sample:
<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
NameDescriptionTypeAdditional 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

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

Sample:
<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>