{"openapi":"3.0.3","info":{"title":"Number Lookup API","version":"1.0.0","description":"The **Number Lookup API** finds the carrier behind a phone number: carrier name, line type and MCC/MNC. Numbers must be in **E.164** format, for example `+38766000111`. This version supports **carrier** lookup.\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/number-lookup/number-lookup.postman_collection.json) · [Environment](/postman/number-lookup/number-lookup.postman_environment.json) |\n| **AI assistants** | [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdeveloper.omaxtelecom.com%2Fnumber-lookup-api.md%20and%20help%20me%20integrate%20the%20OmaxTelecom%20Number%20Lookup%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%2Fnumber-lookup-api.md%20and%20help%20me%20integrate%20the%20OmaxTelecom%20Number%20Lookup%20API%20into%20my%20application.%20Ask%20me%20which%20language%20I%20use%20first.) · [Markdown](/number-lookup-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| **Look up a number** | `POST /number-lookup` | Carrier lookup for one number |\n| **Bulk lookup** | `POST /number-lookup/bulk` | Start an asynchronous bulk job for up to 1000 numbers |\n| **Bulk job status** | `GET /number-lookup/bulk/{job_id}` | Progress and results of a bulk job |\n| **Your price** | `GET /number-lookup/pricing` | Whether the API is enabled for you, and your price per lookup |\n| **Usage history** | `GET /number-lookup/transactions` | Every lookup you made, with what it cost |\n| **Bulk jobs** | `GET /number-lookup/jobs` | All your bulk jobs and their results |\n| **Health** | `GET /number-lookup/health` | Service availability (no token needed) |\n\n## Quick start\n\n1. **Enable the API.** Number lookup must be enabled for your organization in [OmaxTelecom Console](https://console.omaxtelecom.com).\n2. **Get a token** — see [Getting started](/getting-started).\n3. **Look up a number:**\n\n```bash\ncurl -X POST \"https://api.omaxtelecom.com/numbers/number-lookup?phone_number=%2B38766000111\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"phone_number\": \"+38766000111\",\n    \"country_code\": \"BA\",\n    \"national_format\": \"066 000-111\",\n    \"valid\": true,\n    \"carrier\": {\n      \"name\": \"BH Telecom\",\n      \"type\": \"mobile\",\n      \"mcc\": \"218\",\n      \"mnc\": \"90\"\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 /number-lookup/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 lookup result\n\n| Field | Description |\n|-------|-------------|\n| `phone_number` | Normalized E.164 number |\n| `country_code` | ISO 3166-1 alpha-2 country code |\n| `national_format` | Number formatted the national way |\n| `valid` | The number is considered valid |\n| `carrier.name` | Carrier name, when known |\n| `carrier.type` | Line type, for example `mobile` or `landline` |\n| `carrier.mcc` | Mobile Country Code |\n| `carrier.mnc` | Mobile Network Code |\n\n> [!NOTE]\n> An invalid number is not an error. The answer is still `200 OK`, with `valid: false` and no `carrier`:\n>\n> ```json\n> { \"success\": true, \"data\": { \"phone_number\": \"+15551234567\", \"country_code\": \"US\", \"national_format\": \"(555) 123-4567\", \"valid\": false } }\n> ```\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\": \"NUMBER_LOOKUP_UNAVAILABLE\",\n    \"message\": \"Number lookup service unavailable\"\n  }\n}\n```\n\n## Examples\n\n### Bulk lookup\n\nBulk lookups run in the background, for up to **1000** unique numbers per request. Start a job, then poll it every 1–3 seconds 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/number-lookup/bulk\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"phone_numbers\": [\"+38766000111\", \"+38761111222\"]}'\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/number-lookup/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\": \"completed\",\n    \"total_count\": 2,\n    \"processed_count\": 2,\n    \"failed_count\": 0,\n    \"items\": [\n      {\n        \"phone_number\": \"+38766000111\",\n        \"status\": \"completed\",\n        \"result\": {\n          \"phone_number\": \"+38766000111\",\n          \"country_code\": \"BA\",\n          \"national_format\": \"066 000-111\",\n          \"valid\": true,\n          \"carrier\": { \"name\": \"BH Telecom\", \"type\": \"mobile\", \"mcc\": \"218\", \"mnc\": \"90\" }\n        },\n        \"error\": null\n      },\n      {\n        \"phone_number\": \"+38761111222\",\n        \"status\": \"completed\",\n        \"result\": {\n          \"phone_number\": \"+38761111222\",\n          \"country_code\": \"BA\",\n          \"national_format\": \"061 111-222\",\n          \"valid\": true,\n          \"carrier\": { \"name\": \"HT Eronet\", \"type\": \"mobile\", \"mcc\": \"218\", \"mnc\": \"03\" }\n        },\n        \"error\": null\n      }\n    ]\n  }\n}\n```\n\n### Health check\n\n```bash\ncurl \"https://api.omaxtelecom.com/numbers/number-lookup/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 /number-lookup/pricing`:\n\n```json\n{ \"success\": true, \"data\": { \"enabled\": true, \"price_per_lookup\": \"0.050000\", \"currency\": \"EUR\" } }\n```\n\n**Usage history** — `GET /number-lookup/transactions` lists every lookup you made, newest first, with the amount billed. Filter by `from`, `to`, `cached`, `phone_number`, `lookup_type`; page with `page` and `per_page`. `GET /number-lookup/transactions/{id}` returns one transaction.\n\n**Bulk jobs** — `GET /number-lookup/jobs` lists your bulk jobs (filter by `status`, `from`, `to`); `GET /number-lookup/jobs/{id}` returns one job with its items.\n\n## Billing\n\nWhen your organization's `price_per_lookup` is above zero, each lookup is charged from your Console wallet — repeat lookups 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` | `NUMBER_LOOKUP_DISABLED` | Ask support to enable number lookup 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` | — | The number is not in E.164 format, or the request is invalid |\n| `503` | `NUMBER_LOOKUP_UNAVAILABLE` | The lookup provider is unavailable — retry later |\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":"Number Lookup","description":"Single and bulk carrier number lookup"}],"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"}]}},"/number-lookup/health":{"get":{"tags":["Number Lookup"],"summary":"Service health","description":"Public endpoint. Returns whether the service is globally operational. No authentication required.","operationId":"getNumberLookupHealth","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"}}}}}}},"/number-lookup/pricing":{"get":{"tags":["Number Lookup"],"summary":"Get organization number lookup pricing","operationId":"getNumberLookupPricing","responses":{"200":{"description":"Organization pricing for number lookup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberLookupPricingResponse"},"example":{"success":true,"data":{"enabled":true,"price_per_lookup":"0.050000","currency":"EUR"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"}}}},"/number-lookup/transactions":{"get":{"tags":["Number Lookup"],"summary":"List number lookup transactions","operationId":"listNumberLookupTransactions","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":"lookup_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated transaction list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberLookupTransactionListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"}}}},"/number-lookup/transactions/{id}":{"get":{"tags":["Number Lookup"],"summary":"Get number lookup transaction","operationId":"getNumberLookupTransaction","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Transaction detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberLookupTransactionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Transaction not found."}}}}}}}},"/number-lookup/jobs":{"get":{"tags":["Number Lookup"],"summary":"List number lookup bulk jobs","operationId":"listNumberLookupJobs","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":{"$ref":"#/components/schemas/BulkJobStatus"}}],"responses":{"200":{"description":"Paginated job list (without items)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberLookupJobListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"}}}},"/number-lookup/jobs/{id}":{"get":{"tags":["Number Lookup"],"summary":"Get number lookup bulk job detail","operationId":"getNumberLookupJob","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/NumberLookupJobDetailResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"},"404":{"description":"Job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Job not found."}}}}}}}},"/number-lookup":{"post":{"tags":["Number Lookup"],"summary":"Single number lookup","description":"Performs a carrier lookup for one phone number. When billing applies (`price_per_lookup` > 0), each request is charged regardless of cache status.","operationId":"createNumberLookup","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleNumberLookupRequest"},"examples":{"default":{"summary":"Lookup a Bosnian mobile number","value":{"phone_number":"+38766940950"}}}}}},"responses":{"200":{"description":"Lookup completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleNumberLookupSuccessResponse"},"examples":{"liveResult":{"summary":"Live lookup result","value":{"success":true,"data":{"phone_number":"+38766940950","country_code":"BA","national_format":"066 940-950","valid":true,"carrier":{"name":"BH Telecom","type":"mobile","mcc":"218","mnc":"90"}}}},"cachedResult":{"summary":"Cached lookup result","value":{"success":true,"data":{"phone_number":"+38766940950","country_code":"BA","national_format":"066 940-950","valid":true,"carrier":{"name":"BH Telecom","type":"mobile","mcc":"218","mnc":"90"}}}},"invalidNumber":{"summary":"Number found but marked invalid","value":{"success":true,"data":{"phone_number":"+15551234567","country_code":"US","national_format":"(555) 123-4567","valid":false}}}}}}},"401":{"description":"Missing, invalid, or expired access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Missing or invalid Authorization header."}}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"Organization context invalid, number lookup disabled, or billing not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"organizationNotFound":{"summary":"Organization not registered","value":{"success":false,"error":{"code":"ORGANIZATION_NOT_FOUND","message":"Organization not found."}}},"organizationSuspended":{"summary":"Organization suspended","value":{"success":false,"error":{"code":"ORGANIZATION_SUSPENDED","message":"Organization is suspended."}}},"organizationInactive":{"summary":"Organization inactive","value":{"success":false,"error":{"code":"ORGANIZATION_INACTIVE","message":"Organization is not active."}}},"lookupDisabled":{"summary":"Lookup disabled globally or for organization","value":{"success":false,"error":{"code":"NUMBER_LOOKUP_DISABLED","message":"Number lookup is not enabled for this organization."}}},"billingNotConfigured":{"summary":"Billing credentials missing for paid lookup","value":{"success":false,"error":{"code":"BILLING_NOT_CONFIGURED","message":"Billing is not configured for this organization."}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]},"examples":{"invalidE164":{"summary":"Invalid E.164 format (request validation)","value":{"message":"The phone number field format is invalid.","errors":{"phone_number":["The phone number field format is invalid."]}}},"missingPhoneNumber":{"summary":"Missing required field","value":{"message":"The phone number field is required.","errors":{"phone_number":["The phone number field is required."]}}}}}}},"503":{"description":"Lookup provider unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"providerUnavailable":{"value":{"success":false,"error":{"code":"NUMBER_LOOKUP_UNAVAILABLE","message":"Number lookup service unavailable"}}}}}}}}}},"/number-lookup/bulk":{"post":{"tags":["Number Lookup"],"summary":"Create bulk lookup job","description":"Queues an asynchronous bulk carrier lookup job. Returns a `job_id` that can be polled via `GET /number-lookup/bulk/{job_id}`.\n\nMaximum number of phone numbers per request: **1000** (configurable server-side). Phone numbers must be unique within the request.","operationId":"createBulkNumberLookup","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkNumberLookupRequest"},"examples":{"default":{"summary":"Bulk lookup two numbers","value":{"phone_numbers":["+38766940950","+38761111222"]}}}}}},"responses":{"202":{"description":"Bulk lookup job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkNumberLookupAcceptedResponse"},"examples":{"accepted":{"value":{"success":true,"data":{"job_id":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"},"examples":{"emptyArray":{"value":{"message":"The phone numbers field is required.","errors":{"phone_numbers":["The phone numbers field is required."]}}},"duplicateNumbers":{"value":{"message":"The phone_numbers.1 field has a duplicate value.","errors":{"phone_numbers.1":["The phone_numbers.1 field has a duplicate value."]}}},"tooManyNumbers":{"value":{"message":"The phone numbers field must not have more than 1000 items.","errors":{"phone_numbers":["The phone numbers field must not have more than 1000 items."]}}}}}}}}}},"/number-lookup/bulk/{job_id}":{"get":{"tags":["Number Lookup"],"summary":"Get bulk lookup job status and results","description":"Returns the current status and per-number results for a bulk lookup job. Jobs are scoped to the authenticated organization — you can only access jobs created by your organization.\n\nPoll this endpoint until `status` is `completed` or `failed`. Recommended polling interval: 1–3 seconds.","operationId":"getBulkNumberLookupJob","parameters":[{"name":"job_id","in":"path","required":true,"description":"Bulk lookup job UUID returned by `POST /number-lookup/bulk`","schema":{"type":"string","format":"uuid"},"example":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c"}],"responses":{"200":{"description":"Job status and results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkNumberLookupJobResponse"},"examples":{"pending":{"summary":"Job queued, not yet processing","value":{"success":true,"data":{"job_id":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c","status":"pending","total_count":2,"processed_count":0,"failed_count":0,"items":[{"phone_number":"+38766940950","status":"pending","result":null,"error":null},{"phone_number":"+38761111222","status":"pending","result":null,"error":null}]}}},"processing":{"summary":"Job in progress","value":{"success":true,"data":{"job_id":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c","status":"processing","total_count":2,"processed_count":1,"failed_count":0,"items":[{"phone_number":"+38766940950","status":"completed","result":{"phone_number":"+38766940950","country_code":"BA","national_format":"066 940-950","valid":true,"carrier":{"name":"BH Telecom","type":"mobile","mcc":"218","mnc":"90"}},"error":null},{"phone_number":"+38761111222","status":"pending","result":null,"error":null}]}}},"completed":{"summary":"All items processed successfully","value":{"success":true,"data":{"job_id":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c","status":"completed","total_count":2,"processed_count":2,"failed_count":0,"items":[{"phone_number":"+38766940950","status":"completed","result":{"phone_number":"+38766940950","country_code":"BA","national_format":"066 940-950","valid":true,"carrier":{"name":"BH Telecom","type":"mobile","mcc":"218","mnc":"90"}},"error":null},{"phone_number":"+38761111222","status":"completed","result":{"phone_number":"+38761111222","country_code":"BA","national_format":"061 111-222","valid":true,"carrier":{"name":"HT Eronet","type":"mobile","mcc":"218","mnc":"03"}},"error":null}]}}},"completedWithFailures":{"summary":"Job finished with some failed items","value":{"success":true,"data":{"job_id":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c","status":"completed","total_count":2,"processed_count":2,"failed_count":1,"items":[{"phone_number":"+38766940950","status":"completed","result":{"phone_number":"+38766940950","country_code":"BA","valid":true},"error":null},{"phone_number":"+00000000000","status":"failed","result":null,"error":"Number lookup service unavailable"}]}}},"failed":{"summary":"All items failed","value":{"success":true,"data":{"job_id":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c","status":"failed","total_count":1,"processed_count":1,"failed_count":1,"items":[{"phone_number":"+00000000000","status":"failed","result":null,"error":"Number lookup service unavailable"}]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenOrganization"},"404":{"description":"Job not found or not accessible by this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notFound":{"value":{"success":false,"error":{"code":"NOT_FOUND","message":"Bulk lookup job not found."}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OmaxTelecom access token from `POST https://api.omaxtelecom.com/auth/token`. The token must include an `organization` claim matching your registered OmaxTelecom Org ID, unless you are an approved M2M client using the `X-Organization-Id` header."},"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, invalid, or expired access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid or expired token."}}}}}}},"ForbiddenOrganization":{"description":"Organization context invalid, number lookup 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."}}},"lookupDisabled":{"value":{"success":false,"error":{"code":"NUMBER_LOOKUP_DISABLED","message":"Number lookup is not enabled for this organization."}}},"billingNotConfigured":{"value":{"success":false,"error":{"code":"BILLING_NOT_CONFIGURED","message":"Billing is not configured for this organization."}}}}}}},"PaymentRequired":{"description":"Organization wallet balance is insufficient for the lookup charge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"insufficientBalance":{"value":{"success":false,"error":{"code":"INSUFFICIENT_BALANCE","message":"Insufficient wallet balance."}}}}}}}},"schemas":{"TokenRequest":{"type":"object","required":["client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"default":"client_credentials"},"client_id":{"type":"string","description":"Client ID from OmaxTelecom Console","example":"your-client-id"},"client_secret":{"type":"string","description":"Client Secret from OmaxTelecom Console","format":"password"}}},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"JWT access token to send as Bearer token"},"expires_in":{"type":"integer","description":"Token lifetime in seconds","example":300},"token_type":{"type":"string","example":"Bearer"},"scope":{"type":"string","example":"profile email"}}},"OAuthErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"invalid_client"},"error_description":{"type":"string","example":"Invalid client credentials"}}},"MeSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"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":{"$ref":"#/components/schemas/NumberLookupPricing"},"phone_validation":{"$ref":"#/components/schemas/PhoneValidationPricing"},"mcc_mnc":{"$ref":"#/components/schemas/MccMncPricing"}}}}},"NumberLookupPricing":{"type":"object","properties":{"enabled":{"type":"boolean"},"price_per_lookup":{"type":"string","example":"0.050000"},"currency":{"type":"string","example":"EUR"}}},"PhoneValidationPricing":{"type":"object","properties":{"enabled":{"type":"boolean"},"price_per_validation":{"type":"string","example":"0.020000"},"currency":{"type":"string","example":"EUR"}}},"MccMncPricing":{"type":"object","properties":{"enabled":{"type":"boolean"},"price_per_request":{"type":"string","example":"0.010000"},"currency":{"type":"string","example":"EUR"}}},"NumberLookupPricingResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/NumberLookupPricing"}}},"NumberLookupTransaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"phone_number":{"$ref":"#/components/schemas/E164PhoneNumber"},"lookup_type":{"type":"string","example":"carrier"},"cached":{"type":"boolean"},"billed_amount":{"type":"string","example":"0.050000"},"billing_reference":{"type":"string","nullable":true},"console_transaction_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"response":{"$ref":"#/components/schemas/NumberLookupResult"}}},"NumberLookupTransactionResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/NumberLookupTransaction"}}},"NumberLookupTransactionListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/NumberLookupTransaction"}},"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":20},"total":{"type":"integer","example":42}}}}},"NumberLookupJobSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/BulkJobStatus"},"total_count":{"type":"integer"},"processed_count":{"type":"integer"},"failed_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"NumberLookupJobListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/NumberLookupJobSummary"}},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}}}},"NumberLookupJobDetailResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"allOf":[{"$ref":"#/components/schemas/BulkNumberLookupJobResponse/properties/data"}]}}},"E164PhoneNumber":{"type":"string","description":"Phone number in E.164 format","pattern":"^\\+[1-9]\\d{1,14}$","example":"+38766940950"},"CarrierInfo":{"type":"object","description":"Carrier information returned for a valid lookup","properties":{"name":{"type":"string","example":"BH Telecom"},"type":{"type":"string","description":"Carrier line type, for example mobile or landline","example":"mobile"},"mcc":{"type":"string","description":"Mobile Country Code","example":"218"},"mnc":{"type":"string","description":"Mobile Network Code","example":"90"}}},"NumberLookupResult":{"type":"object","description":"Sanitized carrier lookup result","properties":{"phone_number":{"$ref":"#/components/schemas/E164PhoneNumber"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"BA"},"national_format":{"type":"string","description":"Nationally formatted phone number","example":"066 940-950"},"valid":{"type":"boolean","description":"Whether the phone number is considered valid","example":true},"carrier":{"$ref":"#/components/schemas/CarrierInfo"}},"required":["phone_number"]},"SingleNumberLookupRequest":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"$ref":"#/components/schemas/E164PhoneNumber"}}},"SingleNumberLookupSuccessResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/NumberLookupResult"}}},"BulkNumberLookupRequest":{"type":"object","required":["phone_numbers"],"properties":{"phone_numbers":{"type":"array","description":"List of E.164 phone numbers to look up. Must be unique. Maximum 1000 items.","minItems":1,"maxItems":1000,"uniqueItems":true,"items":{"$ref":"#/components/schemas/E164PhoneNumber"},"example":["+38766940950","+38761111222"]}}},"BulkNumberLookupAcceptedResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["job_id"],"properties":{"job_id":{"type":"string","format":"uuid","example":"9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c"}}}}},"BulkJobStatus":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Overall bulk job status"},"BulkJobItemStatus":{"type":"string","enum":["pending","completed","failed"],"description":"Per-number item status"},"BulkNumberLookupJobItem":{"type":"object","required":["phone_number","status"],"properties":{"phone_number":{"$ref":"#/components/schemas/E164PhoneNumber"},"status":{"$ref":"#/components/schemas/BulkJobItemStatus"},"result":{"allOf":[{"$ref":"#/components/schemas/NumberLookupResult"}],"nullable":true,"description":"Lookup result when status is completed"},"error":{"type":"string","nullable":true,"description":"Error message when status is failed","example":"Number lookup service unavailable"}}},"BulkNumberLookupJobResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["job_id","status","total_count","processed_count","failed_count","items"],"properties":{"job_id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/BulkJobStatus"},"total_count":{"type":"integer","minimum":0,"example":2},"processed_count":{"type":"integer","minimum":0,"example":2},"failed_count":{"type":"integer","minimum":0,"example":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/BulkNumberLookupJobItem"}}}}}},"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code","example":"NUMBER_LOOKUP_UNAVAILABLE"},"message":{"type":"string","description":"Human-readable error message","example":"Number lookup service unavailable"}}},"ErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/ApiError"}}},"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"}}},"ValidationErrorResponse":{"type":"object","description":"Validation error returned for invalid request bodies.","required":["message","errors"],"properties":{"message":{"type":"string","example":"The phone number field format is invalid."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"phone_number":["The phone number field format is invalid."]}}}}}}}