{ "openapi": "3.1.0", "info": { "title": "Phone Validator API", "version": "5.0.0", "summary": "Validate phone numbers and identify their line type, carrier and location.", "description": "Look up a phone number with `POST /v5/lookups`. The response states whether\nthe number is valid and gives its country, region, line type, carrier and\nport status.\n\n## Authentication\n\nSend your API key as a bearer token:\n\n```\nAuthorization: Bearer \n```\n\nLive keys start with `pv_live_` and test keys with `pv_test_` (see\n[Test mode](#test-mode)).\n\n## Errors\n\nErrors return a non-2xx status and a body of the form\n`{\"error\": {\"code\": \"...\", \"message\": \"...\"}}`. Match on `code`; `message`\nis for people. Every response has a `Request-Id` header for support.\n\n## Rate limits\n\nEach account may make 25 requests per second across all of its keys.\nHigher limits are available on request. `RateLimit-Limit`,\n`RateLimit-Remaining` and `RateLimit-Reset` report the current window; a\nrequest over the limit receives `429 rate_limited` with `Retry-After`.\n\n## Versioning\n\nv5 changes only by addition. New fields and new `line_type` and\n`invalid_reason` values may appear: ignore unknown fields, treat an unknown\n`line_type` as `unknown` and an unknown `invalid_reason` as invalid.\nExisting fields keep their name, type and meaning.\n", "contact": { "name": "Phone Validator support", "url": "https://www.phonevalidator.com" } }, "servers": [ { "url": "https://api.phonevalidator.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Lookups", "description": "Look up one phone number." }, { "name": "Account", "description": "Balance, limits and usage of the key's account." }, { "name": "Test mode", "description": "Test keys (`pv_test_...`) return fixed responses for the numbers below\nand are never billed. Any other number returns `400 test_mode_number`.\nTest responses set `test_mode: true` and count toward the account's rate\nlimit.\n\nThe numbers are in the reserved 555-01XX range:\n\n| Number | Result |\n| --- | --- |\n| `+12025550100` | Valid, `mobile`, `T-MOBILE`, `ported: false` |\n| `+12025550101` | Valid, `mobile`, `T-MOBILE`, `ported: true` |\n| `+12025550102` | Valid, `landline`, `VERIZON` |\n| `+12025550103` | Valid, `voip`, `BANDWIDTH.COM` |\n| `+18005550100` | Valid, `toll_free` |\n| `+12025550104` | Valid, `unknown` line type |\n| `+1202555010` | Invalid, `too_short` |\n| `+11115550100` | Invalid, `invalid_area_code` |\n| `+12025550106` | Invalid, `not_in_service` |\n| `not a number` | Invalid, `not_a_phone_number` |\n| `+12025550190` | `402 insufficient_funds` |\n| `+12025550191` | `403 account_on_hold` |\n| `+12025550192` | `429 rate_limited` |\n| `+12025550193` | `503 lookup_unavailable` |\n\nValid test numbers report `city: \"WASHINGTON\"` and `region: \"DC\"` (`null`\nfor the toll-free number).\n" } ], "paths": { "/v5/lookups": { "post": { "operationId": "createLookup", "tags": [ "Lookups" ], "summary": "Look up a phone number", "description": "Validates a phone number and returns its details. An invalid number\nreturns `200` with `valid: false` and an `invalid_reason`.\n\nSpaces, `()`, `-` and `.` are ignored, and a leading `+` or `00` marks\nan international number. Other numbers are read in `default_country`,\nelse in the first of `allowed_countries`, else as a North American\nnumber and then as an international one.\n\nWith an `Idempotency-Key`, the first successful response is stored for\n24 hours for your API key. The same key and body return the stored\nresponse with `Idempotent-Replayed: true`, without a second charge. The\nsame key returns `409 idempotency_in_progress` while the first request\nis running and `422 idempotency_key_reused` with a different body.\nErrors are not stored, so a failed request can be retried with the same\nkey.\n", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique value per lookup, such as a UUID.\n", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "4c6f8e0a-1b7d-4f5e-9a3c-2d8e7b6a5f10" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupRequest" }, "examples": { "plain": { "summary": "A number in a common format", "value": { "phone_number": "(702) 927-0000" } }, "international": { "summary": "A number read in a country", "value": { "phone_number": "020 7946 0000", "default_country": "GB" } }, "allowed_countries": { "summary": "Only accept numbers from some countries", "value": { "phone_number": "+12025550100", "allowed_countries": [ "US", "CA" ] } }, "test_key_number": { "summary": "A test number, with a test key", "value": { "phone_number": "+12025550101" } } } } } }, "responses": { "200": { "description": "The lookup result.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" }, "examples": { "valid_mobile": { "$ref": "#/components/examples/ValidMobile" }, "invalid_number": { "$ref": "#/components/examples/InvalidNumber" }, "test_mode": { "$ref": "#/components/examples/TestModeAnswer" } } } } }, "400": { "$ref": "#/components/responses/LookupBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/LookupMethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v5/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Read the account", "description": "Returns the account's balance, price, rate limit, auto-refill and\nbalance-alert settings, and usage for the current month. Settings are\nmanaged in the dashboard. Not billed; counts toward the rate limit.\n", "responses": { "200": { "description": "The account.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" }, "examples": { "account": { "summary": "A live account with auto-refill", "value": { "balance": "41.2760", "price_per_lookup": "0.0040", "trial_lookups_remaining": 0, "rate_limit_per_second": 25, "auto_refill_enabled": true, "auto_refill_threshold": "5.0000", "auto_refill_amount": "25.0000", "balance_alert_enabled": false, "balance_alert_threshold": "5.0000", "lookups_this_month": 18234, "spent_this_month": "72.9360", "test_mode": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/AccountMethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (pv_live_... or pv_test_...)", "description": "Your API key.\n" } }, "headers": { "RequestId": { "description": "Identifies this request. Quote it to support.", "schema": { "type": "string" } }, "CacheControl": { "description": "Always `no-store`.", "schema": { "type": "string", "const": "no-store" } }, "RateLimitLimit": { "description": "Requests allowed per second.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimitRemaining": { "description": "Requests left in the current second.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitReset": { "description": "Seconds until the limit refills.", "schema": { "type": "integer", "minimum": 0 } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "WwwAuthenticate": { "description": "The authentication scheme, `Bearer`. Sent when the key is missing or\nnot valid.\n", "schema": { "type": "string" } }, "IdempotentReplayed": { "description": "`true` when the response is the stored response for this\n`Idempotency-Key`. Absent otherwise.\n", "schema": { "type": "string", "const": "true" } } }, "schemas": { "Money": { "type": "string", "pattern": "^\\d+\\.\\d{4}$", "description": "A USD amount as a decimal string with four decimal places.", "examples": [ "0.0040" ] }, "Country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "An ISO 3166-1 alpha-2 country code, such as `GB`." }, "LookupRequest": { "type": "object", "additionalProperties": false, "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string", "maxLength": 64, "description": "The phone number, in any common format.\n" }, "default_country": { "$ref": "#/components/schemas/Country", "description": "The country used to read a number written without `+` or `00`, as\nan ISO 3166-1 alpha-2 code such as `GB`. Numbers with `+` are read\nas written. Must be in `allowed_countries` when both are sent.\n" }, "allowed_countries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Country" }, "description": "The countries to accept, as ISO codes such as `[\"US\",\"CA\"]`. A\nnumber from any other country returns `valid: false` with\n`invalid_reason: \"country_not_allowed\"`. Without `default_country`,\nthe first country is used to read numbers written without `+`.\n" } } }, "LookupResponse": { "type": "object", "description": "The lookup result. Every field is present in every response; a value\nthat does not apply is `null`.\n", "required": [ "phone_number", "valid", "invalid_reason", "format_national", "format_international", "country", "region", "city", "time_zone", "line_type", "carrier", "ported", "cost", "balance", "test_mode" ], "properties": { "phone_number": { "type": [ "string", "null" ], "pattern": "^\\+[1-9]\\d{1,14}$", "description": "The number in E.164 format. `null` when the input cannot be read as\na phone number.\n" }, "valid": { "type": "boolean", "description": "`true` when the number is in an assigned, in-service range of its\nnumbering plan.\n" }, "invalid_reason": { "type": [ "string", "null" ], "enum": [ "not_a_phone_number", "too_short", "too_long", "invalid_area_code", "invalid_prefix", "not_in_service", "invalid_number", "country_not_allowed", null ], "description": "Why the number is invalid; `null` when it is valid. New values may\nbe added; treat an unknown value as invalid.\n\n| Value | Meaning |\n| --- | --- |\n| `not_a_phone_number` | Empty, only punctuation, letters, an extension, or other characters |\n| `too_short` | Fewer digits than the country's numbers have |\n| `too_long` | More digits than the country's numbers have |\n| `invalid_area_code` | Area code not in service, or not for customer numbers |\n| `invalid_prefix` | Exchange not valid or not assigned |\n| `not_in_service` | Thousands block or exchange not in service |\n| `invalid_number` | International number that is not valid or has no record |\n| `country_not_allowed` | Outside the request's `allowed_countries` |\n" }, "format_national": { "type": [ "string", "null" ], "description": "National display format. `null` for an invalid number." }, "format_international": { "type": [ "string", "null" ], "description": "International display format. `null` for an invalid number." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 code. US territories have their own codes (`PR`,\n`GU`, `VI`, `AS`, `MP`).\n" }, "region": { "type": [ "string", "null" ], "description": "US state or Canadian province code, such as `NV` or `ON`.\n" }, "city": { "type": [ "string", "null" ], "description": "The locality where the number was issued." }, "time_zone": { "type": [ "string", "null" ], "description": "IANA time zone where the number was issued. `null` when the area\nspans more than one zone.\n" }, "line_type": { "type": [ "string", "null" ], "enum": [ "mobile", "landline", "voip", "toll_free", "unknown", null ], "description": "`mobile`, `landline`, `voip`, `toll_free` or `unknown`; `null` for\nan invalid number. New values may be added; treat an unknown value\nas `unknown`.\n\n- `voip`: served by a VoIP or wholesale carrier, including app\n numbers such as Google Voice.\n- `unknown`: the line could not be classified, as with some\n premium-rate and pager numbers.\n" }, "carrier": { "type": [ "string", "null" ], "description": "The number's current carrier, or the carrier its number block is\nassigned to. For a number on a wholesale VoIP network, the company\nbehind it, such as `GOOGLE VOICE`.\n" }, "ported": { "type": [ "boolean", "null" ], "description": "Whether the number has been ported to another carrier. `null` where\nport data is not available, including Canada.\n" }, "cost": { "$ref": "#/components/schemas/Money", "description": "Amount billed for this request, in USD." }, "balance": { "$ref": "#/components/schemas/Money", "description": "Available balance after this request, in USD. `GET /v5/account`\nreturns the exact balance while other lookups are in progress.\n" }, "test_mode": { "type": "boolean", "description": "`true` for a request made with a test key.\n" } } }, "AccountResponse": { "type": "object", "description": "The account behind the key. Every field is always present.", "required": [ "balance", "price_per_lookup", "trial_lookups_remaining", "rate_limit_per_second", "auto_refill_enabled", "auto_refill_threshold", "auto_refill_amount", "balance_alert_enabled", "balance_alert_threshold", "lookups_this_month", "spent_this_month", "test_mode" ], "properties": { "balance": { "$ref": "#/components/schemas/Money", "description": "Available balance in USD, including lookups in progress.\n" }, "price_per_lookup": { "$ref": "#/components/schemas/Money", "description": "Price of one lookup for this account, in USD." }, "trial_lookups_remaining": { "type": "integer", "minimum": 0, "description": "Free lookups remaining." }, "rate_limit_per_second": { "type": "integer", "minimum": 1, "description": "Requests per second allowed for the account." }, "auto_refill_enabled": { "type": "boolean", "description": "Whether auto-refill is on." }, "auto_refill_threshold": { "$ref": "#/components/schemas/Money", "description": "Balance that triggers auto-refill, in USD." }, "auto_refill_amount": { "$ref": "#/components/schemas/Money", "description": "Amount added by auto-refill, in USD." }, "balance_alert_enabled": { "type": "boolean", "description": "Whether the low-balance email is on." }, "balance_alert_threshold": { "$ref": "#/components/schemas/Money", "description": "Balance that triggers the low-balance email, in USD." }, "lookups_this_month": { "type": "integer", "minimum": 0, "description": "Billed lookups in the current UTC calendar month." }, "spent_this_month": { "$ref": "#/components/schemas/Money", "description": "Amount billed in the current UTC calendar month, in USD." }, "test_mode": { "type": "boolean", "description": "`true` for a request made with a test key." } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "description": "The shape of every non-2xx response.", "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable, machine-readable code." }, "message": { "type": "string", "description": "A human-readable explanation." } } } } } }, "responses": { "LookupBadRequest": { "description": "The request is malformed.\n\n- `invalid_request`: a field is missing, unknown or out of range, such\n as `phone_number` over 64 characters, a country that is not an ISO\n 3166-1 alpha-2 code, an empty `allowed_countries`, a\n `default_country` outside `allowed_countries`, or an\n `Idempotency-Key` that is blank or over 255 characters.\n- `invalid_json`: the body is not a JSON object.\n- `test_mode_number`: a test key sent a number that is not a test\n number.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "invalid_json", "test_mode_number" ] } } } } } ] }, "examples": { "invalid_request": { "summary": "A field is missing or wrong", "value": { "error": { "code": "invalid_request", "message": "phone_number is required and must be a string." } } }, "invalid_json": { "summary": "The body is not JSON", "value": { "error": { "code": "invalid_json", "message": "The request body is not valid JSON." } } }, "test_mode_number": { "summary": "A test key sent a number outside the test set", "value": { "error": { "code": "test_mode_number", "message": "Test keys accept only the documented test numbers." } } } } } } }, "Unauthorized": { "description": "The API key is missing, invalid or revoked, or was sent in the URL.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/WwwAuthenticate" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "missing_key", "invalid_key", "key_in_url" ] } } } } } ] }, "examples": { "missing_key": { "summary": "No bearer token", "value": { "error": { "code": "missing_key", "message": "Send your API key as Authorization: Bearer ." } } }, "invalid_key": { "summary": "Unknown or revoked key", "value": { "error": { "code": "invalid_key", "message": "This API key is not valid or was revoked." } } }, "key_in_url": { "summary": "The key was in the query string", "value": { "error": { "code": "key_in_url", "message": "Send the API key in the Authorization header." } } } } } } }, "PaymentRequired": { "description": "The balance does not cover the lookup. Not billed.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_funds" ] } } } } } ] }, "examples": { "insufficient_funds": { "value": { "error": { "code": "insufficient_funds", "message": "This lookup costs $0.0040; $0.0012 is available." } } } } } } }, "Forbidden": { "description": "The account cannot make requests: `account_inactive`, `api_disabled`\n(API access is off for the account) or `account_on_hold` (contact\nsupport).\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_inactive", "api_disabled", "account_on_hold" ] } } } } } ] }, "examples": { "account_inactive": { "value": { "error": { "code": "account_inactive", "message": "This account is not active." } } }, "api_disabled": { "value": { "error": { "code": "api_disabled", "message": "API access is turned off for this account." } } }, "account_on_hold": { "value": { "error": { "code": "account_on_hold", "message": "This account is on hold. Contact support." } } } } } } }, "NotFound": { "description": "No such endpoint under `/v5/`.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "No such endpoint." } } } } } } }, "LookupMethodNotAllowed": { "description": "Method not allowed. Lookups use `POST`.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Allow": { "description": "The method this endpoint accepts.", "schema": { "type": "string", "const": "POST" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "method_not_allowed" ] } } } } } ] }, "examples": { "method_not_allowed": { "value": { "error": { "code": "method_not_allowed", "message": "Use POST for this endpoint." } } } } } } }, "AccountMethodNotAllowed": { "description": "Method not allowed. The account uses `GET`.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Allow": { "description": "The method this endpoint accepts.", "schema": { "type": "string", "const": "GET" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "method_not_allowed" ] } } } } } ] }, "examples": { "method_not_allowed": { "value": { "error": { "code": "method_not_allowed", "message": "Use GET for this endpoint." } } } } } } }, "Conflict": { "description": "A request with this `Idempotency-Key` is in progress. Retry with the\nsame key after `Retry-After`.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "idempotency_in_progress" ] } } } } } ] }, "examples": { "idempotency_in_progress": { "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still running." } } } } } } }, "UnsupportedMediaType": { "description": "The body must be JSON, sent with `Content-Type: application/json`.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unsupported_media_type" ] } } } } } ] }, "examples": { "unsupported_media_type": { "value": { "error": { "code": "unsupported_media_type", "message": "Send a JSON body with Content-Type: application/json." } } } } } } }, "UnprocessableEntity": { "description": "This `Idempotency-Key` was used with a different request body.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "idempotency_key_reused" ] } } } } } ] }, "examples": { "idempotency_key_reused": { "value": { "error": { "code": "idempotency_key_reused", "message": "This Idempotency-Key was used with a different request." } } } } } } }, "TooManyRequests": { "description": "The account's rate limit is exceeded. Not billed; retry after\n`Retry-After`.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "Too many requests. Retry after the Retry-After seconds." } } } } } } }, "InternalError": { "description": "An internal error. Retry with the same `Idempotency-Key`; a request that\nwas billed before the error is not billed again.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "examples": { "internal_error": { "value": { "error": { "code": "internal_error", "message": "Internal error. Retry with the same Idempotency-Key." } } } } } } }, "ServiceUnavailable": { "description": "Carrier data is temporarily unavailable. Not billed; retry after\n`Retry-After`.\n", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "lookup_unavailable" ] } } } } } ] }, "examples": { "lookup_unavailable": { "value": { "error": { "code": "lookup_unavailable", "message": "The carrier lookup is unavailable; retry shortly." } } } } } } } }, "examples": { "ValidMobile": { "summary": "A valid mobile number", "value": { "phone_number": "+17029270000", "valid": true, "invalid_reason": null, "format_national": "(702) 927-0000", "format_international": "+1 702-927-0000", "country": "US", "region": "NV", "city": "LAS VEGAS", "time_zone": "America/Los_Angeles", "line_type": "mobile", "carrier": "T-MOBILE", "ported": true, "cost": "0.0040", "balance": "41.2760", "test_mode": false } }, "InvalidNumber": { "summary": "An invalid number", "value": { "phone_number": "+11115550100", "valid": false, "invalid_reason": "invalid_area_code", "format_national": null, "format_international": null, "country": "US", "region": null, "city": null, "time_zone": null, "line_type": null, "carrier": null, "ported": null, "cost": "0.0040", "balance": "41.2720", "test_mode": false } }, "TestModeAnswer": { "summary": "A test-mode response", "value": { "phone_number": "+12025550101", "valid": true, "invalid_reason": null, "format_national": "(202) 555-0101", "format_international": "+1 202-555-0101", "country": "US", "region": "DC", "city": "WASHINGTON", "time_zone": "America/New_York", "line_type": "mobile", "carrier": "T-MOBILE", "ported": true, "cost": "0.0000", "balance": "41.2760", "test_mode": true } } } } }