{"openapi":"3.0.3","info":{"title":"Phone Validation API","version":"1.0.0","description":"The **Phone Validation API** checks whether a phone number is valid and returns what is known about it: the normalized E.164 form, national format, country, line type, carrier, region and time zones. Send numbers in **E.164** format (`+38766000111`), or in national format together with a `region` code.\n\n| | |\n|---|---|\n| **Base URL** | `https://api.omaxtelecom.com/numbers` |\n| **Authentication** | Bearer access token — [how to get one](/getting-started) |\n| **Postman** | [Collection](/postman/phone-validation/phone-validation.postman_collection.json) · [Environment](/postman/phone-validation/phone-validation.postman_environment.json) |\n| **AI assistants** | [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdeveloper.omaxtelecom.com%2Fphone-validation-api.md%20and%20help%20me%20integrate%20the%20OmaxTelecom%20Phone%20Validation%20API%20into%20my%20application.%20Ask%20me%20which%20language%20I%20use%20first.) · [Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdeveloper.omaxtelecom.com%2Fphone-validation-api.md%20and%20help%20me%20integrate%20the%20OmaxTelecom%20Phone%20Validation%20API%20into%20my%20application.%20Ask%20me%20which%20language%20I%20use%20first.) · [Markdown](/phone-validation-api.md) · [MCP server](/ai) |\n\n> [!TIP]\n> **Try it here:** enter your Client ID and Client Secret in the **Authentication** box, click **Authorize**, then use **Test Request** on any endpoint.\n\n## What you can do\n\n| Task | Endpoint | Description |\n|------|----------|-------------|\n| **Validate a number** | `POST /phone-validation` | Validate one phone number |\n| **Bulk validation** | `POST /phone-validation/bulk` | Start an asynchronous bulk job for many numbers |\n| **Bulk job status** | `GET /phone-validation/bulk/{job_id}` | Progress and results of a bulk job |\n| **Your price** | `GET /phone-validation/pricing` | Whether the API is enabled for you, and your price per validation |\n| **Usage history** | `GET /phone-validation/transactions` | Every validation you made, with what it cost |\n| **Bulk jobs** | `GET /phone-validation/jobs` | All your bulk jobs and their results |\n| **Health** | `GET /phone-validation/health` | Service availability (no token needed) |\n\n## Quick start\n\n1. **Enable the API.** Phone validation must be enabled for your organization in [OmaxTelecom Console](https://console.omaxtelecom.com).\n2. **Get a token** — see [Getting started](/getting-started).\n3. **Validate a number:**\n\n```bash\ncurl -X POST \"https://api.omaxtelecom.com/numbers/phone-validation?phone_number=%2B38766000111&locale=en\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"valid\": true,\n    \"possible\": true,\n    \"phone_number\": \"+38766000111\",\n    \"national_format\": \"066 000-111\",\n    \"country_code\": \"BA\",\n    \"calling_code\": \"387\",\n    \"number_type\": \"MOBILE\",\n    \"geocoder\": {\n      \"description\": \"Bosnia and Herzegovina\",\n      \"locale\": \"en\"\n    },\n    \"time_zones\": [\"Europe/Sarajevo\"],\n    \"carrier\": {\n      \"name\": \"BH Telecom\",\n      \"locale\": \"en\"\n    }\n  }\n}\n```\n\n> [!TIP]\n> In a query string, `+` must be sent as `%2B`, otherwise it is read as a space.\n\n## Authentication\n\nSend an access token on every request except `GET /phone-validation/health`:\n\n```http\nAuthorization: Bearer <access_token>\n```\n\nGet the token from `POST https://api.omaxtelecom.com/auth/token` with your Console `client_id` and `client_secret`. [Getting started](/getting-started) shows how, with code samples.\n\nMachine-to-machine clients whose token has no `organization` claim also send:\n\n```http\nX-Organization-Id: <organization_id>\n```\n\n## The validation result\n\n| Field | Description |\n|-------|-------------|\n| `valid` | The number is valid for its region |\n| `possible` | The number has a plausible length, even if it is not valid |\n| `phone_number` | Normalized E.164 number |\n| `national_format` | Number formatted the national way |\n| `country_code` | ISO 3166-1 alpha-2 country code |\n| `calling_code` | International calling code |\n| `number_type` | Line type, for example `MOBILE` or `FIXED_LINE` |\n| `geocoder` | Geographic description of the number |\n| `time_zones` | Time zones of the number |\n| `carrier` | Carrier name, when known |\n\n## Responses\n\nSuccessful responses wrap the result in `data`:\n\n```json\n{ \"success\": true, \"data\": { ... } }\n```\n\nErrors return `success: false` with a code you can branch on:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"The phone number field format is invalid.\"\n  }\n}\n```\n\n## Examples\n\n### Validate a national number\n\nSend the number without the country prefix and add `region`:\n\n```bash\ncurl -X POST \"https://api.omaxtelecom.com/numbers/phone-validation?phone_number=066000111&region=BA&locale=en\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\nThe result is the same as for `+38766000111` in the quick start.\n\n### Bulk validation\n\nBulk validation runs in the background. Start a job, then poll it until `status` is `completed`.\n\n**1. Start the job** — the answer is `202 Accepted` with a `job_id`:\n\n```bash\ncurl -X POST \"https://api.omaxtelecom.com/numbers/phone-validation/bulk\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"locale\": \"en\",\n    \"validations\": [\n      {\"phone_number\": \"+38766000111\"},\n      {\"phone_number\": \"066000111\", \"region\": \"BA\"}\n    ]\n  }'\n```\n\n```json\n{ \"success\": true, \"data\": { \"job_id\": \"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c\" } }\n```\n\n**2. Poll the job:**\n\n```bash\ncurl \"https://api.omaxtelecom.com/numbers/phone-validation/bulk/9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"job_id\": \"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c\",\n    \"status\": \"processing\",\n    \"total_count\": 2,\n    \"processed_count\": 1,\n    \"failed_count\": 0,\n    \"items\": [\n      {\n        \"phone_number\": \"+38766000111\",\n        \"region\": null,\n        \"locale\": \"en\",\n        \"status\": \"completed\",\n        \"result\": {\n          \"valid\": true,\n          \"possible\": true,\n          \"phone_number\": \"+38766000111\",\n          \"national_format\": \"066 000-111\",\n          \"country_code\": \"BA\",\n          \"calling_code\": \"387\",\n          \"number_type\": \"MOBILE\"\n        },\n        \"error\": null\n      },\n      {\n        \"phone_number\": \"066000111\",\n        \"region\": \"BA\",\n        \"locale\": \"en\",\n        \"status\": \"pending\",\n        \"result\": null,\n        \"error\": null\n      }\n    ]\n  }\n}\n```\n\n### Health check\n\n```bash\ncurl \"https://api.omaxtelecom.com/numbers/phone-validation/health\"\n```\n\n```json\n{ \"ok\": true, \"timestamp\": \"2026-08-20T16:42:00+00:00\" }\n```\n\n## Pricing and history\n\n**Your price** — `GET /phone-validation/pricing`:\n\n```json\n{ \"success\": true, \"data\": { \"enabled\": true, \"price_per_validation\": \"0.020000\", \"currency\": \"EUR\" } }\n```\n\n**Usage history** — `GET /phone-validation/transactions` lists every validation you made, newest first, with the amount billed. Filter by `from`, `to`, `cached`, `phone_number`, `region`; page with `page` and `per_page`. `GET /phone-validation/transactions/{id}` returns one transaction.\n\n**Bulk jobs** — `GET /phone-validation/jobs` lists your bulk jobs (filter by `status`, `from`, `to`); `GET /phone-validation/jobs/{id}` returns one job with its items.\n\n## Billing\n\nWhen your organization's `price_per_validation` is above zero, each successful validation is charged from your Console wallet — repeat validations of the same number too.\n\n## Errors\n\n| HTTP status | Error code | What to do |\n|-------------|------------|------------|\n| `401` | — | Get a new access token |\n| `402` | `INSUFFICIENT_BALANCE` | Top up your wallet in Console |\n| `403` | `PHONE_VALIDATION_DISABLED` | Ask support to enable phone validation for your organization |\n| `403` | `BILLING_NOT_CONFIGURED` | Billing is not set up for your organization — contact support |\n| `403` | `ORGANIZATION_NOT_FOUND` | Your organization is not registered — check `X-Organization-Id` or contact support |\n| `422` | `VALIDATION_ERROR` | Fix the request body or the phone number format |\n\n## Need help?\n\nEmail [support@omaxtelecom.com](mailto:support@omaxtelecom.com). Tell us which endpoint you called, when, and what the response was — including its `request_id` if it has one. Never send your Client Secret or access token."},"servers":[{"url":"https://api.omaxtelecom.com/numbers","description":"Production"}],"tags":[{"name":"Authentication","description":"Get the access token that every other request needs. [Getting started](/getting-started) has code samples and tips for handling tokens."},{"name":"Phone Validation"}],"security":[{"OmaxOAuth":[]},{"bearerAuth":[]}],"paths":{"/token":{"post":{"tags":["Authentication"],"summary":"Get an access token","operationId":"getAccessToken","description":"Exchange your **Client ID** and **Client Secret** for an access token. Every other request needs this token.\n\n1. Copy your Client ID and Client Secret from [OmaxTelecom Console](https://console.omaxtelecom.com).\n2. Call this endpoint with `grant_type=client_credentials`. The body is form-encoded, not JSON.\n3. Send the returned `access_token` on every request:\n   `Authorization: Bearer <access_token>`\n\nThis is the shared OmaxTelecom token endpoint: the same token works for every OmaxTelecom API.\n\n> [!TIP]\n> **Just testing?** Skip this call: enter your credentials in the **Authentication** box at the top of this page and click **Authorize**.\n\n> [!NOTE]\n> Tokens last `expires_in` seconds (usually 5 minutes). Reuse a token until it expires. On `401 Unauthorized`, get a new one and retry.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"default":"client_credentials","description":"Always `client_credentials`."},"client_id":{"type":"string","description":"Your Client ID from OmaxTelecom Console.","example":"your-client-id"},"client_secret":{"type":"string","format":"password","description":"Your Client Secret from OmaxTelecom Console. Keep it on your server — never put it in a browser or mobile app.","example":"your-client-secret"}}},"example":{"grant_type":"client_credentials","client_id":"your-client-id","client_secret":"your-client-secret"}}}},"responses":{"200":{"description":"Token issued.","content":{"application/json":{"schema":{"type":"object","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string","description":"The token. Send it as `Authorization: Bearer <access_token>`.","example":"eyJhbGciOiJSUzI1NiIs..."},"token_type":{"type":"string","description":"Always `Bearer`.","example":"Bearer"},"expires_in":{"type":"integer","description":"Seconds until the token expires. Reuse the token until then.","example":300},"scope":{"type":"string","description":"Scopes granted to the token.","example":"openid"}}},"example":{"access_token":"eyJhbGciOiJSUzI1NiIs...","token_type":"Bearer","expires_in":300,"scope":"openid"}}}},"400":{"description":"Missing `grant_type`, or the body is not form-encoded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"OAuth 2.0 error code."},"error_description":{"type":"string","description":"Human-readable explanation."}}},"example":{"error":"invalid_request","error_description":"Missing form parameter: grant_type"}}}},"401":{"description":"Wrong Client ID or Client Secret.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"OAuth 2.0 error code."},"error_description":{"type":"string","description":"Human-readable explanation."}}},"example":{"error":"invalid_client","error_description":"Invalid client or Invalid client credentials"}}}}},"servers":[{"url":"https://api.omaxtelecom.com/auth"}]}},"/phone-validation/health":{"get":{"tags":["Phone Validation"],"summary":"Service health","description":"Public endpoint. Returns whether the service is globally operational. No authentication required.","operationId":"getPhoneValidationHealth","security":[],"responses":{"200":{"description":"Service is operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceHealthResponse"},"example":{"ok":true,"timestamp":"2026-08-15T00:11:00+00:00"}}}},"503":{"description":"Service is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceHealthResponse"},"example":{"ok":false,"timestamp":"2026-08-15T00:11:00+00:00"}}}}}}},"/phone-validation/pricing":{"get":{"tags":["Phone Validation"],"summary":"Get organization phone validation pricing","operationId":"getPhoneValidationPricing","responses":{"200":{"description":"Organization pricing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneValidationPricingResponse"},"example":{"success":true,"data":{"enabled":true,"price_per_validation":"0.020000","currency":"EUR"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"}}}},"/phone-validation/transactions":{"get":{"tags":["Phone Validation"],"summary":"List phone validation transactions","operationId":"listPhoneValidationTransactions","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"cached","in":"query","schema":{"type":"string","enum":["0","1"]}},{"name":"phone_number","in":"query","schema":{"type":"string"}},{"name":"region","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"Paginated transaction list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneValidationTransactionListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"}}}},"/phone-validation/transactions/{id}":{"get":{"tags":["Phone Validation"],"summary":"Get phone validation transaction","operationId":"getPhoneValidationTransaction","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Transaction detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneValidationTransactionResponse"}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/phone-validation/jobs":{"get":{"tags":["Phone Validation"],"summary":"List phone validation bulk jobs","operationId":"listPhoneValidationJobs","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","completed","failed"]}}],"responses":{"200":{"description":"Paginated job list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneValidationJobListResponse"}}}}}}},"/phone-validation/jobs/{id}":{"get":{"tags":["Phone Validation"],"summary":"Get phone validation bulk job detail","operationId":"getPhoneValidationJob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job detail with items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneValidationJobDetailResponse"}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/phone-validation":{"post":{"tags":["Phone Validation"],"summary":"Validate a single phone number","operationId":"validatePhoneNumber","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SinglePhoneValidationRequest"}}}},"responses":{"200":{"description":"Validation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SinglePhoneValidationSuccessResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"},"422":{"$ref":"#/components/responses/ValidationError"}},"description":"Validates a phone number in E.164 format or national format with an optional region code. When billing applies, each request is charged individually."}},"/phone-validation/bulk":{"post":{"tags":["Phone Validation"],"summary":"Create bulk validation job","operationId":"createBulkPhoneValidation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPhoneValidationRequest"}}}},"responses":{"202":{"description":"Bulk job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPhoneValidationAcceptedResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"},"422":{"$ref":"#/components/responses/ValidationError"}},"description":"Queues an asynchronous bulk validation job. Returns a `job_id` that can be polled via `GET /phone-validation/bulk/{job_id}`."}},"/phone-validation/bulk/{job_id}":{"get":{"tags":["Phone Validation"],"summary":"Get bulk validation job status","operationId":"getBulkPhoneValidationJob","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job status and results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPhoneValidationJobResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"},"404":{"$ref":"#/components/responses/NotFound"}},"description":"Returns the current status and per-number results for a bulk validation job. Poll until `status` is `completed` or `failed`."}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"OmaxOAuth":{"type":"oauth2","description":"Enter the Client ID and Client Secret from [OmaxTelecom Console](https://console.omaxtelecom.com) and click **Authorize**. The access token is added to every request automatically.","flows":{"clientCredentials":{"tokenUrl":"https://api.omaxtelecom.com/auth/token","scopes":{},"x-scalar-credentials-location":"body"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid token"},"PaymentRequired":{"description":"Insufficient wallet balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INSUFFICIENT_BALANCE","message":"Insufficient wallet balance."}}}}},"ForbiddenOrganization":{"description":"Organization invalid, service disabled, or billing not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"organizationNotFound":{"value":{"success":false,"error":{"code":"ORGANIZATION_NOT_FOUND","message":"Organization not found."}}},"organizationSuspended":{"value":{"success":false,"error":{"code":"ORGANIZATION_SUSPENDED","message":"Organization is suspended."}}},"organizationInactive":{"value":{"success":false,"error":{"code":"ORGANIZATION_INACTIVE","message":"Organization is not active."}}},"disabled":{"value":{"success":false,"error":{"code":"PHONE_VALIDATION_DISABLED","message":"Phone validation is not enabled for this organization."}}},"billing":{"value":{"success":false,"error":{"code":"BILLING_NOT_CONFIGURED","message":"Billing is not configured for this organization."}}}}}}},"ValidationError":{"description":"Request validation or parse error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Job not found"}},"schemas":{"TokenRequest":{"type":"object","required":["client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"default":"client_credentials"},"client_id":{"type":"string"},"client_secret":{"type":"string","format":"password"}}},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string"},"expires_in":{"type":"integer","example":300},"token_type":{"type":"string","example":"Bearer"},"scope":{"type":"string"}}},"MeSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sub":{"type":"string"},"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"roles":{"type":"array","items":{"type":"string"}},"organization_id":{"type":"string","nullable":true},"is_m2m":{"type":"boolean"},"organization":{"$ref":"#/components/schemas/PartnerOrganization"}}}}},"PartnerOrganization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"services":{"type":"object","properties":{"number_lookup":{"type":"object","properties":{"enabled":{"type":"boolean"},"price_per_lookup":{"type":"string"},"currency":{"type":"string"}}},"phone_validation":{"type":"object","properties":{"enabled":{"type":"boolean"},"price_per_validation":{"type":"string"},"currency":{"type":"string"}}},"mcc_mnc":{"type":"object","properties":{"enabled":{"type":"boolean"},"price_per_request":{"type":"string"},"currency":{"type":"string"}}}}}}},"PhoneValidationPricingResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"enabled":{"type":"boolean"},"price_per_validation":{"type":"string"},"currency":{"type":"string"}}}}},"PhoneValidationTransaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"phone_number":{"type":"string"},"region":{"type":"string","nullable":true},"locale":{"type":"string"},"cached":{"type":"boolean"},"billed_amount":{"type":"string"},"billing_reference":{"type":"string","nullable":true},"console_transaction_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"response":{"type":"object"}}},"PhoneValidationTransactionResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PhoneValidationTransaction"}}},"PhoneValidationTransactionListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/PhoneValidationTransaction"}},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}}}},"PhoneValidationJobListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object"}},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}}}},"PhoneValidationJobDetailResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}},"SinglePhoneValidationRequest":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","example":"+38766940950"},"region":{"type":"string","description":"ISO 3166-1 alpha-2 region code, required for non-E.164 numbers","example":"BA"},"locale":{"type":"string","description":"Locale for geocoder and carrier mapping","example":"en"}}},"BulkPhoneValidationRequest":{"type":"object","required":["validations"],"properties":{"locale":{"type":"string","description":"Default locale for all items"},"validations":{"type":"array","items":{"$ref":"#/components/schemas/SinglePhoneValidationRequest"}}}},"PhoneValidationResult":{"type":"object","properties":{"valid":{"type":"boolean"},"possible":{"type":"boolean"},"phone_number":{"type":"string"},"national_format":{"type":"string"},"country_code":{"type":"string"},"calling_code":{"type":"string"},"number_type":{"type":"string"},"geocoder":{"type":"object","properties":{"description":{"type":"string"},"locale":{"type":"string"}}},"time_zones":{"type":"array","items":{"type":"string"}},"carrier":{"type":"object","properties":{"name":{"type":"string"},"locale":{"type":"string"}}}}},"SinglePhoneValidationSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/PhoneValidationResult"}}},"BulkPhoneValidationAcceptedResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"}}}}},"BulkPhoneValidationJobResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string"},"total_count":{"type":"integer"},"processed_count":{"type":"integer"},"failed_count":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string"},"region":{"type":"string","nullable":true},"locale":{"type":"string","nullable":true},"status":{"type":"string"},"result":{"$ref":"#/components/schemas/PhoneValidationResult"},"error":{"type":"string","nullable":true}}}}}}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ServiceHealthResponse":{"type":"object","required":["ok","timestamp"],"properties":{"ok":{"type":"boolean","description":"Whether the service is globally operational"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp of the health check"}}}}}}