openapi: 3.2.0
info:
  title: DomScan Phone Intelligence API
  description: DomScan is a domain intelligence API providing domain analysis tools.
  version: 2.15.0
  contact:
    name: DomScan Support
    url: https://domscan.net
    email: support@domscan.net
  termsOfService: https://domscan.net/legal/terms
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://domscan.net
  description: Production server
security:
- apiKey: []
tags:
- name: Phone Intelligence
  description: Privacy-first phone number validation and formatting against bundled numbering-plan metadata
paths:
  /v1/phone/validate:
    post:
      tags:
      - Phone Intelligence
      summary: Validate and normalize a phone number
      description: 'Validate one phone number against maintained international numbering-plan metadata and offline public-allocation data.


        The endpoint accepts international numbers, national numbers with a two-letter default_country, extensions, Unicode digits, vanity numbers, short numbers with country context, and RFC 3966 tel: URIs. Parsing is strict, so unrelated text surrounding a number is rejected rather than silently extracted. Optional dialing_from_country adds caller-relative dialing formats, while language selects the language used for offline location and carrier labels.


        The stable validation fields include E.164, international, national, and RFC 3966 formats, country or region, calling code, possible regions, number type, extension, country-match intelligence, and a decision-oriented status. The additive intelligence object can include a country-specific coverage level, numbering-plan location, possible time zones, original prefix carrier, regional portability support, dialing guidance, short-number signals, service classification, official allocation records, source provenance, and explicit accuracy warnings. United States results can match daily NANPA NPA-NXX central office code records. Canadian results can match nightly CNA/CNAC NPA-NXX status records. These sources describe prefix status and the original code holder, not the current carrier of a ported individual number.


        **Privacy and scope:** The submitted number is checked using offline metadata and downloaded regulator snapshots. Customer lookups make zero paid or per-number third-party requests and the number is not persisted. A valid result means the number matches a current numbering-plan pattern. Location is a numbering-plan description, carrier is the original prefix carrier, and regulator data describes an allocated range. None proves that the individual number is assigned, active, reachable, owned by a particular subscriber, or currently served by any carrier.


        **Credits:** 1 credit per number.'
      operationId: validatePhoneNumber
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneValidationRequest'
            examples:
              international:
                summary: International number
                value:
                  phone: +34 612 345 678
                  expected_country: ES
                  dialing_from_country: US
                  language: es
              national:
                summary: National number with country context
                value:
                  phone: 0491 570 006
                  default_country: AU
              extension:
                summary: Number with an extension
                value:
                  phone: +1 202-555-0123 ext. 456
              shortNumber:
                summary: Short number with country context
                value:
                  phone: '112'
                  default_country: ES
                  language: es
      responses:
        '200':
          description: Numbering-plan validation result. Invalid phone values are returned as structured HTTP 200 results; malformed request bodies return HTTP 400.
          headers:
            Cache-Control:
              schema:
                type: string
                example: no-store
              description: Phone validation responses are never shared-cacheable.
            X-Credits-Used:
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Phone validation failed unexpectedly
      x-domscan-credits:
        model: per_request
        default: 1
  /v1/phone/validate/bulk:
    post:
      tags:
      - Phone Intelligence
      summary: Validate up to 100 phone numbers
      description: 'Validate and enrich up to 100 phone numbers in one request. Input order and duplicates are preserved.


        The phones field can contain strings or objects. Shared default_country, expected_country, dialing_from_country, and language values apply to every item unless an item overrides them. This makes mixed-country national-number and caller-relative dialing batches possible without separate HTTP requests.


        Core validation is deterministic and uses bundled numbering-plan metadata. Enrichment uses offline metadata and downloaded regulator snapshots. There are zero paid or per-number third-party requests. Individual-number assignment, reachability, current carrier, subscriber identity, and current porting state are not checked. If enrichment is unavailable, every result still contains deterministic validation plus intelligence.status=unavailable.


        **Credits:** 1 credit per submitted number with no bulk discount.'
      operationId: validatePhoneNumbersBulk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneValidationBulkRequest'
            example:
              expected_country: ES
              dialing_from_country: US
              language: en
              phones:
              - +34 612 345 678
              - phone: 0491 570 006
                default_country: AU
                expected_country: AU
                dialing_from_country: GB
                language: en
              - +800 1234 5678
      responses:
        '200':
          description: Ordered phone validation results with aggregate counts
          headers:
            Cache-Control:
              schema:
                type: string
                example: no-store
              description: Phone validation responses are never shared-cacheable.
            X-Credits-Used:
              schema:
                type: integer
                example: 3
              description: Total per-item credit cost for the accepted batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneValidationBulkResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Bulk phone validation failed unexpectedly
      x-domscan-credits:
        model: per_item
        default: 1
components:
  schemas:
    PhoneIntelligenceTimeZones:
      type: object
      description: Possible IANA time zones inferred from numbering-plan prefixes, not from current device location.
      required:
      - values
      - current_location
      - inference
      properties:
        values:
          type: array
          items:
            type: string
            example: Europe/Madrid
        current_location:
          type: boolean
          enum:
          - false
        inference:
          type: string
          enum:
          - number_prefix
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code for programmatic handling
              example: INVALID_DOMAIN
            type:
              type: string
              enum:
              - authentication_error
              - credits_error
              - permission_error
              - not_found_error
              - conflict_error
              - rate_limit_error
              - timeout_error
              - validation_error
              - upstream_error
              - api_error
              - request_error
              description: Stable error category used by official SDK subclasses
            message:
              type: string
              description: Human-readable error message
              example: Invalid domain format
            status:
              type: integer
              minimum: 400
              maximum: 599
              description: HTTP status repeated in the JSON error for queue and log processors
            retryable:
              type: boolean
              description: Whether retrying can be appropriate after applying retry guidance
            request_id:
              type: string
              description: Request identifier matching the X-Request-Id response header
            suggestion:
              type: string
              description: Suggestion for fixing the error
            details:
              type: object
              description: Optional structured context for the error
              additionalProperties: true
            retry_after:
              type: integer
              minimum: 0
              description: Seconds to wait before retrying when the error is temporary
              example: 300
            docs_url:
              type: string
              description: Link to relevant documentation
              example: /docs#parameters
          required:
          - type
          - code
          - message
          - status
          - retryable
          - request_id
          - docs_url
    PhoneIntelligenceRelay:
      type: object
      description: Whether supplemental offline enrichment was configured and contributed data.
      required:
      - configured
      - used
      - persisted
      properties:
        configured:
          type: boolean
        used:
          type: boolean
        persisted:
          type: boolean
          enum:
          - false
    PhoneIntelligenceDialing:
      type: object
      description: Offline dialing guidance. Caller-relative fields use dialing_from_country when supplied.
      required:
      - from_country
      - international
      - mobile
      - internationally_diallable
      properties:
        from_country:
          type:
          - string
          - 'null'
          example: US
        international:
          type:
          - string
          - 'null'
          example: 011 34 612 34 56 78
        mobile:
          type:
          - string
          - 'null'
          example: +34 612 34 56 78
        internationally_diallable:
          type: boolean
    PhoneRegulatorAllocation:
      type: object
      description: Longest matching range from a downloaded official regulator snapshot. It describes a range allocation, not current routing, porting, or assignment of the submitted individual number.
      required:
      - authority
      - country
      - matched_prefix
      - matched_range_end
      - match_kind
      - category
      - status
      - original_assignee
      - operator_code
      - region
      - service_description
      - assigned_on
      - effective_on
      - expires_on
      - current_operator
      - portability_included
      - individual_number_assignment_checked
      - source_id
      - source_file
      - details
      properties:
        authority:
          type: string
          example: CNMC
        country:
          type: string
          example: ES
        matched_prefix:
          type: string
          example: '912'
        matched_range_end:
          type:
          - string
          - 'null'
        match_kind:
          type: string
          enum:
          - prefix
          - range
        category:
          type: string
          example: geographic
        status:
          type: string
          example: assigned
        original_assignee:
          type:
          - string
          - 'null'
          example: Example Telecom
        operator_code:
          type:
          - string
          - 'null'
        region:
          type:
          - string
          - 'null'
          example: Madrid
        service_description:
          type:
          - string
          - 'null'
        assigned_on:
          type:
          - string
          - 'null'
          format: date
        effective_on:
          type:
          - string
          - 'null'
          format: date
        expires_on:
          type:
          - string
          - 'null'
          format: date
        current_operator:
          type: boolean
          enum:
          - false
          description: Always false because the snapshot is not a live porting lookup.
        portability_included:
          type: boolean
          enum:
          - false
        individual_number_assignment_checked:
          type: boolean
          enum:
          - false
        source_id:
          type: string
          example: cnmc
        source_file:
          type:
          - string
          - 'null'
        details:
          type: object
          additionalProperties: true
    PhoneIntelligenceServiceSignals:
      type: object
      description: Numbering-plan service classification. These signals describe the prefix category and do not prove live service capabilities.
      required:
      - number_type
      - geographical
      - toll_free
      - premium_rate
      - shared_cost
      - voip
      - personal_number
      - likely_sms_capable
      properties:
        number_type:
          type: string
          enum:
          - fixed_line
          - mobile
          - fixed_line_or_mobile
          - toll_free
          - premium_rate
          - shared_cost
          - voip
          - personal_number
          - pager
          - uan
          - voicemail
          - unknown
        geographical:
          type: boolean
        toll_free:
          type: boolean
        premium_rate:
          type: boolean
        shared_cost:
          type: boolean
        voip:
          type: boolean
        personal_number:
          type: boolean
        likely_sms_capable:
          type:
          - boolean
          - 'null'
          description: A numbering-plan inference for mobile categories, not an SMS reachability check.
    PhoneIntelligence:
      type: object
      description: Deterministic additive enrichment. The object is always present, including when enrichment is unavailable or not applicable.
      required:
      - status
      - kind
      - reason
      - coverage
      - location
      - possible_time_zones
      - original_prefix_carrier
      - portability
      - dialing
      - number_details
      - service_signals
      - short_number
      - regulator_allocations
      - sources
      - warnings
      - relay
      properties:
        status:
          type: string
          enum:
          - available
          - partial
          - unavailable
          - not_applicable
        kind:
          type:
          - string
          - 'null'
          enum:
          - phone_number
          - short_code
        reason:
          type:
          - string
          - 'null'
          description: Machine-readable explanation when enrichment is unavailable or not applicable.
        coverage:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceCoverage'
        location:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceLocation'
        possible_time_zones:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceTimeZones'
        original_prefix_carrier:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceCarrier'
        portability:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligencePortability'
        dialing:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceDialing'
        number_details:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceNumberDetails'
        service_signals:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceServiceSignals'
        short_number:
          allOf:
          - $ref: '#/components/schemas/PhoneIntelligenceShortNumber'
        regulator_allocations:
          type: array
          items:
            $ref: '#/components/schemas/PhoneRegulatorAllocation'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/PhoneIntelligenceSource'
        warnings:
          type: array
          items:
            type: string
          description: Machine-readable accuracy and scope warnings, including original-carrier, location, allocation, and live-check limits.
        relay:
          $ref: '#/components/schemas/PhoneIntelligenceRelay'
    PhoneValidationRequest:
      type: object
      required:
      - phone
      properties:
        phone:
          type: string
          minLength: 1
          maxLength: 256
          example: +34 612 345 678
          description: International number, RFC 3966 tel URI, phone-shaped vanity number such as 1-800-FLOWERS, or national number when default_country is supplied. Text surrounding a number is rejected.
        default_country:
          $ref: '#/components/schemas/PhoneCountryCode'
          description: Parsing context required for national numbers. It is also used for country-match intelligence.
        expected_country:
          $ref: '#/components/schemas/PhoneCountryCode'
          description: Optional expected country or region. A mismatch adds COUNTRY_MISMATCH and changes an otherwise valid recommendation to review.
        dialing_from_country:
          $ref: '#/components/schemas/PhoneCountryCode'
          description: Optional caller country or region used to produce out-of-country and mobile dialing guidance. It does not change parsing or validation.
        language:
          $ref: '#/components/schemas/PhoneLanguageCode'
          description: Preferred language for offline numbering-plan location and original prefix-carrier labels.
    PhoneIntelligenceCoverage:
      type: object
      description: Country-specific offline coverage. Global metadata supports validation, geography, time zones, service type, and dialing. Official snapshots add regulator allocation evidence only where an openly reusable source is loaded.
      required:
      - country
      - level
      - global_numbering_metadata
      - official_snapshot_available
      - official_allocation_match
      - official_source_ids
      - matching_source_ids
      - current_carrier_lookup
      properties:
        country:
          type:
          - string
          - 'null'
          example: US
        level:
          type: string
          enum:
          - global_numbering_metadata
          - official_snapshot
          - official_allocation_match
        global_numbering_metadata:
          type: boolean
        official_snapshot_available:
          type: boolean
        official_allocation_match:
          type: boolean
        official_source_ids:
          type: array
          items:
            type: string
        matching_source_ids:
          type: array
          items:
            type: string
        current_carrier_lookup:
          type: boolean
          enum:
          - false
          description: Always false. DomScan performs no live carrier or portability query.
    PhoneValidationBulkResponse:
      type: object
      required:
      - total
      - valid_count
      - possible_only_count
      - invalid_count
      - validation_level
      - results
      - credits_used
      properties:
        total:
          type: integer
          minimum: 1
          maximum: 100
        valid_count:
          type: integer
          minimum: 0
        possible_only_count:
          type: integer
          minimum: 0
        invalid_count:
          type: integer
          minimum: 0
        validation_level:
          type: string
          enum:
          - numbering_plan
        results:
          type: array
          items:
            $ref: '#/components/schemas/PhoneValidationResult'
        credits_used:
          type: integer
          minimum: 1
          maximum: 100
    PhoneIntelligencePortability:
      type: object
      description: Whether the resolved region supports mobile number portability. The individual number current porting state is not queried.
      required:
      - region_supported
      - current_port_checked
      properties:
        region_supported:
          type: boolean
        current_port_checked:
          type: boolean
          enum:
          - false
    PhoneValidationResult:
      type: object
      required:
      - input
      - normalized_input
      - kind
      - valid
      - possible
      - status
      - recommendation
      - validation_level
      - reason
      - warnings
      - number
      - live_checks
      - privacy
      - intelligence
      - limitations
      - metadata
      properties:
        input:
          type: string
          description: The submitted value, echoed only in this response and not persisted.
        normalized_input:
          type: string
          description: Trimmed input after safe Unicode digit, RFC 3966, and supported phone-shaped vanity-number normalization.
        kind:
          type: string
          enum:
          - phone_number
          - unparseable
        valid:
          type: boolean
          description: Whether the number matches a current numbering-plan pattern.
        possible:
          type: boolean
          description: Whether the number has a possible length for its numbering plan.
        status:
          type: string
          enum:
          - valid
          - possible
          - invalid
        recommendation:
          type: string
          enum:
          - accept
          - review
          - reject
        validation_level:
          type: string
          enum:
          - numbering_plan
          description: Explicitly distinguishes metadata validation from live verification.
        reason:
          type:
          - string
          - 'null'
          enum:
          - DEFAULT_COUNTRY_REQUIRED
          - INPUT_TOO_LONG
          - NOT_A_NUMBER
          - INVALID_COUNTRY_CALLING_CODE
          - TOO_SHORT
          - TOO_LONG
          - INVALID_LENGTH
          - INVALID_PATTERN
        warnings:
          type: array
          items:
            type: string
            enum:
            - COUNTRY_MISMATCH
            - VANITY_NUMBER_CONVERTED
        number:
          type:
          - object
          - 'null'
          required:
          - e164
          - international
          - national
          - rfc3966
          - national_number
          - extension
          - country
          - country_name
          - country_calling_code
          - possible_countries
          - country_match
          - type
          - non_geographic
          properties:
            e164:
              type: string
              example: '+34612345678'
            international:
              type: string
              example: +34 612 34 56 78
            national:
              type: string
              example: 612 34 56 78
            rfc3966:
              type: string
              example: tel:+34612345678
            national_number:
              type: string
              example: '612345678'
            extension:
              type:
              - string
              - 'null'
              example: null
            country:
              type:
              - string
              - 'null'
              example: ES
            country_name:
              type:
              - string
              - 'null'
              example: Spain
            country_calling_code:
              type: string
              example: '34'
            possible_countries:
              type: array
              items:
                type: string
              example:
              - ES
            country_match:
              type:
              - boolean
              - 'null'
              description: Match against expected_country, or default_country when no explicit expectation is supplied. Null means no comparison or no definitive match was possible.
            type:
              type: string
              enum:
              - fixed_line
              - mobile
              - fixed_line_or_mobile
              - toll_free
              - premium_rate
              - shared_cost
              - voip
              - personal_number
              - pager
              - uan
              - voicemail
              - unknown
            non_geographic:
              type: boolean
        live_checks:
          type: object
          description: Live telecom checks intentionally not performed. Offline carrier and allocation metadata elsewhere in the response does not change these states.
          properties:
            assignment:
              type: string
              enum:
              - not_checked
            reachability:
              type: string
              enum:
              - not_checked
            current_carrier:
              type: string
              enum:
              - not_checked
            subscriber_identity:
              type: string
              enum:
              - not_checked
            porting:
              type: string
              enum:
              - not_checked
        privacy:
          type: object
          required:
          - upstream_requests
          - telecom_provider_queried
          - persisted
          - domscan_edge_relay_used
          - third_party_requests
          properties:
            upstream_requests:
              type: integer
              enum:
              - 0
              description: Zero paid or per-number external telecom or regulator requests. Optional offline enrichment is reported separately.
            telecom_provider_queried:
              type: boolean
              enum:
              - false
            persisted:
              type: boolean
              enum:
              - false
            domscan_edge_relay_used:
              type: boolean
              description: Whether DomScan processed the bounded value within its private infrastructure for offline enrichment.
            third_party_requests:
              type: integer
              enum:
              - 0
              description: Customer lookups do not call a paid provider, regulator portal, HLR, CNAM, carrier, or other third party.
        intelligence:
          $ref: '#/components/schemas/PhoneIntelligence'
        limitations:
          type: array
          items:
            type: string
        metadata:
          type: object
          properties:
            engine:
              type: string
              enum:
              - libphonenumber-js/max
            metadata_basis:
              type: string
              enum:
              - Google libphonenumber numbering plans
    PhoneIntelligenceCarrier:
      type: object
      description: Original prefix-carrier or code-holder metadata. The source and evidence fields distinguish bundled prefix metadata from an official allocation record. Number portability and thousands-block pooling mean this must never be interpreted as the current carrier.
      required:
      - name
      - source_id
      - evidence
      - current_carrier
      - portability_may_change_carrier
      properties:
        name:
          type:
          - string
          - 'null'
          example: Vodafone
        source_id:
          type:
          - string
          - 'null'
          example: nanpa_us
          description: Offline source that supplied the name, or null when no name is available.
        evidence:
          type: string
          enum:
          - offline_prefix_metadata
          - official_allocation_record
          - unavailable
        current_carrier:
          type: boolean
          enum:
          - false
        portability_may_change_carrier:
          type: boolean
    PhoneLanguageCode:
      type: string
      minLength: 2
      maxLength: 6
      pattern: ^[A-Za-z]{2,3}(?:[-_][A-Za-z]{2})?$
      example: es
      description: Preferred language for offline location and original-carrier labels. Accepts a two- or three-letter language code with an optional two-letter region, such as en, es, or zh-CN. Unsupported labels fall back safely in the enrichment engine.
    PhoneIntelligenceShortNumber:
      type: object
      description: Country-specific short-number metadata. Emergency behavior and cost classification depend on the dialing region.
      required:
      - region
      - possible
      - valid
      - emergency
      - connects_to_emergency
      - sms_service
      - carrier_specific
      - expected_cost
      properties:
        region:
          type: string
          example: ES
        possible:
          type: boolean
        valid:
          type: boolean
        emergency:
          type: boolean
        connects_to_emergency:
          type: boolean
        sms_service:
          type: boolean
        carrier_specific:
          type: boolean
        expected_cost:
          type: string
          enum:
          - toll_free
          - standard_rate
          - premium_rate
          - unknown
    PhoneValidationBulkRequest:
      type: object
      required:
      - phones
      properties:
        phones:
          type: array
          minItems: 1
          maxItems: 100
          description: Phone strings or per-item request objects. Input order and duplicates are preserved.
          items:
            oneOf:
            - type: string
              minLength: 1
              maxLength: 256
            - $ref: '#/components/schemas/PhoneValidationRequest'
        default_country:
          $ref: '#/components/schemas/PhoneCountryCode'
          description: Shared parsing context for national numbers.
        expected_country:
          $ref: '#/components/schemas/PhoneCountryCode'
          description: Shared expected country or region for mismatch detection.
        dialing_from_country:
          $ref: '#/components/schemas/PhoneCountryCode'
          description: Shared caller country or region for dialing guidance. Per-item objects can override it.
        language:
          $ref: '#/components/schemas/PhoneLanguageCode'
          description: Shared language for offline location and original-carrier labels. Per-item objects can override it.
    PhoneCountryCode:
      type: string
      minLength: 2
      maxLength: 2
      pattern: ^[A-Za-z]{2}$
      example: ES
      description: ISO 3166-1 alpha-2 country or region code supported by the bundled numbering metadata.
    PhoneIntelligenceSource:
      type: object
      description: Offline library or downloaded official dataset that contributed to this result.
      required:
      - id
      - name
      - type
      - url
      properties:
        id:
          type: string
          example: google_libphonenumber
        name:
          type: string
          example: Google libphonenumber metadata
        type:
          type: string
          enum:
          - offline_metadata
          - official_regulator_snapshot
        version:
          type:
          - string
          - 'null'
          example: 9.0.34
        updated_at:
          type:
          - string
          - 'null'
        retrieved_at:
          type:
          - string
          - 'null'
          format: date-time
        age_days:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Age of an official regulator snapshot in whole days when its source date is known.
        record_count:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Number of normalized records loaded from this official source.
        license:
          type:
          - string
          - 'null'
          example: Apache-2.0
        license_url:
          type:
          - string
          - 'null'
          format: uri
        url:
          type: string
          format: uri
        attribution:
          type:
          - string
          - 'null'
    PhoneIntelligenceNumberDetails:
      type: object
      description: Additional structural details from offline numbering-plan metadata.
      required:
      - geographical
      - geographical_area_code
      - geographical_area_code_length
      - national_destination_code
      - national_destination_code_length
      - subscriber_number_length
      - mobile_token
      properties:
        geographical:
          type: boolean
        geographical_area_code:
          type:
          - string
          - 'null'
          description: Geographic area-code digits inferred from the numbering plan, such as 202 for a Washington, D.C. NANP number.
        geographical_area_code_length:
          type: integer
          minimum: 0
        national_destination_code:
          type:
          - string
          - 'null'
          description: National destination code digits inferred from the numbering plan. This is often the NANP area code for United States and Canadian numbers.
        national_destination_code_length:
          type: integer
          minimum: 0
        subscriber_number_length:
          type: integer
          minimum: 0
        mobile_token:
          type:
          - string
          - 'null'
    PhoneIntelligenceLocation:
      type: object
      description: Offline numbering-plan location. This is never the device or subscriber current physical location.
      required:
      - label
      - country_name
      - country
      - language
      - granularity
      - current_physical_location
      properties:
        label:
          type:
          - string
          - 'null'
          example: Madrid
          description: Localized area or country label when the prefix metadata has one.
        country_name:
          type:
          - string
          - 'null'
          example: Spain
        country:
          type:
          - string
          - 'null'
          example: ES
          description: Resolved numbering-plan region.
        language:
          type: string
          example: es
        granularity:
          type: string
          enum:
          - numbering_plan_area
          - country
          description: Whether the label describes a numbering-plan area or only the numbering-plan country. It does not expose device coordinates.
        current_physical_location:
          type: boolean
          enum:
          - false
          description: Always false. No live device-location lookup is performed.
    PhoneValidationResponse:
      allOf:
      - $ref: '#/components/schemas/PhoneValidationResult'
      - type: object
        required:
        - credits_used
        properties:
          credits_used:
            type: integer
            example: 1
  responses:
    RateLimited:
      description: Rate limit exceeded. Free accounts can sustain 120 requests per minute per account with a burst capacity of 60. Free bulk traffic is additionally limited to 20 requests per minute per account across all bulk endpoints and 100 per minute per IPv4 address or IPv6 /56 network. Paid accounts can sustain 600 requests per minute with a burst capacity of 120.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Plan:
          schema:
            type: string
            enum:
            - free
            - paid
          description: The account plan whose policy was applied.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The immediate burst capacity, or the active bulk fixed-window limit when a bulk-specific limit is exceeded.
        X-RateLimit-Remaining:
          schema:
            type: integer
            example: 0
          description: Immediate burst tokens remaining, or requests remaining in the active bulk fixed window.
        X-RateLimit-Policy:
          schema:
            type: string
          description: Machine-readable summary of the active tier and limit policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: RATE_LIMITED
              message: Rate limit exceeded. Please wait before making more requests.
    PaymentRequired:
      description: Insufficient credits for this request
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining on your API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits. This endpoint costs 2 credits but you have 0. Purchase more at https://domscan.net/billing or wait for your monthly reset.
              credits_remaining: 0
              credits_required: 2
              purchase_url: https://domscan.net/billing
    Unauthorized:
      description: 'Authentication required. All API endpoints require a valid API key (x-api-key header or Authorization: Bearer) or an active session cookie.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: AUTH_REQUIRED
              message: 'Authentication required. Provide an API key via x-api-key header or Authorization: Bearer header.'
              docs: https://domscan.net/docs/authentication
              get_key: https://domscan.net/login
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: BAD_REQUEST
              message: Invalid domain format
              suggestion: Domain must be a valid format like example.com
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key for authentication. Get yours free at https://domscan.net. Also accepts Authorization: Bearer header.'
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: Active DomScan browser session. Used by account-management endpoints.
externalDocs:
  description: Full API Documentation
  url: https://domscan.net/docs
x-rapidapi-product: domscan
x-domscan-rate-limits:
  free:
    general:
      scope: account
      sustained_requests_per_minute: 120
      burst_capacity: 60
      shared_across_api_keys_and_sessions: true
    bulk:
      scope: all bulk endpoints combined
      account_requests_per_minute: 20
      network_requests_per_minute: 100
      ipv6_network_prefix: 56
  paid:
    general:
      scope: API key for key-authenticated requests; IP for browser sessions
      sustained_requests_per_minute: 600
      burst_capacity: 120
    free_bulk_budget_applies: false
  response:
    status: 429
    retry_header: Retry-After
    headers_on_every_authenticated_response:
    - X-RateLimit-Plan
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    - X-RateLimit-Policy
    burst_headers:
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    policy_header: X-RateLimit-Policy
x-domscan-response-metadata:
  compatibility: additive response headers; established JSON success bodies are unchanged
  headers:
    X-Request-Id: Unique request identifier for logs and support
    X-API-Version: DomScan API release version
    X-Response-Time: Server processing duration in milliseconds
    X-Credits-Requested: Credits requested before refund settlement
    X-Credits-Charged: Credits retained after settlement
    X-Credits-Refunded: Credits returned during settlement
    X-Credits-Remaining: Authenticated account balance after the request
    X-Data-Freshness: fresh, cached, stale, mixed, or unknown
    X-RateLimit-Limit: Active burst capacity
    X-RateLimit-Remaining: Remaining burst capacity
    X-RateLimit-Plan: Active plan, or not_applicable before authentication
    X-RateLimit-Policy: Machine-readable active rate policy