{ "openapi": "3.1.0", "info": { "title": "PHONE-CHECK.APP Public API", "description": "**Phone number validation and intelligence API for production applications.**\n\nUse PHONE-CHECK.APP to validate phone numbers, normalize formats, identify carriers and line types, detect disposable numbers, and process bulk phone validation jobs.\n\n**Authentication:** Use `x-api-key: YOUR_API_KEY` or `?x-api-key=YOUR_API_KEY` for phone lookup endpoints. Dashboard endpoints for managing API keys, usage exports, and bulk jobs use bearer authentication from your signed-in account.\n\n**Support:** support@phone-check.app • Documentation: [phone-check.app](https://phone-check.app)", "contact": { "name": "PHONE-CHECK.APP Team", "url": "https://phone-check.app", "email": "support@phone-check.app" }, "license": { "name": "Proprietary license", "url": "https://phone-check.app/terms-of-service" }, "termsOfService": "https://phone-check.app/terms-of-service", "version": "1.0.0" }, "servers": [ { "url": "https://api.phone-check.app", "description": "Production Server", "variables": {} } ], "tags": [ { "name": "Phone Lookup", "description": "Validate a single phone number and retrieve carrier, line type, location, and formatting signals." }, { "name": "Bulk Validation", "description": "Upload, monitor, download, and resume bulk phone validation jobs." }, { "name": "API Keys", "description": "Create and manage API keys used by phone-check integrations." }, { "name": "Usage", "description": "Review and export usage for phone validation requests." }, { "name": "Authentication", "description": "Inspect the authenticated account context used by dashboard API calls." } ], "paths": { "/v1-get-phone-details": { "get": { "tags": ["Phone Lookup"], "summary": "Validate a phone number", "parameters": [ { "schema": { "type": "string", "minLength": 6, "maxLength": 20, "example": "+14155552671" }, "required": true, "name": "phone", "in": "query", "description": "Phone number to validate. Use E.164 format when possible, such as +14155552671.", "example": "+14155552671" } ], "responses": { "200": { "description": "Phone validation result for the requested number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneLookupResult" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "validatePhoneNumber", "description": "Validate one phone number and return normalized number data, carrier hints, line type, location, timezone, and disposable-number signals when available.", "security": [ { "APIKeyHeader": [] }, { "APIKeyQueryParam": [] } ] } }, "/v1-get-phone-extra-details": { "get": { "tags": ["Phone Lookup"], "summary": "Get extended phone intelligence", "parameters": [ { "schema": { "type": "string", "minLength": 6, "maxLength": 20, "example": "+14155552671" }, "required": true, "name": "phone", "in": "query", "description": "Phone number to enrich. Use E.164 format when possible, such as +14155552671.", "example": "+14155552671" } ], "responses": { "200": { "description": "Extended phone intelligence for the requested number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneIntelligenceResult" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "getPhoneIntelligence", "description": "Return expanded phone intelligence for workflows that need local and international formats, country details, carrier candidates, and line-type classification.", "security": [ { "APIKeyHeader": [] }, { "APIKeyQueryParam": [] } ] } }, "/v1-upload-phone-json": { "post": { "tags": ["Bulk Validation"], "summary": "Start a bulk validation job", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartBulkPhoneValidationRequest" } } }, "description": "JSON rows and field mapping for a bulk phone validation job." }, "responses": { "200": { "description": "Bulk validation job created for the upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPhoneValidationJob" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "startBulkPhoneValidation", "description": "Upload JSON rows and identify the phone-number field. The API creates a validation job and returns the initial job counters.", "security": [ { "BearerAuth": [] } ] } }, "/v1-list-upload-phone-json": { "post": { "tags": ["Bulk Validation"], "summary": "List bulk validation jobs", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBulkPhoneValidationJobsRequest" } } }, "description": "Optional filters and pagination for bulk validation jobs." }, "responses": { "200": { "description": "Paginated bulk validation jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBulkPhoneValidationJobsResponse" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "listBulkPhoneValidationJobs", "description": "List the authenticated account's bulk phone validation jobs, optionally filtered by batch ID or job status.", "security": [ { "BearerAuth": [] } ] } }, "/v1-download-phone-json": { "post": { "tags": ["Bulk Validation"], "summary": "Download bulk validation results", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadBulkPhoneValidationRequest" } } }, "description": "Batch identifier for the bulk validation results to download." }, "responses": { "200": { "description": "Bulk validation records and summary counters for the requested batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPhoneValidationResults" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "downloadBulkPhoneValidationResults", "description": "Fetch processed validation records and job counters for a completed or in-progress bulk phone validation batch.", "security": [ { "BearerAuth": [] } ] } }, "/v1-resume-phone-json": { "post": { "tags": ["Bulk Validation"], "summary": "Resume a bulk validation job", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeBulkPhoneValidationRequest" } } }, "description": "Batch identifier and optional stuck-job threshold for retrying a bulk validation job." }, "responses": { "200": { "description": "Resume result for the requested bulk validation job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeBulkPhoneValidationResponse" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "resumeBulkPhoneValidationJob", "description": "Retry a stuck or failed bulk validation job by re-queueing pending records and resetting recoverable failed records.", "security": [ { "BearerAuth": [] } ] } }, "/v1-create-api-key": { "post": { "tags": ["API Keys"], "summary": "Create an API key", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "description": "API key settings." }, "responses": { "200": { "description": "Created API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "createApiKey", "description": "Create an API key for phone-check integrations. Use the returned key with single-number lookup endpoints.", "security": [ { "BearerAuth": [] } ] } }, "/v1-list-api-keys": { "post": { "tags": ["API Keys"], "summary": "List API keys", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysRequest" } } }, "description": "Optional request body. Send an empty object to list all keys." }, "responses": { "200": { "description": "API keys for the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponse" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "listApiKeys", "description": "List API keys available to the authenticated phone-check account.", "security": [ { "BearerAuth": [] } ] } }, "/v1-get-api-key-details": { "post": { "tags": ["API Keys"], "summary": "Get API key details", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiKeyRequest" } } }, "description": "API key identifier to fetch." }, "responses": { "200": { "description": "API key details, or null if the key is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDetails" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "getApiKey", "description": "Fetch the status, allowed services, and metadata for one API key.", "security": [ { "BearerAuth": [] } ] } }, "/v1-update-api-key": { "post": { "tags": ["API Keys"], "summary": "Update an API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } }, "description": "API key identifier plus fields to update." }, "responses": { "200": { "description": "Updated API key, or null if the key is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatedApiKey" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "updateApiKey", "description": "Rename an API key, update enabled services, or enable and disable the key.", "security": [ { "BearerAuth": [] } ] } }, "/v1-delete-api-key": { "post": { "tags": ["API Keys"], "summary": "Delete an API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiKeyRequest" } } }, "description": "API key identifier to delete." }, "responses": { "200": { "description": "Delete confirmation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiKeyResponse" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "deleteApiKey", "description": "Delete an API key so it can no longer be used for phone lookup requests.", "security": [ { "BearerAuth": [] } ] } }, "/v1-get-api-usage": { "get": { "tags": ["Usage"], "summary": "View API usage", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query", "description": "Start date for the usage window, formatted as YYYY-MM-DD." }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query", "description": "End date for the usage window, formatted as YYYY-MM-DD." }, { "schema": { "type": "string" }, "required": false, "name": "service", "in": "query", "description": "Optional service filter. Use get-phone-details for phone lookup traffic." } ], "responses": { "200": { "description": "Daily usage rows for the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "listUsage", "description": "Return daily usage rows for phone-check requests in the selected date range.", "security": [ { "BearerAuth": [] } ] } }, "/v1-download-api-usage": { "get": { "tags": ["Usage"], "summary": "Download API usage", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query", "description": "Start date for the usage window, formatted as YYYY-MM-DD." }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query", "description": "End date for the usage window, formatted as YYYY-MM-DD." }, { "schema": { "type": "string" }, "required": false, "name": "service", "in": "query", "description": "Optional service filter. Use get-phone-details for phone lookup traffic." } ], "responses": { "200": { "description": "Download URL and file metadata for the usage export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageExport" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "createUsageExport", "description": "Create a downloadable usage export for phone-check requests in the selected date range.", "security": [ { "BearerAuth": [] } ] } }, "/v1-who-am-i": { "get": { "tags": ["Authentication"], "summary": "Check authentication context", "responses": { "200": { "description": "Authenticated account and request context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationContext" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "getAuthenticationContext", "description": "Return the account and request context currently associated with the bearer token.", "security": [ { "BearerAuth": [] } ] } } }, "components": { "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Pass your phone-check API key in the `x-api-key` request header." }, "APIKeyQueryParam": { "type": "apiKey", "in": "query", "name": "x-api-key", "description": "Pass your phone-check API key as the `x-api-key` query parameter." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token for signed-in dashboard requests, such as managing API keys, bulk jobs, and usage exports." } }, "schemas": { "PhoneLookupResult": { "type": "object", "properties": { "number": { "type": "string", "description": "Normalized phone number in E.164 format when available." }, "valid": { "type": "boolean", "description": "Whether the submitted phone number appears valid." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code associated with the phone number." }, "callingCode": { "type": "string", "description": "Country calling code without the plus sign." }, "nationalNumber": { "type": "string", "description": "National phone number without the country calling code." }, "type": { "type": "string", "description": "Detected line type, such as mobile, landline, or VoIP." }, "isDisposable": { "type": "boolean", "description": "Whether the number matches a disposable or temporary-number pattern." }, "carrier": { "type": "string", "description": "Best available carrier name for the phone number." }, "matchedCarriers": { "type": "array", "items": { "type": "string" }, "description": "Possible carrier matches when more than one carrier candidate is available." }, "geo": { "type": "string", "description": "Best available geographic area for the phone number." }, "timezones": { "type": "array", "items": { "type": "string" }, "description": "Timezones associated with the phone number location." }, "error": { "type": "string", "description": "Validation message when the submitted number cannot be validated." } }, "required": ["valid"], "description": "Validation and enrichment result for a single phone number.", "example": { "number": "+14155552671", "valid": true, "country": "US", "callingCode": "1", "nationalNumber": "4155552671", "type": "MOBILE", "isDisposable": false, "carrier": "Example Wireless", "matchedCarriers": ["Example Wireless"], "geo": "SAN FRANCISCO, CA", "timezones": ["America/Los_Angeles"] } }, "PhoneIntelligenceResult": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the submitted phone number appears valid." }, "number": { "type": "string", "description": "Normalized phone number in E.164 format when available." }, "localFormat": { "type": "string", "description": "Phone number formatted for local display." }, "internationalFormat": { "type": "string", "description": "Phone number formatted for international display." }, "countryPrefix": { "type": "string", "description": "International dialing prefix, including the plus sign." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "countryName": { "type": "string", "description": "Country name associated with the phone number." }, "location": { "type": "string", "description": "Best available city, region, or location label." }, "carrier": { "type": "string", "description": "Best available carrier name." }, "matchedCarriers": { "type": "array", "items": { "type": "string" }, "description": "Possible carrier matches when multiple candidates are available." }, "lineType": { "type": "string", "description": "Detected line type, such as mobile, landline, or VoIP." }, "isDisposable": { "type": "boolean", "description": "Whether the number matches a disposable or temporary-number pattern." } }, "description": "Extended phone intelligence for formatting, geography, carrier, and line-type workflows.", "example": { "valid": true, "number": "+14155552671", "localFormat": "(415) 555-2671", "internationalFormat": "+1 415-555-2671", "countryPrefix": "+1", "countryCode": "US", "countryName": "United States", "location": "San Francisco, CA", "carrier": "Example Wireless", "matchedCarriers": ["Example Wireless"], "lineType": "mobile", "isDisposable": false } }, "StartBulkPhoneValidationRequest": { "type": "object", "properties": { "jsonData": { "nullable": true, "description": "Array of JSON records to validate." }, "phoneField": { "nullable": true, "description": "Field name in each JSON record that contains the phone number." }, "fileName": { "nullable": true, "description": "Display filename for the uploaded job." }, "fileColumns": { "nullable": true, "description": "Optional column metadata shown when viewing or exporting results." } }, "additionalProperties": { "nullable": true }, "summary": "Start bulk phone validation", "description": "JSON payload used to start a bulk phone validation job.", "example": { "jsonData": [ { "customerId": "cust_001", "phone": "+14155552671" }, { "customerId": "cust_002", "phone": "+442071838750" } ], "phoneField": "phone", "fileName": "customers-phone-list.json", "fileColumns": ["customerId", "phone"] } }, "BulkPhoneValidationJob": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the job was created successfully." }, "batchId": { "type": "string", "description": "Unique batch identifier used to list, download, or resume this job." }, "totalRecords": { "type": "number", "description": "Number of records accepted for validation." }, "processedRecords": { "type": "number", "description": "Number of records processed so far." }, "validRecords": { "type": "number", "description": "Number of records validated as valid so far." }, "invalidRecords": { "type": "number", "description": "Number of records validated as invalid so far." }, "status": { "type": "string", "description": "Current job status." } }, "required": [ "success", "batchId", "totalRecords", "processedRecords", "validRecords", "invalidRecords", "status" ], "description": "Initial status and counters for a bulk phone validation job.", "example": { "success": true, "batchId": "batch_123", "totalRecords": 2, "processedRecords": 0, "validRecords": 0, "invalidRecords": 0, "status": "pending" } }, "ListBulkPhoneValidationJobsRequest": { "type": "object", "properties": { "batchId": { "type": "string", "description": "Optional batch identifier to return one job." }, "page": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "default": 1, "description": "Page number to return." }, "limit": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "default": 20, "description": "Maximum number of jobs to return." }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Optional job status filter." } }, "additionalProperties": { "nullable": true }, "summary": "List bulk phone validation jobs", "description": "Filters and pagination for bulk phone validation jobs.", "example": { "page": 1, "limit": 20, "status": "completed" } }, "ListBulkPhoneValidationJobsResponse": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, "batchId": { "type": "string" }, "fileName": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] }, "totalRecords": { "type": "number" }, "processedRecords": { "type": "number" }, "validRecords": { "type": "number" }, "invalidRecords": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z" }, "errorMessage": { "type": "string" }, "liveness": { "type": "object", "properties": { "isStuck": { "type": "boolean" }, "staleForMs": { "type": "number" }, "stuckThresholdMs": { "type": "number" } }, "required": ["isStuck", "staleForMs", "stuckThresholdMs"] } }, "required": [ "_id", "batchId", "fileName", "status", "totalRecords", "processedRecords", "validRecords", "invalidRecords", "createdAt", "updatedAt", "liveness" ] }, "description": "Bulk validation jobs for the current page." }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "number" }, "totalPages": { "type": "number" }, "totalRecords": { "type": "number" }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": ["currentPage", "totalPages", "totalRecords", "hasNext", "hasPrev"], "description": "Pagination details for the result set." } }, "required": ["list", "pagination"], "description": "Paginated list of bulk phone validation jobs.", "example": { "list": [], "pagination": { "currentPage": 1, "totalPages": 0, "totalRecords": 0, "hasNext": false, "hasPrev": false } } }, "DownloadBulkPhoneValidationRequest": { "type": "object", "properties": { "batchId": { "type": "string", "minLength": 1, "description": "Batch identifier returned when the job was created." } }, "required": ["batchId"], "additionalProperties": { "nullable": true }, "summary": "Download bulk validation results", "description": "Request body used to retrieve validation records for a bulk job.", "example": { "batchId": "batch_123" } }, "BulkPhoneValidationResults": { "type": "object", "properties": { "_id": { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, "fileName": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/BulkPhoneValidationRecord" } }, "totalRecords": { "type": "number" }, "validRecords": { "type": "number" }, "invalidRecords": { "type": "number" }, "fileColumns": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z" } }, "required": [ "_id", "fileName", "status", "records", "totalRecords", "validRecords", "invalidRecords", "createdAt", "updatedAt" ], "description": "Validation records and summary counters for one bulk phone validation job.", "example": { "_id": "507f1f77bcf86cd799439011", "fileName": "customers-phone-list.json", "status": "completed", "records": [ { "phoneNumber": "+14155552671", "isValid": true, "validationStatus": "valid", "validationDetails": { "carrier": "Example Wireless", "type": "MOBILE" }, "originalData": { "customerId": "cust_001", "phone": "+14155552671" } } ], "totalRecords": 1, "validRecords": 1, "invalidRecords": 0, "fileColumns": ["customerId", "phone"], "createdAt": "2025-01-01T12:00:00.000Z", "updatedAt": "2025-01-01T12:01:00.000Z" } }, "BulkPhoneValidationRecord": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "Phone number extracted from the source row." }, "isValid": { "type": "boolean", "description": "Whether the phone number passed validation." }, "validationStatus": { "type": "string", "description": "Validation status for this row." }, "validationDetails": { "nullable": true, "description": "Validation details returned for the phone number, when available." }, "error": { "type": "string", "description": "Row-level error message when validation fails." }, "originalData": { "nullable": true, "description": "Original JSON row submitted for validation." } }, "required": ["phoneNumber", "isValid", "validationStatus"], "additionalProperties": { "nullable": true }, "description": "One phone validation result from a bulk job.", "example": { "phoneNumber": "+14155552671", "isValid": true, "validationStatus": "valid", "validationDetails": { "carrier": "Example Wireless", "type": "MOBILE" }, "originalData": { "customerId": "cust_001", "phone": "+14155552671" } } }, "ResumeBulkPhoneValidationRequest": { "type": "object", "properties": { "batchId": { "type": "string", "minLength": 1, "description": "Batch identifier returned when the job was created." }, "stuckAfterMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Optional threshold, in milliseconds, used to decide whether a pending job is stuck." } }, "required": ["batchId"], "summary": "Resume bulk phone validation", "description": "Request body used to retry a stuck or failed bulk validation job.", "example": { "batchId": "batch_123", "stuckAfterMs": 300000 } }, "ResumeBulkPhoneValidationResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "batchId": { "type": "string" }, "status": { "type": "string", "enum": ["resumed", "completed", "no-pending", "not-stuck"] }, "pendingRecords": { "type": "number" }, "resetFailedRecords": { "type": "number" } }, "required": ["success", "batchId", "status", "pendingRecords", "resetFailedRecords"], "description": "Outcome of a bulk validation resume request.", "example": { "success": true, "batchId": "batch_123", "status": "resumed", "pendingRecords": 12, "resetFailedRecords": 3 } }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Friendly name shown in the dashboard." }, "services": { "type": "array", "items": { "type": "string" }, "description": "Services enabled for this key. Use `phone` for phone-check integrations." }, "isEnabled": { "type": "boolean", "description": "Whether the key can be used immediately after creation." } }, "additionalProperties": { "nullable": true }, "summary": "Create API key", "description": "Settings for a new phone-check API key.", "example": { "name": "Production Key", "services": ["phone"], "isEnabled": true } }, "ApiKey": { "type": "object", "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique API key record ID." }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Account user ID that owns the key." }, "apiKey": { "type": "string", "description": "Secret API key value. Store it securely and send it with phone lookup requests." }, "name": { "type": "string", "description": "Friendly key name shown in the dashboard." }, "environment": { "type": "string", "description": "Environment label for the key." }, "services": { "type": "array", "items": { "type": "string" }, "description": "Enabled services for this key, such as phone." }, "isEnabled": { "type": "boolean", "description": "Whether the key is currently active." }, "host": { "type": "string", "description": "Product host associated with the key." }, "note": { "type": "string", "description": "Optional note for the key." }, "meta": { "nullable": true, "description": "Additional request or dashboard metadata associated with the key." }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was created." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was last updated." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "API key created for phone-check requests." }, "ListApiKeysRequest": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true }, "summary": "List API keys", "description": "Optional request body for listing API keys. Send an empty object to return all keys." }, "ListApiKeysResponse": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeySummary" }, "description": "API keys available to the authenticated account." } }, "required": ["list"], "description": "API keys for the authenticated account.", "example": { "list": [] } }, "GetApiKeyRequest": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "API key record ID." } }, "required": ["_id"], "additionalProperties": { "nullable": true }, "summary": "Get API key details", "description": "Request body used to fetch one API key by ID.", "example": { "_id": "507f1f77bcf86cd799439011" } }, "ApiKeyDetails": { "type": "object", "nullable": true, "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique API key record ID." }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Account user ID that owns the key." }, "apiKey": { "type": "string", "description": "Secret API key value. Store it securely and send it with phone lookup requests." }, "name": { "type": "string", "description": "Friendly key name shown in the dashboard." }, "environment": { "type": "string", "description": "Environment label for the key." }, "services": { "type": "array", "items": { "type": "string" }, "description": "Enabled services for this key, such as phone." }, "isEnabled": { "type": "boolean", "description": "Whether the key is currently active." }, "host": { "type": "string", "description": "Product host associated with the key." }, "note": { "type": "string", "description": "Optional note for the key." }, "meta": { "nullable": true, "description": "Additional request or dashboard metadata associated with the key." }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was created." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was last updated." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "API key details for a key owned by the authenticated account, or null when no key is found.", "example": { "_id": "507f1f77bcf86cd799439011", "userId": "507f1f77bcf86cd799439012", "apiKey": "507f1f77bcf86cd799439012-abc123", "name": "Production Key", "environment": "production", "services": ["phone"], "isEnabled": true, "host": "phone-check.app", "note": "Used by production workload", "meta": { "reqIpAddress": "127.0.0.1" }, "createdAt": "2025-01-01T12:00:00.000Z", "updatedAt": "2025-01-01T12:00:00.000Z" } }, "UpdateApiKeyRequest": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "API key record ID." }, "name": { "type": "string", "maxLength": 255, "description": "New friendly key name." }, "environment": { "type": "string", "description": "Environment label for the key." }, "services": { "type": "array", "items": { "type": "string" }, "description": "Services enabled for this key. Use `phone` for phone-check integrations." }, "isEnabled": { "type": "boolean", "description": "Whether the key should be active." } }, "required": ["_id"], "additionalProperties": { "nullable": true }, "summary": "Update API key", "description": "Fields that can be changed on an existing API key." }, "UpdatedApiKey": { "type": "object", "nullable": true, "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique API key record ID." }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Account user ID that owns the key." }, "apiKey": { "type": "string", "description": "Secret API key value. Store it securely and send it with phone lookup requests." }, "name": { "type": "string", "description": "Friendly key name shown in the dashboard." }, "environment": { "type": "string", "description": "Environment label for the key." }, "services": { "type": "array", "items": { "type": "string" }, "description": "Enabled services for this key, such as phone." }, "isEnabled": { "type": "boolean", "description": "Whether the key is currently active." }, "host": { "type": "string", "description": "Product host associated with the key." }, "note": { "type": "string", "description": "Optional note for the key." }, "meta": { "nullable": true, "description": "Additional request or dashboard metadata associated with the key." }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was created." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was last updated." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "Updated API key details, or null when no key is found.", "example": { "_id": "507f1f77bcf86cd799439011", "userId": "507f1f77bcf86cd799439012", "apiKey": "507f1f77bcf86cd799439012-abc123", "name": "Production Key", "environment": "production", "services": ["phone"], "isEnabled": true, "host": "phone-check.app", "note": "Used by production workload", "meta": { "reqIpAddress": "127.0.0.1" }, "createdAt": "2025-01-01T12:00:00.000Z", "updatedAt": "2025-01-01T12:00:00.000Z" } }, "DeleteApiKeyRequest": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "API key record ID." } }, "required": ["_id"], "additionalProperties": { "nullable": true }, "summary": "Delete API key", "description": "Request body used to delete one API key by ID." }, "DeleteApiKeyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the key was deleted successfully." } }, "required": ["success"], "description": "Confirmation that the API key was deleted.", "example": { "success": true } }, "ApiKeySummary": { "type": "object", "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique API key record ID." }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique record ID." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Account user ID that owns the key." }, "apiKey": { "type": "string", "description": "Secret API key value. Store it securely and send it with phone lookup requests." }, "name": { "type": "string", "description": "Friendly key name shown in the dashboard." }, "environment": { "type": "string", "description": "Environment label for the key." }, "services": { "type": "array", "items": { "type": "string" }, "description": "Enabled services for this key, such as phone." }, "isEnabled": { "type": "boolean", "description": "Whether the key is currently active." }, "host": { "type": "string", "description": "Product host associated with the key." }, "note": { "type": "string", "description": "Optional note for the key." }, "meta": { "nullable": true, "description": "Additional request or dashboard metadata associated with the key." }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was created." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Time the key was last updated." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "API key summary shown when listing keys." }, "UsageSummary": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "service": { "type": "string" }, "count": { "type": "number" }, "userId": { "type": "string" } }, "required": ["date", "service", "count", "userId"] }, "description": "Daily usage rows for phone-check API requests.", "example": [ { "date": "2026-03-12", "service": "get-phone-details", "count": 14, "userId": "507f1f77bcf86cd799439011" } ] }, "UsageExport": { "type": "object", "properties": { "url": { "type": "string", "description": "Temporary URL for downloading the usage export." }, "filename": { "type": "string", "description": "Suggested filename for the export." }, "contentType": { "type": "string", "description": "MIME type of the export file." } }, "required": ["url", "filename", "contentType"], "description": "Download metadata for a generated API usage export.", "example": { "url": "https://phone-check.app/api/exports/usage.csv", "filename": "phone-check-usage-2026-03-12.csv", "contentType": "text/csv" } }, "AuthenticationContext": { "type": "object", "properties": { "userId": { "type": "string", "nullable": true, "description": "Authenticated account user ID, when available." }, "email": { "type": "string", "nullable": true, "description": "Authenticated account email, when available." }, "username": { "type": "string", "nullable": true, "description": "Authenticated account username, when available." }, "reqIpAddress": { "type": "string", "nullable": true, "description": "IP address seen by the API for this request." }, "reqIpCountry": { "type": "string", "nullable": true, "description": "Country inferred from the request IP address." }, "reqUserAgent": { "type": "string", "nullable": true, "description": "User agent sent with the request." } }, "description": "Account and request context associated with the current bearer token.", "example": { "userId": "507f1f77bcf86cd799439011", "email": "developer@example.com", "username": "developer", "reqIpAddress": "203.0.113.10", "reqIpCountry": "US", "reqUserAgent": "curl/8.0.0" } }, "BadRequestError": { "type": "object", "properties": { "error": { "type": "string", "example": "VALIDATION_ERROR", "description": "Error code identifier" }, "message": { "type": "string", "example": "Invalid request parameters", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "description": "Standard error response returned when the request cannot be completed." }, "UnauthorizedError": { "type": "object", "properties": { "error": { "type": "string", "example": "AUTHENTICATION_REQUIRED", "description": "Error code identifier" }, "message": { "type": "string", "example": "Authentication token is required", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "description": "Standard error response returned when the request cannot be completed." }, "PaymentRequiredError": { "type": "object", "properties": { "error": { "type": "string", "example": "PAYMENT_REQUIRED", "description": "Error code identifier" }, "message": { "type": "string", "example": "Insufficient credits", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "description": "Standard error response returned when the request cannot be completed." }, "ForbiddenError": { "type": "object", "properties": { "error": { "type": "string", "example": "ACCESS_DENIED", "description": "Error code identifier" }, "message": { "type": "string", "example": "You do not have permission to perform this action", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "description": "Standard error response returned when the request cannot be completed." }, "NotFoundError": { "type": "object", "properties": { "error": { "type": "string", "example": "NOT_FOUND", "description": "Error code identifier" }, "message": { "type": "string", "example": "The requested resource was not found", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "description": "Standard error response returned when the request cannot be completed." }, "TooManyRequestsError": { "type": "object", "properties": { "error": { "type": "string", "example": "RATE_LIMIT_EXCEEDED", "description": "Error code identifier" }, "message": { "type": "string", "example": "Too many requests, please try again later", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "description": "Standard error response returned when the request cannot be completed." }, "InternalServerError": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_SERVER_ERROR", "description": "Error code identifier" }, "message": { "type": "string", "example": "An unexpected error occurred", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "description": "Standard error response returned when the request cannot be completed." }, "ErrorIssue": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ] } }, "additionalProperties": { "nullable": true }, "description": "Structured validation detail for a specific field or request value." } } } }