# Verify a practitioner's phone OTP

Operation ID: `provider.verifySms`

Confirm the SMS OTP sent by provider.updatePhone and mark the Cognito account's phone number as verified. The OTP is checked against the authenticated caller's own Cognito subject (from the Bearer JWT), not against {practitioner_id} in the path.

## Public method

`verifySms`

Signature: `provider.verifySms(fhirPractitionerId, request)`

Return type: `Promise<VerifiedResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /practitioners/{practitioner_id}/verify-sms`

## Path parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `practitioner_id` | `string` | Yes |  |  |  | No |  |

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`provider.VerifySmsRequest`](../models/provider.VerifySmsRequest.md) | Yes |  |  |  | No |  |

Request model: [`provider.VerifySmsRequest`](../models/provider.VerifySmsRequest.md)

## Request example

```json
{
  "otp": "123456"
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`provider.VerifySmsResponse`](../models/provider.VerifySmsResponse.md) | application/json | Phone verified |

## Success response examples

### 200

```json
{
  "verified": true
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Required fields are missing, or the OTP is invalid/expired |
| `401` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |

## Error examples

### 400 — The OTP is incorrect or expired (sanitized example)

```json
{
  "error": "Invalid or expired OTP"
}
```

### 400 — Required field is missing

```json
{
  "error": "otp is required"
}
```

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { PractitionerSmsVerificationRequest } from "@healthcloudai/hc-sdk";
```

```ts
const fhirPractitionerId = "<FHIR_PRACTITIONER_ID>";

const request = {
  "otp": "123456"
};

const result = await provider.verifySms(fhirPractitionerId, request);
```

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"otp":"123456"}' \
  'https://dev-api-provider.health.cloud/practitioners/%3CPRACTITIONER_ID%3E/verify-sms'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.