# Phone Number Verification

The goal of this process is to verify User’s mobile number. If successful, Client acquires a first authentication factor allowing him to access onboarding APIs (including Get User State). 

{% hint style="info" %}
**Note:** User must have the UK number
{% endhint %}

The verification shall start before onboarding and consists of two stages:

**1. Request sending a one time password (OTP) via SMS to User's phone**

The request must include the full phone number and `channel: sms`

## Request OTP

<mark style="color:green;">`POST`</mark> `https://api.kavoon.io/otp`

#### Request Body

| Name                                      | Type   | Description                             |
| ----------------------------------------- | ------ | --------------------------------------- |
| phone<mark style="color:red;">\*</mark>   |        | Full mobile number e.g.  "447401101801" |
| channel<mark style="color:red;">\*</mark> | String | Sending channel. Use "sms"              |

{% tabs %}
{% tab title="200: OK " %}

```xquery
{ }
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
  "errCode": "GENERAL_ERROR",
  "errText": "invalid Device-Id"
}
```

{% endtab %}
{% endtabs %}

**2. Verify OTP and receive authentication token**

## Verify OTP

<mark style="color:green;">`POST`</mark> `https://api.kavoon.io/auth/token`

In case of successful verification, Client gets an `access_token`

#### Request Body

| Name                                          | Type   | Description                            |
| --------------------------------------------- | ------ | -------------------------------------- |
| grant\_type<mark style="color:red;">\*</mark> | String | Request type. Pass "password"          |
| username<mark style="color:red;">\*</mark>    | String | Full mobile number e.g. "447401101801" |
| password<mark style="color:red;">\*</mark>    | String | Received OTP e.g. "5757"               |
| channel<mark style="color:red;">\*</mark>     | String | Sending channel. Use "sms"             |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "access_token": "f7bf9bcb493d45cb99164ba7653b2e0a",
  "token_type": "Bearer",
  "expires_in": 300,
  "refresh_token": "7b7b75b866814bd3bf14409b796894f0",
  "new_client": true
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
  "errCode": "BAD_REQUEST",
  "errText":"Check OTP exception"
}
```

{% endtab %}
{% endtabs %}

If success, Client will retrieve the first authentication factor and will be able to call the User State to start onboarding to find out what is the first step. If the password does not match, Client will receive the respective error.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kavoon.io/onboarding/phone-number-verification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.