{ "openapi": "3.1.0", "info": { "title": "SendMyCall public API", "version": "1.0.0", "summary": "Read-only data about SendMyCall virtual phone numbers: countries, number areas and their monthly prices, calling and forwarding rates.", "description": "A public, read-only JSON API over the same data as the sendmycall.com coverage, pricing and rates pages. No account and no key: every endpoint is open (security: []). The data comes from snapshots shipped with the site (meta.data_as_of says when each was taken); availability means an area had numbers at the snapshot, not that a given number is in stock now. The number picker (https://sendmycall.com/numbers) shows the numbers available now; buying a number is done by the user on the website.\n\nRate limit: 60 requests per 60 seconds per client IP address, reported on every response in RateLimit / RateLimit-Policy and X-RateLimit-* headers; a 429 carries Retry-After.\n\nErrors: every 4xx and 5xx has the body { \"error\": { \"code\", \"message\", \"hint\", \"request_id\" } }.\n\nPagination: list endpoints take limit (1-100, default 50) and cursor, and return { data, pagination: { limit, next_cursor, has_more }, meta }. Follow next_cursor until has_more is false.\n\nVersioning: The version is in the path (/api/v1) and in the API-Version response header. Within v1 we only make compatible changes: new endpoints, new optional parameters, new fields in responses and new values where a field documents that it may grow. Clients should ignore fields they do not know. A breaking change (removing or renaming a field or endpoint, changing a type or a meaning) ships as /api/v2, and v1 then keeps working for at least 180 days after the deprecation is announced on https://sendmycall.com/developers, in /llms.txt and in this document; during that time v1 responses carry a Deprecation header and, once the retirement date is fixed, a Sunset header (RFC 8594). Policy published 2026-10-14.", "contact": { "name": "SendMyCall support", "email": "care@sendmycall.com", "url": "https://sendmycall.com/developers" }, "termsOfService": "https://sendmycall.com/terms" }, "externalDocs": { "description": "Developer guide", "url": "https://sendmycall.com/developers" }, "servers": [ { "url": "https://sendmycall.com", "description": "Production" } ], "security": [], "tags": [ { "name": "API", "description": "The API's self-description." }, { "name": "Coverage", "description": "Countries and number areas, with monthly prices." }, { "name": "Rates", "description": "Per-minute prices for outgoing calls and forwarding." } ], "paths": { "/api/v1": { "get": { "operationId": "getApiIndex", "summary": "Describe the API", "description": "This self-description: version, authentication, documentation and endpoints.", "tags": [ "API" ], "security": [], "responses": { "200": { "description": "The self-description.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ApiIndex" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "name": "SendMyCall public API", "version": "1", "status": "stable", "read_only": true, "authentication": "none", "documentation_url": "https://sendmycall.com/developers", "openapi_url": "https://sendmycall.com/openapi.json", "openapi_yaml_url": "https://sendmycall.com/openapi.yaml", "versioning_policy_url": "https://sendmycall.com/developers#versioning", "rate_limit": { "requests": 60, "window_seconds": 60, "scope": "client IP address" }, "endpoints": [ { "method": "GET", "path": "/api/v1", "url": "https://sendmycall.com/api/v1", "operation_id": "getApiIndex", "description": "This self-description: version, authentication, documentation and endpoints." }, { "method": "GET", "path": "/api/v1/countries", "url": "https://sendmycall.com/api/v1/countries", "operation_id": "listCountries", "description": "Countries with number coverage, their number types, area counts and lowest monthly price." }, { "method": "GET", "path": "/api/v1/areas", "url": "https://sendmycall.com/api/v1/areas", "operation_id": "listAreas", "description": "Number areas (cities, regions, national, mobile and toll-free ranges) with monthly price, features and registration requirements." }, { "method": "GET", "path": "/api/v1/areas/{id}", "url": "https://sendmycall.com/api/v1/areas/{id}", "operation_id": "getArea", "description": "One number area by its public id." }, { "method": "GET", "path": "/api/v1/rates/calling", "url": "https://sendmycall.com/api/v1/rates/calling", "operation_id": "getCallingRate", "description": "Per-minute price of outgoing calls and forwards to one phone number (longest matching prefix)." }, { "method": "GET", "path": "/api/v1/rates/forwarding", "url": "https://sendmycall.com/api/v1/rates/forwarding", "operation_id": "getForwardingRate", "description": "What forwarding calls to a country costs: free to SIP, VoIP and the app; the per-minute range to its phone numbers." } ], "billing_terms": { "currency": "USD", "tax_included": true, "setup_price_cents": 0, "prepay_periods_months": [ 1, 3, 6, 12 ], "longer_periods_discounted": true, "contract": "none", "usage_billing": "Forwarding to phone numbers and outgoing calls are billed per minute from the account balance; forwarding to SIP, VoIP and the app is free." } }, "meta": { "api_version": "1", "dataset_version": "sha256:a18e1ca20c7c679ad7aa7d273ece13fbb76d6533dec8378272d9bdac3239013d", "data_as_of": "2026-09-19T04:42:21.787Z" } } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported; the Allow header lists them.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "GET, HEAD, OPTIONS", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "POST is not supported: the public API is read-only.", "hint": "Use GET (or HEAD).", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After seconds.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded: 60 requests per 60 seconds per client.", "hint": "Wait 42 seconds (Retry-After) before the next request.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "500": { "description": "An unexpected error on our side.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "hint": "Retry later; if it persists, write to support with the request_id.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } } } } }, "/api/v1/countries": { "get": { "operationId": "listCountries", "summary": "List countries", "description": "Countries with number coverage, their number types, area counts and lowest monthly price. Ordered by country code. offered says whether new numbers in the country can be bought now (null when that could not be checked).", "tags": [ "Coverage" ], "security": [], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Only this number type.", "schema": { "type": "string", "enum": [ "local", "national", "mobile", "toll_free", "shared_cost", "global" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 50 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor: next_cursor of the previous page, sent with the same filters.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "A page of countries.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "code": "GB", "name": "United Kingdom", "calling_code": "44", "number_types": [ "local", "national", "mobile", "toll_free" ], "area_count": 581, "monthly_price_from_cents": 995, "currency": "USD", "offered": true, "page_urls": { "virtual_number": "https://sendmycall.com/virtual-number/united-kingdom/", "toll_free": "https://sendmycall.com/toll-free/united-kingdom/" }, "order_url": "https://sendmycall.com/numbers?country=GB" } ], "pagination": { "limit": 50, "next_cursor": "eyJ2IjoiLi4uIn0", "has_more": true }, "meta": { "api_version": "1", "dataset_version": "sha256:a18e1ca20c7c679ad7aa7d273ece13fbb76d6533dec8378272d9bdac3239013d", "data_as_of": "2026-09-19T04:42:21.787Z" } } } } }, "400": { "description": "A parameter or the cursor is not valid.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "country must be an ISO 3166-1 alpha-2 code such as GB.", "hint": "List the codes with GET /api/v1/countries.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported; the Allow header lists them.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "GET, HEAD, OPTIONS", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "POST is not supported: the public API is read-only.", "hint": "Use GET (or HEAD).", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "409": { "description": "The cursor was issued for an earlier data snapshot.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "cursor_expired", "message": "The data changed since this cursor was issued.", "hint": "Start the list again without cursor.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After seconds.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded: 60 requests per 60 seconds per client.", "hint": "Wait 42 seconds (Retry-After) before the next request.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "500": { "description": "An unexpected error on our side.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "hint": "Retry later; if it persists, write to support with the request_id.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "503": { "description": "The data is temporarily unavailable.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable.", "hint": "Retry later.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } } } } }, "/api/v1/areas": { "get": { "operationId": "listAreas", "summary": "List number areas", "description": "Number areas (cities, regions, national, mobile and toll-free ranges) with monthly price, features and registration requirements. Without country, every country's areas, ordered by id. A search with no match is an empty list (200).", "tags": [ "Coverage" ], "security": [], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code, e.g. GB. Omitted: all countries.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "type", "in": "query", "required": false, "description": "Only this number type.", "schema": { "type": "string", "enum": [ "local", "national", "mobile", "toll_free", "shared_cost", "global" ] } }, { "name": "q", "in": "query", "required": false, "description": "Text in the area's name, city or region, or a dialling prefix (e.g. London, 4420).", "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 50 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor: next_cursor of the previous page, sent with the same filters.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "A page of areas.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Area" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "gb-vn-london_44-20", "country": "GB", "name": "London", "city": "London", "region": "England", "prefix": "20", "type": "local", "features": [ "voice_in", "voice_out", "fax_t38" ], "monthly_price_cents": 995, "setup_price_cents": 0, "currency": "USD", "tax_included": true, "toll_free_incoming_per_minute": null, "availability": { "available_at_snapshot": true, "observed_at": "2026-09-19T04:42:21.787Z", "stock_count": null, "country_offered": true }, "registration": { "documents_required": false, "holder": "any", "address_required_in": null, "identity_documents": 0, "address_documents": 0, "service_description_required": false, "summary": "No documents are needed to activate this number." }, "page_url": "https://sendmycall.com/virtual-number/united-kingdom/london_44-20/", "order_url": "https://sendmycall.com/numbers?country=GB" } ], "pagination": { "limit": 50, "next_cursor": "eyJ2IjoiLi4uIn0", "has_more": true }, "meta": { "api_version": "1", "dataset_version": "sha256:a18e1ca20c7c679ad7aa7d273ece13fbb76d6533dec8378272d9bdac3239013d", "data_as_of": "2026-09-19T04:42:21.787Z" } } } } }, "400": { "description": "A parameter or the cursor is not valid.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "country must be an ISO 3166-1 alpha-2 code such as GB.", "hint": "List the codes with GET /api/v1/countries.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported; the Allow header lists them.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "GET, HEAD, OPTIONS", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "POST is not supported: the public API is read-only.", "hint": "Use GET (or HEAD).", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "409": { "description": "The cursor was issued for an earlier data snapshot.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "cursor_expired", "message": "The data changed since this cursor was issued.", "hint": "Start the list again without cursor.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After seconds.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded: 60 requests per 60 seconds per client.", "hint": "Wait 42 seconds (Retry-After) before the next request.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "500": { "description": "An unexpected error on our side.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "hint": "Retry later; if it persists, write to support with the request_id.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "503": { "description": "The data is temporarily unavailable.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable.", "hint": "Retry later.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } } } } }, "/api/v1/areas/{id}": { "get": { "operationId": "getArea", "summary": "Get one number area", "description": "One number area by its public id.", "tags": [ "Coverage" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public area id from listAreas, e.g. gb-vn-london_44-20.", "schema": { "type": "string", "pattern": "^[a-z]{2}-(vn|tf)-.+$", "maxLength": 220 } } ], "responses": { "200": { "description": "The area.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Area" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": "gb-vn-london_44-20", "country": "GB", "name": "London", "city": "London", "region": "England", "prefix": "20", "type": "local", "features": [ "voice_in", "voice_out", "fax_t38" ], "monthly_price_cents": 995, "setup_price_cents": 0, "currency": "USD", "tax_included": true, "toll_free_incoming_per_minute": null, "availability": { "available_at_snapshot": true, "observed_at": "2026-09-19T04:42:21.787Z", "stock_count": null, "country_offered": true }, "registration": { "documents_required": false, "holder": "any", "address_required_in": null, "identity_documents": 0, "address_documents": 0, "service_description_required": false, "summary": "No documents are needed to activate this number." }, "page_url": "https://sendmycall.com/virtual-number/united-kingdom/london_44-20/", "order_url": "https://sendmycall.com/numbers?country=GB" }, "meta": { "api_version": "1", "dataset_version": "sha256:a18e1ca20c7c679ad7aa7d273ece13fbb76d6533dec8378272d9bdac3239013d", "data_as_of": "2026-09-19T04:42:21.787Z" } } } } }, "404": { "description": "No such resource.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No area with that id.", "hint": "Find area ids with GET /api/v1/areas?country=XX.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported; the Allow header lists them.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "GET, HEAD, OPTIONS", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "POST is not supported: the public API is read-only.", "hint": "Use GET (or HEAD).", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After seconds.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded: 60 requests per 60 seconds per client.", "hint": "Wait 42 seconds (Retry-After) before the next request.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "500": { "description": "An unexpected error on our side.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "hint": "Retry later; if it persists, write to support with the request_id.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "503": { "description": "The data is temporarily unavailable.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable.", "hint": "Retry later.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } } } } }, "/api/v1/rates/calling": { "get": { "operationId": "getCallingRate", "summary": "Get the per-minute price of calls to a number", "description": "Per-minute price of outgoing calls and forwards to one phone number (longest matching prefix). The same price applies when a call to your SendMyCall number is forwarded to that phone number. The number is used for the lookup only: it is not stored or returned.", "tags": [ "Rates" ], "security": [], "parameters": [ { "name": "to", "in": "query", "required": true, "description": "The phone number in E.164 format; encode + as %2B (to=%2B442079460000).", "schema": { "type": "string", "pattern": "^\\+?[1-9][0-9]{6,14}$" } } ], "responses": { "200": { "description": "The rate; offered is false when calls to that number are not offered.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CallingRate" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "destination": "United Kingdom", "country": "GB", "matched_prefix": "442", "offered": true, "price_per_minute": "0.64", "first_interval_price": null, "first_interval_seconds": null, "currency": "USD", "tax_included": true, "rates_url": "https://sendmycall.com/rates?q=442" }, "meta": { "api_version": "1", "dataset_version": "sha256:a18e1ca20c7c679ad7aa7d273ece13fbb76d6533dec8378272d9bdac3239013d", "data_as_of": "2026-09-24T07:59:35Z" } } } } }, "400": { "description": "A parameter or the cursor is not valid.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "country must be an ISO 3166-1 alpha-2 code such as GB.", "hint": "List the codes with GET /api/v1/countries.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported; the Allow header lists them.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "GET, HEAD, OPTIONS", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "POST is not supported: the public API is read-only.", "hint": "Use GET (or HEAD).", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After seconds.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded: 60 requests per 60 seconds per client.", "hint": "Wait 42 seconds (Retry-After) before the next request.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "500": { "description": "An unexpected error on our side.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "hint": "Retry later; if it persists, write to support with the request_id.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "503": { "description": "The data is temporarily unavailable.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable.", "hint": "Retry later.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } } } } }, "/api/v1/rates/forwarding": { "get": { "operationId": "getForwardingRate", "summary": "Get forwarding prices for a country", "description": "What forwarding calls to a country costs: free to SIP, VoIP and the app; the per-minute range to its phone numbers.", "tags": [ "Rates" ], "security": [], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 code of the country calls are forwarded to, e.g. GB.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } } ], "responses": { "200": { "description": "Forwarding prices.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ForwardingRate" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "country": "GB", "destination": "United Kingdom", "to_sip_voip_app": { "price_per_minute": "0" }, "to_phone": { "price_per_minute_min": "0.08", "price_per_minute_max": "1.25", "offered": true, "currency": "USD", "tax_included": true }, "exact_rate": { "endpoint": "https://sendmycall.com/api/v1/rates/calling?to=%2B", "description": "The exact per-minute price of one phone number, by the longest matching prefix." }, "rates_url": "https://sendmycall.com/rates?q=United%20Kingdom" }, "meta": { "api_version": "1", "dataset_version": "sha256:a18e1ca20c7c679ad7aa7d273ece13fbb76d6533dec8378272d9bdac3239013d", "data_as_of": "2026-09-24T07:59:35Z" } } } } }, "400": { "description": "A parameter or the cursor is not valid.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "country must be an ISO 3166-1 alpha-2 code such as GB.", "hint": "List the codes with GET /api/v1/countries.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "404": { "description": "No such resource.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No area with that id.", "hint": "Find area ids with GET /api/v1/areas?country=XX.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported; the Allow header lists them.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "GET, HEAD, OPTIONS", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "POST is not supported: the public API is read-only.", "hint": "Use GET (or HEAD).", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After seconds.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded: 60 requests per 60 seconds per client.", "hint": "Wait 42 seconds (Retry-After) before the next request.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "500": { "description": "An unexpected error on our side.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "hint": "Retry later; if it persists, write to support with the request_id.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } }, "503": { "description": "The data is temporarily unavailable.", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable.", "hint": "Retry later.", "request_id": "6f1c2e9a-8a3b-4d55-9a0e-2b7f0c1d4e5f" } } } } } } } } }, "components": { "headers": { "API-Version": { "description": "The API version that answered: 1.", "schema": { "type": "string", "enum": [ "1" ] } }, "RateLimit": { "description": "Remaining requests (r) and seconds until the window resets (t), IETF draft-ietf-httpapi-ratelimit-headers syntax: \"public\";r=59;t=42.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "The quota: \"public\";q=60;w=60 (60 requests per 60 seconds per client IP address).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests allowed per window.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "When the current window resets, in Unix seconds.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "The id of this request; the same as error.request_id on errors.", "schema": { "type": "string" } } }, "schemas": { "Error": { "type": "object", "description": "The body of every 4xx and 5xx response.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "invalid_parameter", "invalid_cursor", "not_found", "method_not_allowed", "cursor_expired", "rate_limited", "internal_error", "service_unavailable" ], "description": "Machine-readable error code." }, "message": { "type": "string", "description": "What went wrong, for people." }, "hint": { "type": "string", "description": "How to fix or work around it." }, "request_id": { "type": "string", "description": "The id of the request (also in X-Request-Id)." } } } } }, "Pagination": { "type": "object", "required": [ "limit", "next_cursor", "has_more" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The page size used." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether another page follows." } } }, "Meta": { "type": "object", "required": [ "api_version", "dataset_version", "data_as_of" ], "properties": { "api_version": { "type": "string", "enum": [ "1" ] }, "dataset_version": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Changes whenever the data snapshots change; cursors are bound to it." }, "data_as_of": { "type": "string", "format": "date-time", "description": "When the snapshot this response comes from was taken." } } }, "NumberType": { "type": "string", "enum": [ "local", "national", "mobile", "toll_free", "shared_cost", "global" ], "description": "The kind of number." }, "ApiIndex": { "type": "object", "required": [ "name", "version", "authentication", "documentation_url", "openapi_url", "endpoints" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string", "enum": [ "stable" ] }, "read_only": { "type": "boolean" }, "authentication": { "type": "string", "enum": [ "none" ] }, "documentation_url": { "type": "string", "format": "uri" }, "openapi_url": { "type": "string", "format": "uri" }, "openapi_yaml_url": { "type": "string", "format": "uri" }, "versioning_policy_url": { "type": "string", "format": "uri" }, "rate_limit": { "type": "object", "required": [ "requests", "window_seconds", "scope" ], "properties": { "requests": { "type": "integer" }, "window_seconds": { "type": "integer" }, "scope": { "type": "string" } } }, "endpoints": { "type": "array", "items": { "type": "object", "required": [ "method", "path", "url", "operation_id", "description" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "operation_id": { "type": "string" }, "description": { "type": "string" } } } }, "billing_terms": { "type": "object", "description": "Terms every number shares.", "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "tax_included": { "type": "boolean" }, "setup_price_cents": { "type": "integer" }, "prepay_periods_months": { "type": "array", "items": { "type": "integer" } }, "longer_periods_discounted": { "type": "boolean" }, "contract": { "type": "string" }, "usage_billing": { "type": "string" } } } } }, "Country": { "type": "object", "required": [ "code", "name", "calling_code", "number_types", "area_count", "monthly_price_from_cents", "currency", "offered", "page_urls", "order_url" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2." }, "name": { "type": "string" }, "calling_code": { "type": "string", "pattern": "^[0-9]{1,4}$", "description": "Country calling code without +." }, "number_types": { "type": "array", "items": { "$ref": "#/components/schemas/NumberType" } }, "area_count": { "type": "integer", "minimum": 0, "description": "Areas in the snapshot (of type, when filtered). Not a stock count." }, "monthly_price_from_cents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Lowest monthly price among the areas that had numbers at the snapshot, in US cents, tax included; null when no price is published." }, "currency": { "type": "string", "enum": [ "USD" ] }, "offered": { "type": [ "boolean", "null" ], "description": "Whether new numbers in this country can be bought now; null when that could not be checked." }, "page_urls": { "type": "object", "required": [ "virtual_number", "toll_free" ], "properties": { "virtual_number": { "type": [ "string", "null" ], "format": "uri" }, "toll_free": { "type": [ "string", "null" ], "format": "uri" } } }, "order_url": { "type": "string", "format": "uri", "description": "The number picker for this country, where the user chooses and buys a number." } } }, "Registration": { "type": [ "object", "null" ], "description": "What the holder must provide before the number is activated; null when the snapshot does not say.", "required": [ "documents_required", "holder", "address_required_in", "identity_documents", "address_documents", "service_description_required", "summary" ], "properties": { "documents_required": { "type": "boolean" }, "holder": { "type": "string", "enum": [ "personal", "business", "any" ], "description": "Who may hold the number: an individual, a business, or either." }, "address_required_in": { "type": [ "string", "null" ], "enum": [ "world_wide", "country", "area", "city", null ], "description": "Where the holder's address must be; null when no address is asked for." }, "identity_documents": { "type": "integer", "minimum": 0 }, "address_documents": { "type": "integer", "minimum": 0 }, "service_description_required": { "type": "boolean" }, "summary": { "type": "string" } } }, "Area": { "type": "object", "required": [ "id", "country", "name", "city", "region", "prefix", "type", "features", "monthly_price_cents", "setup_price_cents", "currency", "tax_included", "toll_free_incoming_per_minute", "availability", "registration", "page_url", "order_url" ], "properties": { "id": { "type": "string", "description": "Stable public id: country, family (vn = virtual number, tf = toll-free) and page slug." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "name": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "prefix": { "type": "string", "description": "Dialling prefix after the country code." }, "type": { "$ref": "#/components/schemas/NumberType" }, "features": { "type": "array", "items": { "type": "string", "enum": [ "voice_in", "voice_out", "sms_in", "sms_out", "fax_t38" ] }, "description": "May grow with new values." }, "monthly_price_cents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Monthly price in US cents, tax included; null when no price is published (unknown, not free)." }, "setup_price_cents": { "type": [ "integer", "null" ], "minimum": 0, "description": "0: there is no setup fee; null when the monthly price is unknown." }, "currency": { "type": "string", "enum": [ "USD" ] }, "tax_included": { "type": "boolean", "enum": [ true ] }, "toll_free_incoming_per_minute": { "type": [ "object", "null" ], "description": "Toll-free numbers only: per-minute price of incoming calls in US dollars (decimal strings).", "properties": { "all": { "type": [ "string", "null" ] }, "fixed": { "type": [ "string", "null" ] }, "mobile": { "type": [ "string", "null" ] } } }, "availability": { "type": "object", "required": [ "available_at_snapshot", "observed_at", "stock_count", "country_offered" ], "properties": { "available_at_snapshot": { "type": "boolean", "description": "Whether the area had numbers when the snapshot was taken." }, "observed_at": { "type": "string", "format": "date-time" }, "stock_count": { "type": "null", "description": "Not published." }, "country_offered": { "type": [ "boolean", "null" ], "description": "Whether new numbers in the country can be bought now; null when unknown." } } }, "registration": { "$ref": "#/components/schemas/Registration" }, "page_url": { "type": "string", "format": "uri" }, "order_url": { "type": "string", "format": "uri" } } }, "CallingRate": { "type": "object", "required": [ "destination", "country", "matched_prefix", "offered", "price_per_minute", "first_interval_price", "first_interval_seconds", "currency", "tax_included", "rates_url" ], "properties": { "destination": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO code of the destination where known." }, "matched_prefix": { "type": [ "string", "null" ], "description": "The longest prefix that matched, without +. null when no rule matched, or when the matching rule is the complete number (the number is never echoed; rates_url is then the plain /rates page)." }, "offered": { "type": "boolean" }, "price_per_minute": { "type": [ "string", "null" ], "description": "US dollars per minute as a decimal string; null when not offered." }, "first_interval_price": { "type": [ "string", "null" ], "description": "Charge for the first interval where the destination bills one; null otherwise." }, "first_interval_seconds": { "type": [ "integer", "null" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "tax_included": { "type": "boolean", "enum": [ true ] }, "rates_url": { "type": "string", "format": "uri" } } }, "ForwardingRate": { "type": "object", "required": [ "country", "destination", "to_sip_voip_app", "to_phone", "exact_rate", "rates_url" ], "properties": { "country": { "type": "string" }, "destination": { "type": "string" }, "to_sip_voip_app": { "type": "object", "required": [ "price_per_minute" ], "properties": { "price_per_minute": { "type": "string", "enum": [ "0" ] } } }, "to_phone": { "type": "object", "required": [ "price_per_minute_min", "price_per_minute_max", "offered", "currency", "tax_included" ], "properties": { "price_per_minute_min": { "type": [ "string", "null" ] }, "price_per_minute_max": { "type": [ "string", "null" ] }, "offered": { "type": "boolean" }, "currency": { "type": "string", "enum": [ "USD" ] }, "tax_included": { "type": "boolean", "enum": [ true ] } } }, "exact_rate": { "type": "object", "required": [ "endpoint", "description" ], "properties": { "endpoint": { "type": "string" }, "description": { "type": "string" } } }, "rates_url": { "type": "string", "format": "uri" } } } } } }