Contract
SV2 API
Base URL https://api.sv2labs.com/v1. These routes are the contract. This build answers only the gateway health check. Prices are not part of the contract yet.
Routes
| Method | Path | Phase | Note |
|---|---|---|---|
| GET | /v1/lrn/lookup | 1 | One NANP number. |
| POST | /v1/lrn/bulk | 1 | Up to 1,000 numbers in the same response. |
| POST | /v1/lrn/jobs | 2 | Up to 1,000,000 numbers. Requires Idempotency-Key. |
| GET | /v1/lrn/jobs/{id} | 2 | Status for a job this customer owns. |
| GET | /v1/lrn/jobs | 2 | Recent jobs for this customer only. |
| GET | /v1/lrn/jobs/{id}/results.csv | 2 | Our file. Expires 7 days after completion. |
| GET | /v1/lrn/jobs/{id}/results.jsonl | 2 | Our file. Expires 7 days after completion. |
| GET | /v1/usage | 1 | Usage for the calling account. |
| GET | /v1/balance | 1 | Balance, once billing exists. |
Errors
| HTTP | Code | Message |
|---|---|---|
| 400 | invalid_tn | The phone number is not a valid NANP number. |
| 401 | invalid_key | The API key is missing, revoked, or unknown. |
| 402 | insufficient_balance | The account balance cannot cover this request. |
| 403 | plan_forbidden | The account plan does not allow this call. |
| 404 | not_found | Not found. |
| 409 | idempotency_conflict | This Idempotency-Key was already used with a different request. |
| 429 | rate_limited | Too many requests. See the Retry-After header. |
| 500 | internal_error | Internal error. |
| 502 | upstream_error | The lookup service failed. |
| 504 | upstream_timeout | The lookup service timed out. |
rate_limited also sends a Retry-After header. The body stays the envelope above.