{ "openapi": "3.0.3", "info": { "title": "Phone Numbers 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 purchasing and managing phone numbers, voice/SMS routing endpoints, inbound/outbound SMS, and KYC.\n\n## Billing\n\nNumber purchases, inbound SMS, and outbound SMS may be charged via the Console Wallet API depending on configured sell rates.\n\n## Response envelope\n\nSuccess: `{ \"success\": true, \"data\": { ... } }`\n\nError: `{ \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\n\n## Phone number format\n\nAll phone numbers must be in **E.164** format, for example `+447700900001`.\n\n## Purchase workflow\n\n1. `GET /available` — search the supplier catalog\n2. `POST /preview` — get a cost quote for selected catalog number IDs\n3. `POST /` — purchase using the catalog number ID(s) from step 1 or 2" }, "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": "Health", "description": "Service health checks (no authentication)" }, { "name": "Phone Numbers", "description": "Search, purchase, list, and release phone numbers" }, { "name": "SMS", "description": "Inbound and outbound SMS, pricing, and partner webhooks" }, { "name": "Endpoints", "description": "Voice and SMS routing endpoints" }, { "name": "KYC", "description": "Organization and per-number KYC submissions" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/me": { "get": { "tags": [ "Auth" ], "summary": "Verify token and organization context", "operationId": "getAuthenticatedContext", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "responses": { "200": { "description": "Authenticated context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeSuccessResponse" }, "example": { "success": true, "data": { "sub": "service-account-partner-service-m2m", "email": null, "name": null, "roles": [], "organization_id": "acme-telecom", "is_m2m": true, "organization": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme Telecom", "slug": "acme-telecom", "services": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/health": { "get": { "tags": [ "Health" ], "summary": "Phone numbers service health", "operationId": "getPhoneNumbersHealth", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceHealthResponse" }, "example": { "ok": true, "timestamp": "2026-09-17T12:00:00+00:00" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceHealthResponse" }, "example": { "ok": false, "timestamp": "2026-09-17T12:00:00+00:00" } } } } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/available": { "get": { "tags": [ "Phone Numbers" ], "summary": "Search available numbers", "description": "Search the supplier catalog for numbers available to purchase.", "operationId": "searchAvailablePhoneNumbers", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "name": "country_iso", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "GB" }, { "name": "number_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/PhoneNumberType" } }, { "name": "pattern", "in": "query", "schema": { "type": "string", "maxLength": 32 }, "example": "7700" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Available numbers", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogPhoneNumber" } }, "total_available": { "type": "integer" } } } } }, "example": { "success": true, "data": { "numbers": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "e164": "+447700900123", "phone_number": "+447700900123", "national_format": "07700 900123", "country_iso": "GB", "number_type": "mobile", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "billing_period": "monthly", "currency": "EUR", "value_tier": "standard" } ], "total_available": 42 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "OFFERING_NOT_FOUND", "message": "No offering found for GB local numbers." } } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/preview": { "post": { "tags": [ "Phone Numbers" ], "summary": "Preview purchase cost", "operationId": "previewPhoneNumberPurchase", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNumberSelectionRequest" }, "examples": { "singleNumber": { "summary": "Preview single number", "value": { "number_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "country_iso": "GB", "number_type": "mobile" } }, "multipleNumbers": { "summary": "Preview multiple numbers", "value": { "number_ids": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479", "a9b8c7d6-e5f4-3210-abcd-ef9876543210" ] } } } } } }, "responses": { "200": { "description": "Purchase preview with quote", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogPhoneNumber" } }, "quote": { "$ref": "#/components/schemas/PurchaseQuote" } } } } }, "example": { "success": true, "data": { "numbers": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "e164": "+447700900123", "phone_number": "+447700900123", "national_format": "07700 900123", "country_iso": "GB", "number_type": "mobile", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "billing_period": "monthly", "currency": "EUR", "value_tier": "standard" } ], "quote": { "connection_cost": 5, "monthly_cost": 2, "total_cost": 7, "currency": "EUR", "quote_token": "qt_abc123xyz", "expected_total_cost_minor": 700, "first_billing_date": "2026-09-17", "next_billing_date": "2026-10-17" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/": { "get": { "tags": [ "Phone Numbers" ], "summary": "List owned phone numbers", "operationId": "listOwnedPhoneNumbers", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "name": "e164", "in": "query", "schema": { "$ref": "#/components/schemas/E164PhoneNumber" }, "description": "Filter by exact E.164 number" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/PhoneNumberStatus" } }, { "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 } } ], "responses": { "200": { "description": "Paginated list of owned numbers", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "phone_numbers", "page", "per_page", "total" ], "properties": { "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberSummary" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "success": true, "data": { "phone_numbers": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "e164": "+447700900001", "phone_number": "+447700900001", "national_format": "07700 900001", "country_iso": "GB", "number_type": "local", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "status": "active", "kyc_status": "approved", "traffic_direction": "inbound_and_outbound", "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "next_billing_date": "2026-10-01", "billing_period": "monthly", "currency": "EUR" } ], "page": 1, "per_page": 20, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" } } }, "post": { "tags": [ "Phone Numbers" ], "summary": "Purchase phone numbers", "operationId": "purchasePhoneNumbers", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Optional idempotency key for the purchase charge", "example": "purchase-2026-09-17-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePhoneNumbersRequest" }, "examples": { "singleNumber": { "summary": "Purchase single number", "value": { "number_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } }, "withQuoteGuard": { "summary": "Purchase with quote token guard", "value": { "number_ids": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ], "quote_token": "qt_abc123xyz", "expected_total_cost_minor": 700 } } } } } }, "responses": { "201": { "description": "Numbers purchased", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberSummary" } } } } } }, "example": { "success": true, "data": { "order_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "phone_numbers": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "e164": "+447700900001", "phone_number": "+447700900001", "national_format": "07700 900001", "country_iso": "GB", "number_type": "local", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "status": "provisioning", "kyc_status": "approved", "traffic_direction": "inbound_and_outbound", "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "next_billing_date": "2026-10-01", "billing_period": "monthly", "currency": "EUR" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/{phoneNumberId}": { "get": { "tags": [ "Phone Numbers" ], "summary": "Get phone number details", "operationId": "getPhoneNumber", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/PhoneNumberId" } ], "responses": { "200": { "description": "Phone number details", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumberSummary" } } }, "example": { "success": true, "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "e164": "+447700900001", "phone_number": "+447700900001", "national_format": "07700 900001", "country_iso": "GB", "number_type": "local", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "status": "active", "kyc_status": "approved", "traffic_direction": "inbound_and_outbound", "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "next_billing_date": "2026-10-01", "billing_period": "monthly", "currency": "EUR", "purchased_by_keycloak_id": "user-123" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Phone Numbers" ], "summary": "Release phone number", "operationId": "releasePhoneNumber", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/PhoneNumberId" } ], "responses": { "200": { "description": "Number released", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumberSummary" } } }, "example": { "success": true, "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "e164": "+447700900001", "phone_number": "+447700900001", "national_format": "07700 900001", "country_iso": "GB", "number_type": "local", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "status": "releasing", "kyc_status": "approved", "traffic_direction": "inbound_and_outbound", "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "next_billing_date": "2026-10-01", "billing_period": "monthly", "currency": "EUR" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/{phoneNumberId}/routing": { "put": { "tags": [ "Phone Numbers" ], "summary": "Update voice and SMS routing", "operationId": "updatePhoneNumberRouting", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/PhoneNumberId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingRequest" }, "example": { "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012" } } } }, "responses": { "200": { "description": "Routing updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumberSummary" } } }, "example": { "success": true, "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "e164": "+447700900001", "phone_number": "+447700900001", "national_format": "07700 900001", "country_iso": "GB", "number_type": "local", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "status": "active", "kyc_status": "approved", "traffic_direction": "inbound_and_outbound", "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "next_billing_date": "2026-10-01", "billing_period": "monthly", "currency": "EUR" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/{phoneNumberId}/kyc": { "get": { "tags": [ "KYC" ], "summary": "Get per-number KYC submission", "operationId": "getPhoneNumberKyc", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/PhoneNumberId" } ], "responses": { "200": { "description": "Latest per-number KYC submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumberKycSubmission" } } }, "example": { "success": true, "data": { "id": "b8c9d0e1-f2a3-4567-bcde-678901234567", "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "pending", "data": { "use_case": "customer_support", "end_user_type": "business" }, "documents": [ "https://storage.example.com/docs/reg-form.pdf" ], "submitted_at": "2026-09-15T14:30:00+00:00", "reviewed_at": null, "rejection_reason": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "KYC" ], "summary": "Submit per-number KYC", "operationId": "submitPhoneNumberKyc", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/PhoneNumberId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitKycRequest" }, "example": { "data": { "use_case": "customer_support", "end_user_type": "business", "company_name": "Acme Telecom Ltd" }, "documents": [ "https://storage.example.com/docs/reg-form.pdf" ] } } } }, "responses": { "201": { "description": "KYC submitted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumberKycSubmission" } } }, "example": { "success": true, "data": { "id": "b8c9d0e1-f2a3-4567-bcde-678901234567", "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "pending", "data": { "use_case": "customer_support", "end_user_type": "business" }, "documents": [ "https://storage.example.com/docs/reg-form.pdf" ], "submitted_at": "2026-09-17T10:00:00+00:00", "reviewed_at": null, "rejection_reason": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/endpoints": { "get": { "tags": [ "Endpoints" ], "summary": "List routing endpoints", "operationId": "listPhoneNumberEndpoints", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/EndpointType" }, "description": "Filter by endpoint type" } ], "responses": { "200": { "description": "Endpoints list", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } } } }, "example": { "success": true, "data": { "endpoints": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "type": "voice", "name": "Primary SIP trunk", "destination_uri": "sip:trunk.example.com:5060", "is_default": true, "is_secondary": false, "created_by_keycloak_id": "user-123", "created_at": "2026-09-01T10:00:00+00:00" }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "type": "sms", "name": "SMS webhook", "destination_uri": "https://api.example.com/sms/inbound", "is_default": true, "is_secondary": false, "created_by_keycloak_id": "user-123", "created_at": "2026-09-01T10:00:00+00:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" } } }, "post": { "tags": [ "Endpoints" ], "summary": "Create routing endpoint", "operationId": "createPhoneNumberEndpoint", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointRequest" }, "examples": { "voice": { "summary": "Voice SIP endpoint", "value": { "name": "Primary SIP trunk", "type": "voice", "destination_uri": "sip:trunk.example.com:5060", "is_default": true } }, "sms": { "summary": "SMS webhook endpoint", "value": { "name": "Inbound SMS webhook", "type": "sms", "destination_uri": "https://api.example.com/sms/inbound", "is_default": true } } } } } }, "responses": { "201": { "description": "Endpoint created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Endpoint" } } }, "example": { "success": true, "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "type": "voice", "name": "Primary SIP trunk", "destination_uri": "sip:trunk.example.com:5060", "is_default": true, "is_secondary": false, "created_by_keycloak_id": "user-123", "created_at": "2026-09-01T10:00:00+00:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/endpoints/{endpointId}": { "get": { "tags": [ "Endpoints" ], "summary": "Get routing endpoint", "operationId": "getPhoneNumberEndpoint", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "200": { "description": "Endpoint details", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Endpoint" } } }, "example": { "success": true, "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "type": "voice", "name": "Primary SIP trunk", "destination_uri": "sip:trunk.example.com:5060", "is_default": true, "is_secondary": false, "created_by_keycloak_id": "user-123", "created_at": "2026-09-01T10:00:00+00:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Endpoints" ], "summary": "Update routing endpoint", "operationId": "updatePhoneNumberEndpoint", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/EndpointId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointRequest" }, "example": { "name": "Updated SIP trunk", "destination_uri": "sip:new-trunk.example.com:5060", "is_default": true } } } }, "responses": { "200": { "description": "Endpoint updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Endpoint" } } }, "example": { "success": true, "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "type": "voice", "name": "Updated SIP trunk", "destination_uri": "sip:new-trunk.example.com:5060", "is_default": true, "is_secondary": false, "created_by_keycloak_id": "user-123", "created_at": "2026-09-01T10:00:00+00:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Endpoints" ], "summary": "Delete routing endpoint", "operationId": "deletePhoneNumberEndpoint", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "200": { "description": "Endpoint deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } } } }, "example": { "success": true, "data": { "deleted": true, "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/pricing": { "get": { "tags": [ "SMS" ], "summary": "List inbound and outbound SMS rates", "operationId": "getSmsPricing", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "responses": { "200": { "description": "SMS rates for the organization", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SmsPricing" } } }, "example": { "success": true, "data": { "enabled": true, "inbound": [ { "country_iso": "GB", "cost_per_message": "0.020000", "currency": "EUR" } ], "outbound": [ { "destination_country_iso": "GB", "prefix": "44", "cost_per_message": "0.050000", "currency": "EUR" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/send": { "post": { "tags": [ "SMS" ], "summary": "Send outbound SMS", "operationId": "sendOutboundSms", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOutboundSmsRequest" }, "example": { "from": "+447700900001", "to": "+447911123456", "body": "Your verification code is 123456" } } } }, "responses": { "201": { "description": "SMS sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OutboundSmsMessage" } } }, "example": { "success": true, "data": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "from": "+447700900001", "to": "+447911123456", "body": "Your verification code is 123456", "segments": 1, "status": "sent", "sent_at": "2026-09-17T09:20:00+00:00", "delivered_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Outbound SMS failed at supplier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "OUTBOUND_SMS_FAILED", "message": "Failed to send SMS via supplier." } } } } } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/messages": { "get": { "tags": [ "SMS" ], "summary": "List inbound SMS messages", "operationId": "listInboundSmsMessages", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "name": "phone_number_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T00:00:00+00:00" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Inbound messages", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InboundSmsMessage" } } } } } }, "example": { "success": true, "data": { "messages": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "from": "+447911123456", "to": "+447700900001", "body": "Hello, I need support", "segments": 1, "status": "forwarded", "received_at": "2026-09-17T09:15:00+00:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/messages/{messageId}": { "get": { "tags": [ "SMS" ], "summary": "Get inbound SMS message detail", "operationId": "getInboundSmsMessage", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/MessageId" } ], "responses": { "200": { "description": "Inbound message with delivery attempts", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/InboundSmsMessageDetail" } } }, "example": { "success": true, "data": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "from": "+447911123456", "to": "+447700900001", "body": "Hello, I need support", "segments": 1, "status": "forwarded", "received_at": "2026-09-17T09:15:00+00:00", "sell_amount": "0.020000", "billing_reference": "pn-sms-in-abc123", "deliveries": [ { "id": "c9d0e1f2-a3b4-5678-cdef-901234567890", "attempt": 1, "status": "delivered", "http_status": 200, "error": null, "delivered_at": "2026-09-17T09:15:02+00:00", "next_retry_at": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/messages/{messageId}/retry": { "post": { "tags": [ "SMS" ], "summary": "Retry forwarding inbound SMS", "description": "Re-queues delivery of an inbound SMS to the configured partner webhook endpoint.", "operationId": "retryInboundSmsForward", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/MessageId" } ], "responses": { "202": { "description": "Forward retry accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/InboundSmsStatus" } } } } }, "example": { "success": true, "data": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "status": "forward_pending" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/sent": { "get": { "tags": [ "SMS" ], "summary": "List outbound SMS messages", "operationId": "listOutboundSmsMessages", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "name": "phone_number_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Outbound messages", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundSmsMessage" } } } } } }, "example": { "success": true, "data": { "messages": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "from": "+447700900001", "to": "+447911123456", "body": "Your verification code is 123456", "segments": 1, "status": "delivered", "sent_at": "2026-09-17T09:20:00+00:00", "delivered_at": "2026-09-17T09:20:05+00:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/sent/{messageId}": { "get": { "tags": [ "SMS" ], "summary": "Get outbound SMS message detail", "operationId": "getOutboundSmsMessage", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" }, { "$ref": "#/components/parameters/MessageId" } ], "responses": { "200": { "description": "Outbound message detail", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OutboundSmsMessageDetail" } } }, "example": { "success": true, "data": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "from": "+447700900001", "to": "+447911123456", "body": "Your verification code is 123456", "segments": 1, "status": "delivered", "sent_at": "2026-09-17T09:20:00+00:00", "delivered_at": "2026-09-17T09:20:05+00:00", "sell_amount": "0.050000", "billing_reference": "pn-sms-out-def456", "error_message": null, "sent_by_keycloak_id": "user-123" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/sms/webhook": { "get": { "tags": [ "SMS" ], "summary": "Get partner inbound SMS webhook settings", "operationId": "getPartnerSmsWebhook", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "responses": { "200": { "description": "Webhook settings", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PartnerSmsWebhook" } } }, "example": { "success": true, "data": { "url": "https://api.example.com/webhooks/inbound-sms", "enabled": true, "has_secret": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" } } }, "put": { "tags": [ "SMS" ], "summary": "Update partner inbound SMS webhook settings", "operationId": "updatePartnerSmsWebhook", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartnerSmsWebhookRequest" }, "example": { "url": "https://api.example.com/webhooks/inbound-sms", "secret": "my-webhook-secret-16chars", "enabled": true } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PartnerSmsWebhook" } } }, "example": { "success": true, "data": { "url": "https://api.example.com/webhooks/inbound-sms", "enabled": true, "has_secret": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/kyc/organization": { "get": { "tags": [ "KYC" ], "summary": "Get organization KYC submission", "operationId": "getOrganizationKyc", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "responses": { "200": { "description": "Latest organization KYC submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/KycSubmission" } } }, "example": { "success": true, "data": { "id": "a7b8c9d0-e1f2-3456-abcd-567890123456", "status": "approved", "data": { "company_name": "Acme Telecom Ltd", "registration_number": "12345678", "country": "GB" }, "documents": [ "https://storage.example.com/docs/certificate.pdf" ], "submitted_at": "2026-08-01T10:00:00+00:00", "reviewed_at": "2026-08-03T14:00:00+00:00", "rejection_reason": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "KYC" ], "summary": "Submit organization KYC", "operationId": "submitOrganizationKyc", "parameters": [ { "$ref": "#/components/parameters/XOrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitKycRequest" }, "example": { "data": { "company_name": "Acme Telecom Ltd", "registration_number": "12345678", "country": "GB", "address": "1 Telecom Way, London" }, "documents": [ "https://storage.example.com/docs/certificate.pdf", "https://storage.example.com/docs/id-proof.pdf" ] } } } }, "responses": { "201": { "description": "KYC submitted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/KycSubmission" } } }, "example": { "success": true, "data": { "id": "a7b8c9d0-e1f2-3456-abcd-567890123456", "status": "pending", "data": { "company_name": "Acme Telecom Ltd", "registration_number": "12345678", "country": "GB" }, "documents": [ "https://storage.example.com/docs/certificate.pdf" ], "submitted_at": "2026-09-17T10:00:00+00:00", "reviewed_at": null, "rejection_reason": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenPhoneNumbers" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "servers": [ { "url": "https://api.omaxtelecom.com/numbers", "description": "Phone Numbers API" } ] }, "/auth/token": { "servers": [ { "url": "https://api.omaxtelecom.com" } ], "post": { "tags": [ "Auth" ], "summary": "Get Access Token", "operationId": "createAccessToken", "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": {} } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OmaxTelecom ID access token issued for your organization." }, "noauthAuth": { "type": "http", "scheme": "noauth" } }, "parameters": { "XOrganizationId": { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Keycloak organization ID for M2M clients whose token does not include an `organization` claim.", "example": "acme-telecom" }, "PhoneNumberId": { "name": "phoneNumberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "EndpointId": { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, "MessageId": { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "e5f6a7b8-c9d0-1234-efab-345678901234" }, "SupplierCode": { "name": "supplierCode", "in": "path", "required": true, "schema": { "type": "string" }, "example": "cloud_numbering" } }, "responses": { "Unauthorized": { "description": "Missing, invalid, or expired access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired token." } } } } }, "ForbiddenPhoneNumbers": { "description": "Organization context invalid or phone numbers disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "disabled": { "summary": "Phone numbers disabled", "value": { "success": false, "error": { "code": "PHONE_NUMBERS_DISABLED", "message": "Phone numbers is not enabled for this organization." } } }, "kycRequired": { "summary": "KYC required", "value": { "success": false, "error": { "code": "KYC_REQUIRED", "message": "Organization KYC approval is required before purchasing numbers." } } }, "trafficRestricted": { "summary": "Outbound traffic restricted", "value": { "success": false, "error": { "code": "TRAFFIC_RESTRICTED", "message": "Outbound SMS is not permitted for this organization." } } }, "billingNotConfigured": { "summary": "Billing not configured", "value": { "success": false, "error": { "code": "BILLING_NOT_CONFIGURED", "message": "Billing is not configured for this organization." } } } } } } }, "PaymentRequired": { "description": "Insufficient wallet balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Insufficient wallet balance." } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found." } } } } }, "ServiceUnavailable": { "description": "Supplier or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SUPPLIER_UNAVAILABLE", "message": "Phone number supplier is temporarily unavailable." } } } } }, "ValidationError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaravelValidationErrorResponse" } } } } }, "schemas": { "TokenRequest": { "type": "object", "required": [ "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "default": "client_credentials" }, "client_id": { "type": "string", "example": "partner-service-m2m" }, "client_secret": { "type": "string", "example": "your-client-secret" } } }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "example": 300 }, "token_type": { "type": "string", "example": "Bearer" }, "scope": { "type": "string" } } }, "OAuthErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "MeSuccessResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ 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" }, "is_m2m": { "type": "boolean" }, "organization": { "$ref": "#/components/schemas/OrganizationContext" } } } } }, "OrganizationContext": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "services": { "type": "object" } } }, "SuccessResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" } } }, "ApiError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "PHONE_NUMBERS_DISABLED" }, "message": { "type": "string", "example": "Phone numbers is not enabled for this organization." } } }, "ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "$ref": "#/components/schemas/ApiError" } } }, "LaravelValidationErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "ServiceHealthResponse": { "type": "object", "required": [ "ok", "timestamp" ], "properties": { "ok": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" } } }, "E164PhoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "example": "+447700900001" }, "PhoneNumberType": { "type": "string", "enum": [ "local", "mobile", "national", "toll_free" ] }, "PhoneNumberStatus": { "type": "string", "enum": [ "pending_kyc", "provisioning", "active", "suspended", "releasing", "released", "failed" ] }, "KycStatus": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "TrafficDirection": { "type": "string", "enum": [ "inbound_only", "inbound_and_outbound" ] }, "EndpointType": { "type": "string", "enum": [ "voice", "sms" ] }, "InboundSmsStatus": { "type": "string", "enum": [ "received", "forward_pending", "forwarded", "forward_failed" ] }, "OutboundSmsStatus": { "type": "string", "enum": [ "pending", "sent", "failed", "delivered", "undelivered" ] }, "BillingPeriod": { "type": "string", "enum": [ "monthly", "quarterly", "annually" ] }, "CatalogPhoneNumber": { "type": "object", "required": [ "id", "e164", "phone_number", "country_iso", "number_type", "connection_fee", "monthly_fee", "total_fee", "billing_period", "currency" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Opaque catalog selection ID returned by search or preview" }, "e164": { "$ref": "#/components/schemas/E164PhoneNumber" }, "phone_number": { "type": "string" }, "national_format": { "type": "string", "nullable": true }, "country_iso": { "type": "string", "minLength": 2, "maxLength": 2 }, "number_type": { "$ref": "#/components/schemas/PhoneNumberType" }, "connection_fee": { "type": "string" }, "monthly_fee": { "type": "string" }, "total_fee": { "type": "string" }, "billing_period": { "$ref": "#/components/schemas/BillingPeriod" }, "currency": { "type": "string" }, "value_tier": { "type": "string", "nullable": true } }, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "e164": "+447700900123", "phone_number": "+447700900123", "national_format": "07700 900123", "country_iso": "GB", "number_type": "mobile", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "billing_period": "monthly", "currency": "EUR", "value_tier": "standard" } }, "PhoneNumberSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "e164": { "$ref": "#/components/schemas/E164PhoneNumber" }, "phone_number": { "type": "string" }, "national_format": { "type": "string", "nullable": true }, "country_iso": { "type": "string" }, "number_type": { "$ref": "#/components/schemas/PhoneNumberType" }, "connection_fee": { "type": "string" }, "monthly_fee": { "type": "string" }, "total_fee": { "type": "string" }, "status": { "$ref": "#/components/schemas/PhoneNumberStatus" }, "kyc_status": { "$ref": "#/components/schemas/KycStatus" }, "traffic_direction": { "$ref": "#/components/schemas/TrafficDirection" }, "voice_endpoint_id": { "type": "string", "format": "uuid", "nullable": true }, "sms_endpoint_id": { "type": "string", "format": "uuid", "nullable": true }, "next_billing_date": { "type": "string", "format": "date", "nullable": true }, "billing_period": { "$ref": "#/components/schemas/BillingPeriod" }, "currency": { "type": "string" }, "purchased_by_keycloak_id": { "type": "string", "nullable": true, "description": "Present on detailed responses only" } }, "example": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "e164": "+447700900001", "phone_number": "+447700900001", "national_format": "07700 900001", "country_iso": "GB", "number_type": "local", "connection_fee": "5.000000", "monthly_fee": "2.000000", "total_fee": "7.000000", "status": "active", "kyc_status": "approved", "traffic_direction": "inbound_and_outbound", "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "next_billing_date": "2026-10-01", "billing_period": "monthly", "currency": "EUR" } }, "PurchaseQuote": { "type": "object", "properties": { "connection_cost": { "type": "number", "format": "float" }, "monthly_cost": { "type": "number", "format": "float" }, "total_cost": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "quote_token": { "type": "string", "nullable": true }, "expected_total_cost_minor": { "type": "integer", "nullable": true }, "first_billing_date": { "type": "string", "nullable": true }, "next_billing_date": { "type": "string", "nullable": true } } }, "CatalogNumberSelectionRequest": { "type": "object", "properties": { "number_id": { "type": "string", "format": "uuid", "description": "Single catalog number ID" }, "number_ids": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uuid" } }, "country_iso": { "type": "string", "minLength": 2, "maxLength": 2 }, "number_type": { "$ref": "#/components/schemas/PhoneNumberType" } }, "oneOf": [ { "required": [ "number_id" ] }, { "required": [ "number_ids" ] } ] }, "PurchasePhoneNumbersRequest": { "allOf": [ { "$ref": "#/components/schemas/CatalogNumberSelectionRequest" }, { "type": "object", "properties": { "quote_token": { "type": "string", "nullable": true }, "expected_total_cost_minor": { "type": "integer", "minimum": 0, "nullable": true } } } ] }, "Endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/EndpointType" }, "name": { "type": "string" }, "destination_uri": { "type": "string", "format": "uri" }, "is_default": { "type": "boolean" }, "is_secondary": { "type": "boolean" }, "created_by_keycloak_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "example": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "type": "voice", "name": "Primary SIP trunk", "destination_uri": "sip:trunk.example.com:5060", "is_default": true, "is_secondary": false, "created_by_keycloak_id": "user-123", "created_at": "2026-09-01T10:00:00+00:00" } }, "CreateEndpointRequest": { "type": "object", "required": [ "name", "type", "destination_uri" ], "properties": { "name": { "type": "string", "maxLength": 128 }, "type": { "$ref": "#/components/schemas/EndpointType" }, "destination_uri": { "type": "string", "format": "uri", "maxLength": 2048 }, "is_default": { "type": "boolean", "default": false }, "is_secondary": { "type": "boolean", "default": false } } }, "UpdateEndpointRequest": { "type": "object", "required": [ "name", "destination_uri" ], "properties": { "name": { "type": "string", "maxLength": 128 }, "destination_uri": { "type": "string", "format": "uri", "maxLength": 2048 }, "is_default": { "type": "boolean" } } }, "UpdateRoutingRequest": { "type": "object", "properties": { "voice_endpoint_id": { "type": "string", "format": "uuid", "nullable": true }, "sms_endpoint_id": { "type": "string", "format": "uuid", "nullable": true } } }, "SendOutboundSmsRequest": { "type": "object", "required": [ "from", "to", "body" ], "properties": { "from": { "$ref": "#/components/schemas/E164PhoneNumber", "description": "Owned active sender number" }, "to": { "$ref": "#/components/schemas/E164PhoneNumber" }, "body": { "type": "string", "maxLength": 1600 } } }, "InboundSmsMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number_id": { "type": "string", "format": "uuid" }, "from": { "$ref": "#/components/schemas/E164PhoneNumber" }, "to": { "$ref": "#/components/schemas/E164PhoneNumber" }, "body": { "type": "string" }, "segments": { "type": "integer" }, "status": { "$ref": "#/components/schemas/InboundSmsStatus" }, "received_at": { "type": "string", "format": "date-time", "nullable": true } } }, "InboundSmsMessageDetail": { "allOf": [ { "$ref": "#/components/schemas/InboundSmsMessage" }, { "type": "object", "properties": { "sell_amount": { "type": "string", "nullable": true }, "billing_reference": { "type": "string", "nullable": true }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/InboundSmsDelivery" } } } } ] }, "InboundSmsDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "attempt": { "type": "integer" }, "status": { "type": "string" }, "http_status": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true } } }, "OutboundSmsMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number_id": { "type": "string", "format": "uuid" }, "from": { "$ref": "#/components/schemas/E164PhoneNumber" }, "to": { "$ref": "#/components/schemas/E164PhoneNumber" }, "body": { "type": "string" }, "segments": { "type": "integer" }, "status": { "$ref": "#/components/schemas/OutboundSmsStatus" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true } } }, "OutboundSmsMessageDetail": { "allOf": [ { "$ref": "#/components/schemas/OutboundSmsMessage" }, { "type": "object", "properties": { "sell_amount": { "type": "string", "nullable": true }, "billing_reference": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "sent_by_keycloak_id": { "type": "string", "nullable": true } } } ] }, "SmsPricing": { "type": "object", "required": [ "enabled", "inbound", "outbound" ], "properties": { "enabled": { "type": "boolean" }, "inbound": { "type": "array", "items": { "type": "object", "required": [ "country_iso", "cost_per_message", "currency" ], "properties": { "country_iso": { "type": "string" }, "cost_per_message": { "type": "string" }, "currency": { "type": "string" } } } }, "outbound": { "type": "array", "items": { "type": "object", "required": [ "destination_country_iso", "cost_per_message", "currency" ], "properties": { "destination_country_iso": { "type": "string" }, "prefix": { "type": "string", "nullable": true }, "cost_per_message": { "type": "string" }, "currency": { "type": "string" } } } } } }, "PartnerSmsWebhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true }, "enabled": { "type": "boolean" }, "has_secret": { "type": "boolean" } } }, "UpdatePartnerSmsWebhookRequest": { "type": "object", "required": [ "url", "enabled" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "secret": { "type": "string", "minLength": 16, "maxLength": 255, "nullable": true }, "enabled": { "type": "boolean" } } }, "KycSubmission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/KycStatus" }, "data": { "type": "object" }, "documents": { "type": "array", "items": { "type": "string" } }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "rejection_reason": { "type": "string", "nullable": true } } }, "PhoneNumberKycSubmission": { "allOf": [ { "$ref": "#/components/schemas/KycSubmission" }, { "type": "object", "properties": { "phone_number_id": { "type": "string", "format": "uuid" } } } ] }, "SubmitKycRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "KYC payload fields as required by your regulator" }, "documents": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "description": "URLs to supporting documents" } } }, "SupplierInboundSmsWebhookRequest": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "description": "Receiving number in E.164" }, "from": { "type": "string", "description": "Sender E.164 or alphanumeric sender ID" }, "content": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "parts": { "type": "integer", "minimum": 1 }, "sid": { "type": "string" } } }, "SupplierDlrWebhookRequest": { "type": "object", "required": [ "sid", "status", "timestamp" ], "properties": { "sid": { "type": "string" }, "status": { "type": "string", "enum": [ "delivered", "rejected" ] }, "timestamp": { "type": "string", "format": "date-time" } } }, "WebhookAcceptedResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] } } } } } }