@apifreaks/openapi-specs 0.1.0

package/specs/phone-validation/bulk-phone-number-validation.json

@@ -0,0 +1,518 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Bulk Phone Validation API - Validate and Verify Numbers and Carrier in Batches",
+    "version": "1.0.0",
+    "description": "Validate up to 100 phone numbers in a single POST request. Each number is processed independently — invalid entries return per-number results without affecting the rest of the batch. Returns an array of validation results with the same structure as the single Phone Validation API.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Bulk Phone Validation API Server"
+    }
+  ],
+  "paths": {
+    "/phone/validation/bulk": {
+      "post": {
+        "tags": ["Phone Validation APIs"],
+        "summary": "Bulk validate phone numbers",
+        "description": "Validates up to 100 phone numbers in a single request. Each number is processed independently — invalid entries return per-number errors without affecting the rest of the batch.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Specifies the desired format for the API response. Choose 'json' for a JSON object. If not provided, the API defaults to JSON format."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "Send a JSON object with a `numbers` array. Each item must have `number` and optionally `region` **or** `dialer_region` — never both at the same time.\n\n- **International format** (`+` prefix): provide `number` only.\n- **Local format** (no `+`): provide `number` + `region`.\n- **IDD format** (exit code): provide `number` + `dialer_region`.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BulkPhoneValidationRequest"
+              },
+              "examples": {
+                "international_format": {
+                  "summary": "International format numbers (+ prefix) — no region needed",
+                  "value": {
+                    "numbers": [
+                      {
+                        "number": "+14155552671"
+                      },
+                      {
+                        "number": "+447911123456"
+                      },
+                      {
+                        "number": "+919876543210"
+                      }
+                    ]
+                  }
+                },
+                "local_format_with_region": {
+                  "summary": "Local format numbers — use region (not dialer_region)",
+                  "value": {
+                    "numbers": [
+                      {
+                        "number": "03301112233",
+                        "region": "PK"
+                      },
+                      {
+                        "number": "07911123456",
+                        "region": "GB"
+                      },
+                      {
+                        "number": "09876543210",
+                        "region": "IN"
+                      }
+                    ]
+                  }
+                },
+                "mixed": {
+                  "summary": "Mixed formats in one batch",
+                  "value": {
+                    "numbers": [
+                      {
+                        "number": "+14155552671"
+                      },
+                      {
+                        "number": "03301112233",
+                        "region": "PK"
+                      },
+                      {
+                        "number": "0014155552671",
+                        "dialer_region": "AU"
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Array of phone validation results, one entry per requested number, in the same order. A number that fails validation is not a separate error object — it's the same result shape with error/message added and possible/valid set to false. An item missing the required number field is silently omitted from the array rather than causing an error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkPhoneValidationResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "All numbers resolved",
+                    "value": [
+                      {
+                        "raw_input": {
+                          "number": "+14155552671"
+                        },
+                        "possible": true,
+                        "valid": true,
+                        "country_prefix": 1,
+                        "national_number": 4155552671,
+                        "country_code": "US",
+                        "location": "San Francisco, CA",
+                        "time_zones": ["America/Los_Angeles"],
+                        "line_type": "FIXED_LINE_OR_MOBILE",
+                        "formats": {
+                          "E164": "+14155552671",
+                          "International": "+1 415-555-2671",
+                          "National": "(415) 555-2671",
+                          "RFC3966": "tel:+1-415-555-2671"
+                        },
+                        "area_code_length": 3,
+                        "ndc_length": 3,
+                        "can_be_internationally_dialled": true
+                      }
+                    ]
+                  },
+                  "partialFailure": {
+                    "summary": "Mix of a valid and an invalid-format number — the failure is embedded in the item, not a separate error object",
+                    "value": [
+                      {
+                        "raw_input": {
+                          "number": "+14155552671"
+                        },
+                        "possible": true,
+                        "valid": true,
+                        "country_prefix": 1,
+                        "national_number": 4155552671,
+                        "country_code": "US",
+                        "location": "San Francisco, CA",
+                        "time_zones": ["America/Los_Angeles"],
+                        "line_type": "FIXED_LINE_OR_MOBILE",
+                        "formats": {
+                          "E164": "+14155552671",
+                          "International": "+1 415-555-2671",
+                          "National": "(415) 555-2671",
+                          "RFC3966": "tel:+1-415-555-2671"
+                        },
+                        "area_code_length": 3,
+                        "ndc_length": 3,
+                        "can_be_internationally_dialled": true
+                      },
+                      {
+                        "raw_input": {
+                          "number": "abcdefg"
+                        },
+                        "possible": false,
+                        "valid": false,
+                        "error": "Invalid Number Format",
+                        "message": "The input does not match the expected structure of a phone number."
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request – Missing or malformed request body",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingNumbers": {
+                    "summary": "numbers field missing or malformed",
+                    "value": {
+                      "error": "Invalid request body Exception",
+                      "message": "Please provide data in required format in request body",
+                      "path": "/v1.0/phone/validation/bulk",
+                      "status": 400,
+                      "timestamp": "2026-07-27T12:56:50.387Z"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "Payload Too Large – Request body exceeds the size limit",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "payloadTooLarge": {
+                    "summary": "Too many numbers / body too large",
+                    "value": {
+                      "error": "Payload too large Exception",
+                      "message": "Maximum request body size limit exceeded",
+                      "path": "/v1.0/phone/validation/bulk",
+                      "status": 413,
+                      "timestamp": "2026-07-27T12:57:03.711Z"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "408": {
+            "description": "Request Timeout – Timed out while connecting to the remote server",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "error": {
+                    "summary": "Error response",
+                    "value": {
+                      "timestamp": "2026-06-06T14:00:00.000Z",
+                      "path": "/v1.0/phone/validation/bulk",
+                      "status": 408,
+                      "error": "Request Timeout",
+                      "message": "Timed out while connecting to the remote URL."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found – Wrong HTTP method used on the endpoint (e.g. GET instead of POST)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "wrongMethod": {
+                    "summary": "GET used instead of POST",
+                    "value": {
+                      "error": "Resource Not Found",
+                      "message": "The requested resource could not be found. Please verify the URL and try again.",
+                      "path": "/v1.0/phone/validation/bulk",
+                      "status": 404,
+                      "timestamp": "2026-07-27T12:58:41.535Z"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate Limit Exceeded – API rate limit exceeded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "error": {
+                    "summary": "Error response",
+                    "value": {
+                      "timestamp": "2026-06-06T14:00:00.000Z",
+                      "path": "/v1.0/phone/validation/bulk",
+                      "status": 429,
+                      "error": "Too Many Requests",
+                      "message": "API rate limit exceeded."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "operationId": "bulkValidatePhoneNumbers"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "BulkPhoneValidationResponse": {
+        "type": "array",
+        "description": "Array of per-number results, one entry per requested phone number that had a number field, in the same order as the request. Items missing number are silently omitted rather than erroring.",
+        "items": {
+          "$ref": "#/components/schemas/PhoneValidationResponse"
+        }
+      },
+      "PhoneValidationResponse": {
+        "type": "object",
+        "properties": {
+          "raw_input": {
+            "$ref": "#/components/schemas/PhoneRawInput"
+          },
+          "possible": {
+            "type": "boolean",
+            "description": "Whether the number is possible (length and format checks only). A number can be possible but not valid."
+          },
+          "valid": {
+            "type": "boolean",
+            "description": "Whether the number is valid according to the numbering plan."
+          },
+          "country_prefix": {
+            "type": "integer",
+            "description": "The international dialing prefix for the number's country (e.g., 1 for US/Canada, 44 for United Kingdom)."
+          },
+          "national_number": {
+            "type": "integer",
+            "description": "The national significant number (the phone number without the country code)."
+          },
+          "country_code": {
+            "type": "string",
+            "description": "ISO-2 country code inferred from the number (e.g., US, GB)."
+          },
+          "carrier": {
+            "type": "string",
+            "description": "Carrier name associated with the number (if available). May not reflect ported carriers."
+          },
+          "location": {
+            "type": "string",
+            "description": "Geographic description (city/region) for the number (if applicable)."
+          },
+          "time_zones": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of possible time zones associated with the number."
+          },
+          "line_type": {
+            "type": "string",
+            "description": "Classification of the phone line (MOBILE, FIXED_LINE, VOIP, etc.).",
+            "enum": [
+              "MOBILE",
+              "FIXED_LINE",
+              "FIXED_LINE_OR_MOBILE",
+              "VOIP",
+              "TOLL_FREE",
+              "PREMIUM_RATE",
+              "SHARED_COST",
+              "PERSONAL_NUMBER",
+              "PAGER",
+              "UAN",
+              "VOICEMAIL",
+              "UNKNOWN"
+            ]
+          },
+          "formats": {
+            "$ref": "#/components/schemas/PhoneFormats"
+          },
+          "area_code_length": {
+            "type": "integer",
+            "description": "Length of the geographic area code. Only applies to geographically-assigned numbers."
+          },
+          "ndc_length": {
+            "type": "integer",
+            "description": "Length of the National Destination Code (NDC), the routing prefix within a country."
+          },
+          "can_be_internationally_dialled": {
+            "type": "boolean",
+            "description": "Whether the number can be dialled internationally. false for short codes, emergency numbers, and domestic-only services."
+          },
+          "error": {
+            "type": "string",
+            "description": "Short error category. Present only when this item failed validation (e.g. malformed number, conflicting region parameters)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable reason for failure. Present only when this item failed validation."
+          }
+        },
+        "description": "Phone validation result for a single number in the batch. When the number fails validation, error/message are populated instead of the full metadata fields, and possible/valid are false.",
+        "required": ["raw_input", "possible", "valid"]
+      },
+      "PhoneRawInput": {
+        "type": "object",
+        "description": "Original request payload sent by the caller.",
+        "properties": {
+          "number": {
+            "type": "string",
+            "description": "The phone number as entered by the user."
+          },
+          "region": {
+            "type": "string",
+            "description": "ISO-2 country code."
+          },
+          "dialer_region": {
+            "type": "string",
+            "description": "ISO-2 country code of the dialing origin."
+          }
+        },
+        "required": ["number"]
+      },
+      "PhoneFormats": {
+        "type": "object",
+        "description": "Four standardized representations of the phone number.",
+        "properties": {
+          "E164": {
+            "type": "string",
+            "description": "Number in E.164 format."
+          },
+          "International": {
+            "type": "string",
+            "description": "Human-readable international format."
+          },
+          "National": {
+            "type": "string",
+            "description": "Local format as dialed within the country."
+          },
+          "RFC3966": {
+            "type": "string",
+            "description": "URI format following RFC 3966."
+          }
+        },
+        "required": []
+      },
+      "BulkPhoneValidationRequest": {
+        "type": "object",
+        "description": "Request body for bulk phone validation.",
+        "required": ["numbers"],
+        "properties": {
+          "numbers": {
+            "type": "array",
+            "description": "Array of phone number objects. Maximum 100 per request.",
+            "maxItems": 100,
+            "items": {
+              "$ref": "#/components/schemas/BulkPhoneNumberItem"
+            }
+          }
+        }
+      },
+      "BulkPhoneNumberItem": {
+        "type": "object",
+        "description": "A single phone number entry in a bulk validation request.",
+        "required": ["number"],
+        "properties": {
+          "number": {
+            "type": "string",
+            "description": "Phone number to validate."
+          },
+          "region": {
+            "type": "string",
+            "description": "Two-letter ISO country code. Required for local format numbers."
+          },
+          "dialer_region": {
+            "type": "string",
+            "description": "Two-letter ISO country code of the dialing origin. Required for IDD format numbers."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        },
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"]
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}