{ "openapi": "3.0.3", "info": { "title": "Number Lookup API", "version": "1.0.0", "description": "## Quick Start\n\n1. Get your `client_id` and `client_secret` from [OmaxTelecom Console](https://console.omaxtelecom.com)\n2. Run **Auth → Get Access Token** to obtain a Bearer token\n3. All other endpoints use the `access_token` in the `Authorization` header\n\n## Authentication (OAuth 2.0)\n\nThis API uses the **OAuth 2.0 Client Credentials** grant type ([RFC 6749 §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)).\n\n**Token endpoint:**\n\n```\nPOST https://api.omaxtelecom.com/auth/token\n```\n\nSend `Authorization: Bearer ` on all endpoints except health.\n\nFor M2M clients without an `organization` claim, include `X-Organization-Id: `.\n\nPartner API for carrier number lookup. Phone numbers must be in **E.164** format (for example `+38766000111`). Version 1 supports **carrier** lookup only.\n\n## Billing\n\nWhen `price_per_lookup` > 0, each lookup is charged via Console Wallet API, including repeat lookups for the same number.\n\n## Response envelope\n\nSuccess: `{ \"success\": true, \"data\": { ... } }`\n\nError: `{ \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\n\n## Bulk processing\n\nBulk lookups are asynchronous. Create a job with `POST /number-lookup/bulk`, then poll `GET /number-lookup/bulk/{job_id}` until status is `completed` or `failed`." }, "tags": [ { "name": "Auth", "description": "OAuth 2.0 authentication using the **Client Credentials** grant type ([RFC 6749 §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)). Use your **Client ID** and **Client Secret** from [OmaxTelecom Console](https://console.omaxtelecom.com) to obtain an access token." }, { "name": "Number Lookup", "description": "Single and bulk carrier number lookup" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/auth/token": { "servers": [ { "url": "https://api.omaxtelecom.com" } ], "post": { "tags": [ "Auth" ], "summary": "Get Access Token", "description": "## Get Access Token\n\nObtain a Bearer access token using the OAuth 2.0 **Client Credentials** grant ([RFC 6749 §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)).\n\n### Setup\n\n1. Get your `client_id` from [OmaxTelecom Console](https://console.omaxtelecom.com)\n2. Get your `client_secret` from [OmaxTelecom Console](https://console.omaxtelecom.com)\n\n### Request\n\n```\nPOST https://api.omaxtelecom.com/auth/token\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=client_credentials&client_id={client_id}&client_secret={client_secret}\n```\n\n### Response (200 OK)\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIs...\",\n \"expires_in\": 300,\n \"token_type\": \"Bearer\",\n \"scope\": \"openid\"\n}\n```\n\n### Token Usage\n\nInclude the token in the `Authorization` header:\n\n```\nAuthorization: Bearer {access_token}\n```", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "grant_type": { "type": "string", "description": "OAuth 2.0 grant type (RFC 6749 §4.4)", "example": "client_credentials" }, "client_id": { "type": "string", "description": "Your Client ID", "example": "{{client_id}}" }, "client_secret": { "type": "string", "description": "Your Client Secret", "example": "{{client_secret}}" } } } } } }, "security": [ { "noauthAuth": [] } ], "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/x-www-form-urlencoded" }, { "name": "Accept", "in": "header", "schema": { "type": "string" }, "example": "application/json" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } } } }, "/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" } } } } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Number Lookup API" } ] }, "/number-lookup": { "post": { "tags": [ "Number Lookup" ], "summary": "Single number lookup", "description": "Performs a carrier lookup for one phone number. Results may be served from cache internally. 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": "+38766000111" } } } } } }, "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": "+38766000111", "country_code": "BA", "national_format": "066 000-111", "valid": true, "carrier": { "name": "BH Telecom", "type": "mobile", "mcc": "218", "mnc": "90" } } } }, "cachedResult": { "summary": "Cached lookup result", "value": { "success": true, "data": { "phone_number": "+38766000111", "country_code": "BA", "national_format": "066 000-111", "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/LaravelValidationErrorResponse" } ] }, "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" } } } } } } } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Number Lookup API" } ] }, "/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": [ "+38766000111", "+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/LaravelValidationErrorResponse" }, "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." ] } } } } } } } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Number Lookup API" } ] }, "/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": "+38766000111", "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": "+38766000111", "status": "completed", "result": { "phone_number": "+38766000111", "country_code": "BA", "national_format": "066 000-111", "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": "+38766000111", "status": "completed", "result": { "phone_number": "+38766000111", "country_code": "BA", "national_format": "066 000-111", "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": "+38766000111", "status": "completed", "result": { "phone_number": "+38766000111", "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." } } } } } } } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Number Lookup API" } ] } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OmaxTelecom ID access token. The token must include an `organization` claim matching your registered organisation ID, unless you are an approved M2M client using the `X-Organization-Id` header." }, "noauthAuth": { "type": "http", "scheme": "noauth" } }, "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": { "E164PhoneNumber": { "type": "string", "description": "Phone number in E.164 format", "pattern": "^\\+[1-9]\\d{1,14}$", "example": "+38766000111" }, "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 000-111" }, "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": [ "+38766000111", "+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" } } }, "LaravelValidationErrorResponse": { "type": "object", "description": "Standard Laravel validation error format 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." ] } } } }, "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" } } } } } }