proweblook-com Phone API

openapi: 3.2.0
info:
  title: ProWebLook Phone API
  description: ProWebLook APIs for WhatsApp verification, phone validation, email verification, caller identification, IP geolocation, blacklist checking, social scraping, Google SERP, and AI visibility audits. Phone, WhatsApp validation, caller ID, blacklist, spam, email validation, and URL scrape live on lookup.proweblook.com; social scrapers, SERP, and audits live on proweblook.com. Authentication placement is endpoint-specific; consult each operation for its required API-key location. New accounts receive 50 one-time free credits for each of WhatsApp verification, phone validation, caller ID, email verification, social scrapers (shared across Reddit, X, and LinkedIn), blacklist checking, Google SERP, AI visibility audits, spam checking, and URL scraping/screenshots. Granted once per account, never expires, and never renews. GeoIP remains 20,000 free requests per month with no extra 50-credit signup grant. Anonymous SERP playground requests remain limited to 10 per day and are separate from account credits.
  version: 1.0.0
  contact:
    name: ProWebLook Support
    url: https://proweblook.com/contact
    email: support@proweblook.com
  termsOfService: https://proweblook.com/generic/terms_conditions
  x-logo:
    url: https://proweblook.com/upload/logo.png
servers:
- url: https://proweblook.com/api/v1
  description: Production API server
security:
- apiKey: []
tags:
- name: Phone
  description: Phone number validation and caller identification
paths:
  /phonevalidation:
    servers:
    - url: https://lookup.proweblook.com/api/v1
      description: ProWebLook production lookup API
    get:
      summary: Validate a phone number
      description: Validate and enrich one phone number. GET requires api_key and phone_number in the query string. When country_code is omitted or set to none, send a full international number including its country calling code, preferably in E.164 form. A local or national number requires country_code. One credit is deducted from phoneapi_balance per successful validation.
      operationId: validatePhoneNumberGet
      tags:
      - Phone
      externalDocs:
        description: Complete Phone Validation documentation
        url: https://docs.proweblook.com/api-reference/phone-validation
      security:
      - apiKey: []
      parameters:
      - name: phone_number
        in: query
        required: true
        allowReserved: false
        description: Phone number to validate. URL-encode a leading + as %2B. A local/national value requires country_code.
        schema:
          $ref: '#/components/schemas/PhoneNumberInput'
      - name: country_code
        in: query
        required: false
        description: Optional ISO country hint for a local or national phone number.
        schema:
          $ref: '#/components/schemas/PhoneCountryCode'
      responses:
        '200':
          $ref: '#/components/responses/PhoneValidationOk'
        '400':
          $ref: '#/components/responses/PhoneValidationBadRequest'
        '401':
          $ref: '#/components/responses/PhoneValidationUnauthorized'
        '402':
          $ref: '#/components/responses/PhoneValidationNoCredits'
        '500':
          $ref: '#/components/responses/PhoneValidationServerError'
    post:
      summary: Validate a phone number
      description: Validate and enrich one phone number using a JSON or form body. api_key and phone_number are required in the body. When country_code is omitted or set to none, send a full international number including its country calling code, preferably in E.164 form. A local or national number requires country_code. One credit is deducted from phoneapi_balance per successful validation. The empty OpenAPI security override does not mean this operation accepts unauthenticated requests; OpenAPI 3.0 cannot represent an API key located in a request body.
      operationId: validatePhoneNumberPost
      tags:
      - Phone
      externalDocs:
        description: Complete Phone Validation documentation
        url: https://docs.proweblook.com/api-reference/phone-validation
      security: []
      x-api-key-location: requestBody
      requestBody:
        required: true
        description: POST authentication and phone-validation fields. api_key must be included in this body.
        content:
          application/json:
            schema:
              type: object
              required:
              - phone_number
              - api_key
              properties:
                phone_number:
                  $ref: '#/components/schemas/PhoneNumberInput'
                country_code:
                  $ref: '#/components/schemas/PhoneCountryCode'
                api_key:
                  type: string
                  format: password
                  writeOnly: true
                  description: Your ProWebLook API key.
                  example: YOUR_API_KEY
            examples:
              internationalNumber:
                summary: Complete international number
                value:
                  phone_number: '+14155552671'
                  api_key: YOUR_API_KEY
              localNumberWithCountryHint:
                summary: Local number with an ISO country hint
                value:
                  phone_number: '9876543210'
                  country_code: IN
                  api_key: YOUR_API_KEY
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - phone_number
              - api_key
              properties:
                phone_number:
                  $ref: '#/components/schemas/PhoneNumberInput'
                country_code:
                  $ref: '#/components/schemas/PhoneCountryCode'
                api_key:
                  type: string
                  format: password
                  writeOnly: true
                  description: Your ProWebLook API key.
                  example: YOUR_API_KEY
            example:
              phone_number: '9876543210'
              country_code: IN
              api_key: YOUR_API_KEY
      responses:
        '200':
          $ref: '#/components/responses/PhoneValidationOk'
        '400':
          $ref: '#/components/responses/PhoneValidationBadRequest'
        '401':
          $ref: '#/components/responses/PhoneValidationUnauthorized'
        '402':
          $ref: '#/components/responses/PhoneValidationNoCredits'
        '500':
          $ref: '#/components/responses/PhoneValidationServerError'
  /calleridvalidation:
    servers:
    - url: https://lookup.proweblook.com/api/v1
      description: Lookup API host
    get:
      summary: Caller ID Lookup
      description: Reverse phone lookup (CNAM). Not the monolith /check path.
      operationId: callerIdLookup
      tags:
      - Phone
      externalDocs:
        description: Caller ID documentation
        url: https://docs.proweblook.com/api-reference/caller-id-validation
      parameters:
      - name: phone_number
        in: query
        required: true
        schema:
          type: string
          example: '+919876543210'
      responses:
        '200':
          description: Caller information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallerInfoResponse'
components:
  schemas:
    PhoneValidationErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable description of the request failure.
          example: Invalid API key.
    PhoneCountryCode:
      type: string
      pattern: ^([A-Za-z]{2}|none)$
      description: Optional ISO 3166-1 alpha-2 country hint such as US, IN, or GB. This is a country identifier, not a numeric calling prefix such as +1 or +91. Omit it, or use the literal value none, only with a complete international phone_number.
      example: IN
    CallerInfoResponse:
      type: object
      properties:
        status:
          type: boolean
          example: true
        number:
          type: string
          example: '+1234567890'
        name:
          type: string
          example: John Doe
        carrier:
          type: string
          example: AT&T
        line_type:
          type: string
          example: mobile
        location:
          type: string
          example: New York, NY
    PhoneValidationResponse:
      type: object
      required:
      - status
      description: A completed phone-validation result. INVALID is a normal result and may contain only status; enrichment fields are not guaranteed for an invalid number.
      properties:
        status:
          type: string
          enum:
          - VALID_CONFIRMED
          - INVALID
          description: VALID_CONFIRMED for a confirmed number or INVALID when the supplied number could not be validated.
          example: VALID_CONFIRMED
        formatted_number:
          type: string
          description: Internationally formatted number returned by the API.
          example: +1 415 555 2671
        linetype:
          type: string
          enum:
          - Mobile
          - Fixed Line
          - Fixed Line or Mobile
          - Toll-Free
          - Premium Rate
          - Shared Cost
          - VoIP
          - Personal Number
          - Pager
          - Universal Access Number
          - Voicemail
          - Unknown
          example: Mobile
        carrier:
          type: string
          description: Carrier/operator name. May be an empty string for landlines.
          example: T-Mobile
        location:
          type: string
          description: Geographic description such as a city, region, or country.
          example: California
        countrycodenum:
          type: integer
          description: Numeric country calling code.
          example: 1
        countrycode:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: US
        countryname:
          type: string
          description: Full country name.
          example: United States
        formatnational:
          type: string
          description: Phone number in national display format.
          example: (415) 555-2671
        formatinternational:
          type: string
          description: Phone number in international display format.
          example: +1 415 555 2671
        timezone:
          type: array
          description: Applicable IANA timezone identifiers.
          items:
            type: string
          example:
          - America/Los_Angeles
        ratelimit_remain:
          type: integer
          description: Calls remaining in the current rate-limit window.
          example: 100
        ratelimit_seconds:
          type: integer
          description: Seconds until the current rate-limit window resets.
          example: 100
    PhoneNumberInput:
      type: string
      description: Phone number to validate. When country_code is omitted or set to none, send the complete international number, preferably in E.164 form, including the leading + and country calling code (for example, +14155552671). A local or national number requires country_code (for example, phone_number=9876543210 with country_code=IN). Percent-encode a leading + as %2B in a GET URL.
      example: '+14155552671'
  responses:
    PhoneValidationBadRequest:
      description: A required parameter is missing or a parameter is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PhoneValidationErrorResponse'
          example:
            error: PhoneNumber is missing in the request.
    PhoneValidationOk:
      description: Validation completed. INVALID is a completed validation result returned with HTTP 200, not an API error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PhoneValidationResponse'
          examples:
            valid:
              summary: Confirmed valid number
              value:
                status: VALID_CONFIRMED
                formatted_number: +1 415 555 2671
                linetype: Mobile
                carrier: T-Mobile
                location: California
                countrycodenum: 1
                countrycode: US
                countryname: United States
                formatnational: (415) 555-2671
                formatinternational: +1 415 555 2671
                timezone:
                - America/Los_Angeles
                ratelimit_remain: 100
                ratelimit_seconds: 100
            invalid:
              summary: Invalid number
              value:
                status: INVALID
    PhoneValidationServerError:
      description: An unexpected server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PhoneValidationErrorResponse'
          example:
            error: Description of the error.
    PhoneValidationUnauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PhoneValidationErrorResponse'
          example:
            error: Invalid API key.
    PhoneValidationNoCredits:
      description: The account has insufficient phone-validation credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PhoneValidationErrorResponse'
          example:
            error: Insufficient phone API credits.
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: api_key
      description: Your ProWebLook API key. Get a free key at https://proweblook.com/auth/signup
externalDocs:
  description: ProWebLook Documentation
  url: https://docs.proweblook.com/api-reference/