@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/phone-validation/bulk-phone-number-validation.yaml

@@ -0,0 +1,374 @@
+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.
+
+          - **International format** (`+` prefix): provide `number` only.
+          - **Local format** (no `+`): provide `number` + `region`.
+          - **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'
+        '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'
+        '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.
+        '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'
+        '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: []