Provider Email OTP Verification

When a provider user logs in without an email, an auto-generated placeholder email is assigned with is_fake_email: true.

This page documents the companion endpoints used to verify and bind the user's real email address.

---

1. Request Email Verification OTP

Sends a 6-digit numeric OTP verification code to the specified email address.

• Endpoint: /api/v1/auth/send-email-otp
• Method: POST
• Rate Limit: Throttled via otp-send middleware (1 request per cooldown period).

Headers

Header	Value	Required	Description
Partner-Access-Token	Base64 String	Yes	Partner B2B token.
Authorization	Bearer <token>	Optional*	Signed-in provider user's Sanctum token.
Content-Type	application/json	Yes
Accept	application/json	Yes

* If the Authorization bearer token is omitted, you must supply userId in the request body to identify the provider user.

Request Body

Parameter	Type	Required	Description
email	String	Yes	The real email address to verify.
userId	String | Integer	Optional*	Provider user ID. Required only if Authorization header is not provided.

Sample Request

{
  "email": "realuser@example.com"
}

Responses

Success Response (HTTP 200)

{
  "result": 1,
  "message": "Verification code has been sent."
}

Email Already Exists (HTTP 200)

Returned if the target email is already registered to another user under the same partner:

{
  "result": 0,
  "message": "email already exist"
}

Throttled / Rate Limited (HTTP 429)

Returned if a verification code was requested too frequently:

{
  "result": 0,
  "message": "Please wait 60 seconds before requesting another code."
}

Headers include Retry-After: <seconds>.

---

2. Verify Email OTP

Verifies the 6-digit OTP code, sets is_fake_email: false, updates the user's email, and sets email_verified_at.

• Endpoint: /api/v1/auth/verify-email-otp
• Method: POST

Headers

Header	Value	Required	Description
Partner-Access-Token	Base64 String	Yes	Partner B2B token.
Authorization	Bearer <token>	Optional*	Signed-in provider user's Sanctum token.
Content-Type	application/json	Yes
Accept	application/json	Yes

* If the Authorization bearer token is omitted, you must supply userId in the request body.

Request Body

Parameter	Type	Required	Description
email	String	Yes	The email address being verified.
code	String | Integer	Yes	The 6-digit numeric OTP code sent to the email.
userId	String | Integer	Optional*	Provider user ID. Required only if Authorization header is not provided.

Sample Request

{
  "email": "realuser@example.com",
  "code": "123456"
}

Responses

Success Response (HTTP 200)

{
  "result": 1,
  "message": "Email verified successfully.",
  "data": {
    "is_fake_email": false,
    "user": {
      "id": 42,
      "name": "John Doe",
      "email": "realuser@example.com",
      "is_fake_email": false,
      "has_real_email": true,
      "email_verified_at": "2026-09-14T12:00:00.000000Z",
      "is_active": true,
      "partner_id": 12
    }
  }
}

Invalid / Expired Code (HTTP 200)

{
  "result": 0,
  "message": "Invalid code & can you resend code."
}

Email Taken By Another User (HTTP 200)

{
  "result": 0,
  "message": "email already exist"
}