> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Password Reset

> Trigger a password-reset email for a customer account.

# Start Password Reset

Sends a password-reset email to the customer's registered email address. The email contains a one-time link that the customer can follow to set a new password. The portal calls this from the "Forgot your password?" flow on the sign-in page.

## Authentication

No authentication required. This is a public endpoint.

## Request Body

<ParamField body="email" type="string" required>
  The email address of the account for which the password reset should be triggered.
</ParamField>

<ParamField body="businessId" type="number">
  The numeric identifier of the location the customer belongs to. Providing this ensures the correct branded email template is used.
</ParamField>

## Response

Returns an `ActionConfirmation` envelope. The portal treats any successful response as confirmation that the email was sent — it does not reveal whether the email address is registered, to prevent enumeration attacks.

<ResponseField name="WasSuccessful" type="boolean">
  `true` when the reset email was dispatched (or when no account was found — the response is intentionally the same to prevent user enumeration).
</ResponseField>

<ResponseField name="Value" type="string | null">
  Usually `null`.
</ResponseField>

<ResponseField name="Status" type="number">
  HTTP-style status code mirrored in the body. `200` on success.
</ResponseField>

<ResponseField name="Message" type="string | null">
  Human-readable message. Usually `null` on success.
</ResponseField>

<ResponseField name="Errors" type="any">
  Validation errors. `null` on success.
</ResponseField>

## Example Response

```json theme={null}
{
  "WasSuccessful": true,
  "Value": null,
  "Status": 200,
  "Message": null,
  "Errors": null
}
```

## TypeScript Integration

```typescript theme={null}
import endpoints from '@/api/endpoints'

const url = endpoints.system.users.startPasswordReset
// => '/api/sys/users/startPasswordReset'

await httpClient.post(url, { email: userEmail, businessId })
```

## Usage in Portal

| Context                      | Source file                      |
| ---------------------------- | -------------------------------- |
| Forgot password page / modal | `src/views/auth/ForgotPassword/` |

## Error Responses

<ResponseField name="400 Bad Request" type="error">
  The email field is missing or the request body is malformed.
</ResponseField>

## Related Endpoints

| Method | Endpoint                               | Description                                           |
| ------ | -------------------------------------- | ----------------------------------------------------- |
| `POST` | `/api/sys/users/completePasswordReset` | Complete the reset flow with the token from the email |
| `POST` | `/api/token`                           | Sign in after completing the password reset           |
| `GET`  | `/api/sys/users/sendOtp`               | Send a one-time password for passwordless sign-in     |