mobilevalidate-com Catalog API

openapi: 3.2.0
info:
  title: Mobilevalidate Com Catalog API
  version: 1.0.0
  contact:
    name: MobileValidate
    url: https://mobilevalidate.com/contact
  termsOfService: https://mobilevalidate.com/legal/terms
  description: 'Operations tagged catalog across 2 of this provider''s published API definitions: mobilevalidate-com-openapi.yaml, openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mobilevalidate.com/v1
  description: Production (live and test keys)
security:
- bearerAuth: []
tags:
- name: Catalog
  description: 'Service catalog (GET /v1/services is authoritative at run time).


    **Spam reputation (`number.spam`, alias `spam`).** Whether a phone number appears in spam and nuisance-call

    reports: telecom-regulator actions, government nuisance-call complaint data and community spam-report sites, plus

    whether the number looks unassigned — recently offered as an unassigned number, or in a range the national

    numbering plan has not assigned (a possible spoofed caller ID or fake lead) — and whether it is a premium-rate

    number. It is report-based: `no_reports` means we hold no reports for the number — it is **not** a statement that

    the number is safe. Countries: all, except sanctioned countries (see below). Attributes: `risk_level`

    (`high | medium | low | no_reports`), `risk_score` (integer 0–100, higher = more reports or risk signals), booleans

    `reason_regulator`, `reason_government`, `reason_community`, `reason_unassigned`, hint `voip_range` (VoIP carrier

    range or VoIP number type; adds no points), `top_category` (most frequent report category; `telemarketing` = in a

    range designated for telemarketing calls), `first_seen` / `last_seen` (YYYY-MM, when the number first/last appeared

    in our data), `sources` (integer, independent signal classes), `premium_rate` (premium-rate or international

    shared-cost number — a toll-fraud risk for OTP/verification traffic; adds 20 points but is not a signal class),

    hint `personal_number` (personal/call-forwarding or pager number type; adds no points). Attributes may be added

    over time; ignore unknown keys and enum values. Levels: `high` needs a regulator action or at least two

    independent signal classes. Billing: every `risk_level` including

    `no_reports` is a conclusive answer and is billed; `unknown` and `unsupported_country` are free. No report texts

    and no names are ever returned.


    **Live network status (`number.hlr`, alias `hlr`).** Live home-network query: `status`

    (`reachable | unreachable | invalid | unknown`), `ported`, `roaming` (yes/no only, no location), `network`,

    `mcc_mnc`, `country`. `reachable`, `unreachable` and `invalid` are conclusive and billed; `unknown` is free.


    **Number portability (`number.mnp`, alias `mnp`).** Whether a mobile number was ported to another network:

    `porting` (`ported | not_ported | unknown`), `mcc_mnc` and `country` of the current network. `ported` and

    `not_ported` are billed; `unknown` (including invalid numbers) is free.


    **Sanctioned countries.** Numbers from Cuba, Iran, North Korea, Syria, Russia, Belarus, Venezuela and sanctioned regions are never checked:

    every check answers `unsupported_country` and is free.'
paths:
  /services:
    get:
      tags:
      - Catalog
      operationId: listServices
      summary: List checks and prices
      description: 'Without a key: the public catalog. With a key: every check the key''s account may use, at the account''s prices. Lists active phone and e-mail checks; switched-off checks are not listed.'
      security:
      - {}
      - bearerAuth: []
      responses:
        '200':
          description: Service catalog with prices by mode.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                - has_more
                properties:
                  object:
                    type: string
                    const: list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Service'
                  has_more:
                    type: boolean
              examples:
                catalog:
                  value:
                    object: list
                    data:
                    - object: service
                      code: whatsapp.registered
                      name: WhatsApp registration
                      platform: WhatsApp
                      family: messaging
                      namespace: whatsapp
                      description: Whether the phone number has a WhatsApp account.
                      input_type: phone
                      result_kind: boolean
                      fields:
                      - registered
                      attributes: []
                      realtime: true
                      batch: true
                      modes:
                      - realtime
                      - batch
                      status: active
                      beta: false
                      countries: []
                      prices:
                        realtime:
                          amount: '0.004'
                          currency: USD
                        batch:
                          amount: '0.00025'
                          currency: USD
                      unit: per number and check; non-conclusive results are free
                    has_more: false
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
components:
  schemas:
    Service:
      type: object
      required:
      - object
      - code
      - name
      - platform
      - family
      - input_type
      - result_kind
      - realtime
      - batch
      - status
      - prices
      examples:
      - object: service
        code: number.spam
        name: Spam reputation
        platform: Spam reputation
        family: network
        namespace: number
        description: Whether the number appears in spam and nuisance-call reports.
        input_type: phone
        result_kind: attributes
        fields:
        - risk_level
        - risk_score
        attributes:
        - key: risk_level
          type: enum
          values:
          - high
          - medium
          - low
          - no_reports
          description: Overall reputation level.
        - key: risk_score
          type: integer
          min: 0
          max: 100
          description: Score 0–100 (higher = more reports).
        realtime: true
        batch: true
        modes:
        - realtime
        - batch
        status: active
        beta: false
        countries:
        - US
        - CA
        - DE
        prices:
          realtime:
            amount: '0.003'
            currency: USD
          batch:
            amount: '0.0015'
            currency: USD
        unit: per number and check; non-conclusive results are free
      properties:
        object:
          type: string
          const: service
        code:
          type: string
          examples:
          - telegram.registered
        name:
          type: string
        platform:
          type: string
          description: Descriptive platform name (no affiliation implied).
        family:
          type: string
          enum:
          - messaging
          - social
          - apps
          - network
          - email
          - finance
        namespace:
          type: string
        description:
          type: string
        input_type:
          type: string
          enum:
          - phone
          - email
        result_kind:
          type: string
          enum:
          - boolean
          - attributes
        fields:
          type: array
          items:
            type: string
        attributes:
          type: array
          items:
            type: object
            required:
            - key
            - type
            - description
            properties:
              key:
                type: string
              type:
                type: string
                enum:
                - string
                - boolean
                - enum
                - integer
              values:
                type: array
                items:
                  type: string
                description: Allowed values (type enum).
              min:
                type:
                - integer
                - 'null'
                description: Inclusive lower bound (type integer).
              max:
                type:
                - integer
                - 'null'
                description: Inclusive upper bound (type integer).
              description:
                type: string
        realtime:
          type: boolean
          description: Usable on POST /v1/lookup; otherwise bulk jobs only.
        batch:
          type: boolean
        modes:
          type: array
          items:
            type: string
            enum:
            - realtime
            - batch
        status:
          type: string
          enum:
          - active
          - unavailable
        beta:
          type: boolean
        countries:
          type: array
          items:
            type: string
          description: ISO alpha-2; empty = all countries.
        unsupported_countries:
          type: object
          description: 'Countries this check does not cover, per mode (ISO alpha-2, in addition to sanctioned countries). Numbers from them answer `unsupported_country` and are free; bulk jobs mark them before the job runs (estimate `unsupported_checks`). Example: iMessage does not cover mainland China (CN) numbers.

            '
          properties:
            realtime:
              type: array
              items:
                type: string
            batch:
              type: array
              items:
                type: string
        prices:
          type: object
          properties:
            realtime:
              oneOf:
              - $ref: '#/components/schemas/Money'
              - type: 'null'
            batch:
              $ref: '#/components/schemas/Money'
        unit:
          type: string
    Money:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Decimal USD amount.
        currency:
          type: string
          enum:
          - USD
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - status
          - retryable
          - param
          - doc_url
          - request_id
          properties:
            code:
              type: string
              description: Stable machine-readable code (full list with fixes at https://mobilevalidate.com/errors.json).
              enum:
              - invalid_request
              - too_many_numbers
              - test_number_only
              - invalid_cursor
              - unauthorized
              - insufficient_balance
              - cost_limit_exceeded
              - payment_hold
              - insufficient_scope
              - service_disabled
              - sandbox_magic_only
              - suspected_enumeration
              - not_found
              - idempotency_key_reused
              - idempotency_request_in_progress
              - test_key_exists
              - payload_too_large
              - rate_limited
              - daily_cap_reached
              - spend_cap_reached
              - internal_error
              - temporarily_unavailable
            message:
              type: string
              description: Human-readable; never repeats submitted values.
            status:
              type: integer
            retryable:
              type: boolean
            param:
              type:
              - string
              - 'null'
              description: The request field at fault, e.g. numbers[1], checks[0], email.
            suggestion:
              type: string
              maxLength: 200
              description: Optional plain-English hint on how to fix the request.
            doc_url:
              type: string
              format: uri
            request_id:
              type: string
  headers:
    X-Request-Id:
      description: Id of this request; quote it to support. Also in `error.request_id`.
      schema:
        type: string
        pattern: ^req_
  responses:
    Error:
      description: 'Error. Branch on `error.code`; `suggestion` (optional) says how to fix the request. A known path called with the wrong method answers `404 not_found` with an `Allow` header listing the methods it accepts.

        '
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        Allow:
          description: Only on `404 not_found` for a known path called with the wrong method, e.g. `POST`.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            sandbox_magic_only:
              summary: The public sandbox key only accepts test values
              value:
                error:
                  code: sandbox_magic_only
                  message: The public sandbox key only accepts the documented test numbers and e-mail addresses.
                  status: 403
                  retryable: false
                  param: numbers[0]
                  suggestion: Use a test value such as +447700900001 or registered@test.mobilevalidate.com (https://mobilevalidate.com/docs/test-values), or get your own test key at https://mobilevalidate.com/get-test-key.
                  doc_url: https://mobilevalidate.com/docs/errors#sandbox_magic_only
                  request_id: req_0VWGgv00hQwazWkblZfw
            unauthorized:
              summary: Missing key
              value:
                error:
                  code: unauthorized
                  message: Missing or invalid API key.
                  status: 401
                  retryable: false
                  param: null
                  suggestion: 'Send your API key as Authorization: Bearer mv_test_… (test) or mv_live_… (live). No key yet? The public sandbox key is on https://mobilevalidate.com/docs/test-values.'
                  doc_url: https://mobilevalidate.com/docs/errors#unauthorized
                  request_id: req_0VWGgv00hQwazWkblZfw
            not_found:
              summary: Unknown endpoint (answered before authentication)
              value:
                error:
                  code: not_found
                  message: Unknown endpoint.
                  status: 404
                  retryable: false
                  param: null
                  suggestion: Did you mean POST /v1/lookup?
                  doc_url: https://mobilevalidate.com/docs/errors#not_found
                  request_id: req_0VWGgv00hQwazWkblZfw
            not_found_method:
              summary: Known path, wrong method (GET /v1/jobs/estimate; header Allow is POST)
              value:
                error:
                  code: not_found
                  message: Method GET is not supported on this endpoint; use POST.
                  status: 404
                  retryable: false
                  param: null
                  suggestion: This endpoint accepts POST.
                  doc_url: https://mobilevalidate.com/docs/errors#not_found
                  request_id: req_0VWGgv00hQwazWkblZfw
            invalid_type:
              summary: A field with the wrong type
              value:
                error:
                  code: invalid_request
                  message: 'Invalid type for ''numbers'': expected an array of strings.'
                  status: 400
                  retryable: false
                  param: numbers
                  doc_url: https://mobilevalidate.com/docs/errors#invalid_request
                  request_id: req_0VWGgv00hQwazWkblZfw
            invalid_request:
              summary: Unknown check code
              value:
                error:
                  code: invalid_request
                  message: Unknown check. See GET /v1/services for valid codes.
                  status: 400
                  retryable: false
                  param: checks[0]
                  suggestion: Did you mean 'whatsapp'? GET /v1/services lists every check code.
                  doc_url: https://mobilevalidate.com/docs/errors#invalid_request
                  request_id: req_0VWGgv00hQwazWkblZfw
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <key>`. Keys start with `mv_live_` (billed), `mv_test_` (test mode: documented sample

        answers, never billed) or `mv_agent_` (AI agents, with a daily spend cap). Keep the key in the

        `MOBILEVALIDATE_API_KEY` environment variable.


        Public sandbox key (safe to publish; test values only, limited per IP address):

        `mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym`

        '
      x-example: mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym
externalDocs:
  description: Guides, test values and error reference
  url: https://mobilevalidate.com/docs
x-refined-from:
- mobilevalidate-com-openapi.yaml
- openapi.yaml