# SMS Validation API

Backend API for phone number validation via SMS and other channels. This API allows you to validate phone numbers
by sending SMS verification codes and verifying them. 


## Rate Limiting
The API implements multi-level rate limiting per account, country, and phone number.

## Offline Proof Verification
If your tenant has a `verificationSecret` configured, the API returns an HMAC proof in the 
validation response. This proof can be verified offline without calling the API (see `/v1/verify-proof` endpoint).


Version: 1.0.0

## Servers

Production server
```
https://verify-api.smsmanager.com
```

## Security

### ApiKeyAuth

Your tenant's API key

Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[SMS Validation API](https://api-ref.smsmanager.com/_bundle/openapi/cs/verify/verifyapi_v1.yaml)

## Validation

Phone number validation operations

### Verify HMAC proof

 - [POST /v1/verify-proof](https://api-ref.smsmanager.com/openapi/cs/verify/verifyapi_v1/validation/verifyproof.md): Verifies an HMAC proof for phone validation without storing any state.
This endpoint is useful for backend verification when you have all the validation data
but want SMS Manager to verify the HMAC calculation.

This endpoint not requires authentication - proof itself is the authentication.

All of these data are returned by the /v1/validations endpoint.

Note: This only works for accounts with a verificationSecret configured.

### Start phone validation

 - [POST /v1/validations](https://api-ref.smsmanager.com/openapi/cs/verify/verifyapi_v1/validation/startvalidation.md): Initiates a new phone number validation by sending an message with a verification code.
Returns a validation token that must be used for subsequent verification.

### Verify code

 - [POST /v1/validations/{token}/verify](https://api-ref.smsmanager.com/openapi/cs/verify/verifyapi_v1/validation/verifycode.md): Verifies the code entered by the user. On successful verification, returns all data needed
for backend verification including the phone number, token, code, timestamp, and HMAC proof 
(if account has verificationSecret configured).

The number of attempts is limited based on account configuration (default: 6).

### Verify proof (optional)

 - [PATCH /v1/validations/{token}](https://api-ref.smsmanager.com/openapi/cs/verify/verifyapi_v1/validation/verifyproof.md): Optional endpoint to verify a proof hash from a previous successful validation.
This can be used to confirm that a validation was completed successfully.