VeloVerify quick start

Use VeloVerify to check whether a mobile number is reachable, identify the network that currently serves it, or submit up to 1,000 lookups for background processing.

Base address: https://verify.veloconnect.me

Before you start

Create an API key and secret in the VeloVerify dashboard. Keep both on your server. Never put them in browser or mobile-app code.

The protected calls in this VeloVerify section accept either of these methods:

API key: X-API-Key: YOUR_API_KEY.

Bearer access token: Authorization: Bearer YOUR_ACCESS_TOKEN.

Use one method per request. If both are supplied, the API key takes precedence. The examples below use a short-lived bearer token. The token exchange and refresh endpoints do not require either header.

Make your first lookup

Exchange your credentials

The answer contains access_token, refresh_token, token_type and expires_in. Store the tokens securely. Use the refresh token with POST /v1/auth/refresh before the access token expires.

Check a number

Write the mobile number with its country code and digits only.

The response says whether the number is valid and reachable and, when available, gives its country and network information. Use GET /v1/mnp/{number} when you need the network that currently serves a ported number.

Process a list in the background

Use the asynchronous calls when you do not need the answer in the same HTTP request.

Submit one number with POST /v1/async/hlr or POST /v1/async/mnp, or up to 1,000 numbers with POST /v1/async/batch.

Keep the returned task_id or batch_id.

Either poll GET /v1/async/tasks/{task_id} or GET /v1/async/batches/{batch_id}, or include an HTTPS webhook_url in the submission.

Stop polling when each task is completed or failed. A completed task carries its lookup result in result.

query_type is liveStatus for reachability and npq for number portability.

Errors and retries

401 means the credentials or token are missing, invalid or expired. Exchange or refresh the token and try again.

403 means the account cannot perform that operation.

422 means a path, query or JSON field is invalid. Read the detail array before changing the request.

429 means too many requests. Pause, then retry with exponential backoff and random jitter.

Retry a temporary 500 or 503 response with backoff. Do not automatically retry 400, 401, 403 or 422 without correcting the request.

Limits can vary by account. Do not hard-code a request rate that has not been confirmed for your account.

Reference

Every operation, request field and response schema is in this VeloVerify section.

The machine-readable description is available at https://verify.veloconnect.me/openapi.json.

Keep your own reference value on a lookup when you need to match the result to a customer or job in your system.

VeloVerify quick start

Before you start#

Make your first lookup#

Process a list in the background#

Errors and retries#

Reference#

Before you start

Make your first lookup

Process a list in the background

Errors and retries

Reference