# Getting started

Number Validation is CM.com's API for verifying and enriching phone number data. Currently it allows checking and retrieving the latest data of a phone number. Such as its validity, country, operator, active status, and ported status.

It is used exclusively through the API.

For complete technical documentation with specifications for all field types, <<glossary:JSON>> objects, and methods, you can consult our complete API reference: [API reference](https://developers.cm.com/verification/reference/create_check)

If you need technical assistance, please [contact us](https://www.cm.com/contact/).

More information on testing with dummy data can be found in [Sandbox](https://developers.cm.com/verification/docs/number-validation-sandbox)

# Authentication

Before you can start using the API, you need API credentials. Credentials consist of a key ID and a secret. Contact your account manager to get production credentials. Credentials should be kept secret.

To authenticate you need to use your credentials to generate a <<glossary:JWT>> <<glossary:Bearer token>>. The [JWT token](https://jwt.io/introduction/) has to be generated using the `HS256` algorithm and your credentials. This JWT has to contain the following attributes: `iat`, `nbf`, and `exp` in the payload, as well as the attribute `kid` in the header of the JWT. This `kid` attribute needs to contain the Key ID of your credentials.

The generated token needs to be passed via the HTTP Authorization header:

```
Authorization: Bearer GENERATED_TOKEN_HERE
```

There are many libraries available for different programming languages that can help you to generate a JWT. See the Libraries tab on <https://jwt.io>.

**Example**

Assuming we want to create a token that is valid for 60 seconds and we have received the following credentials:

Key ID: `3b438437-04a4-40bb-8389-54bb02766fba`\
Secret: `AC4Etykn7jusGR5FwLDAtILtQbiQbTMKedP31szXg4WlSbjGEXyNMZ`

We need to create a JWT with the following properties:

JWT header:

```json
{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "3b438437-04a4-40bb-8389-54bb02766fba"
}
```

JWT payload:

```json
{
    "iat": 1704067200,
    "nbf": 1704067200,
    "exp": 1704067260
}
```

* `iat`: the time when the token was generated.
* `nbf`: the time after which the token is valid, usually equal to `iat`.
* `exp`: the time when the token will expire.

> 📘
>
> Make sure these are UNIX timestamps in seconds

This results in the following token:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjNiNDM4NDM3LTA0YTQtNDBiYi04Mzg5LTU0YmIwMjc2NmZiYSJ9.eyJpYXQiOjE3MDQwNjcyMDAsIm5iZiI6MTcwNDA2NzIwMCwiZXhwIjoxNzA0MDY3MjYwfQ.lTzOd4cKOan2rwL4fHjwOffc0dp3pwYjDdl4uM1WluU
```

Add this token to the `Authorization` header in the API request.

```
Authorization: Bearer GENERATED_TOKEN_HERE
```

> The <https://jwt.io> website provides a way to inspect or validate JWT tokens.