mobilevalidate-com Keys API

openapi: 3.2.0
info:
  title: Mobilevalidate Com Keys API
  version: 1.0.0
  contact:
    name: MobileValidate
    url: https://mobilevalidate.com/contact
  termsOfService: https://mobilevalidate.com/legal/terms
  description: 'Operations tagged keys 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: Keys
  description: Instant personal test keys for developers (no account needed).
paths:
  /test-keys:
    post:
      tags:
      - Keys
      operationId: createTestKey
      summary: Get a personal test key
      description: Issues a personal test key (`mv_test_…`) for a work e-mail address, protected by a Cloudflare Turnstile token from the form at https://mobilevalidate.com/get-test-key. The key works in test mode with any number (never billed, never reaches a data source), including bulk jobs and test-mode webhooks. It is shown **once** and never returned again. Each address can receive at most 3 test keys in 30 days; after that the answer is 409 test_key_exists. At most 3 requests per network per day, whatever their result (IPv6 networks count per /64). The request also asks for live access, which we review by hand. No authentication.
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - company
              - country
              - accept_terms
              - turnstile_token
              additionalProperties: false
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 254
                  description: Work e-mail address (must receive mail).
                name:
                  type: string
                  maxLength: 120
                company:
                  type: string
                  minLength: 2
                  maxLength: 160
                  description: Company name.
                country:
                  type: string
                  pattern: ^[A-Za-z]{2}$
                  description: ISO 3166-1 alpha-2 country of the company.
                accept_terms:
                  type: boolean
                  const: true
                  description: The company accepts the Terms of Service, the Acceptable Use Policy and the Data Processing Agreement (https://mobilevalidate.com/legal/terms, /legal/acceptable-use, /legal/dpa) and is responsible for the lawful use of the service and its results. Recorded with the document versions.
                use_case:
                  type: string
                  maxLength: 2000
                turnstile_token:
                  type: string
                  maxLength: 4096
                  description: Token from the Turnstile widget on mobilevalidate.com.
                session_id:
                  type: string
                  maxLength: 100
                  description: Optional. Set by the form on mobilevalidate.com to link the key to the page visit that led to it (first-party, per browser tab, no cookie; not sent when the browser signals Do-Not-Track or Global Privacy Control). Unknown or malformed values are ignored.
            examples:
              request:
                value:
                  email: dev@example.com
                  name: Ada
                  company: Example Ltd
                  country: GB
                  accept_terms: true
                  use_case: Screen sign-up phone numbers
                  turnstile_token: 0.x…
      responses:
        '201':
          description: The key (shown only once).
          content:
            application/json:
              schema:
                type: object
                required:
                - key
                - key_prefix
                - docs_url
                - request_id
                properties:
                  key:
                    type: string
                    pattern: ^mv_test_
                  key_prefix:
                    type: string
                    description: First characters of the key, for display.
                  docs_url:
                    type: string
                    format: uri
                  request_id:
                    type: string
              examples:
                issued:
                  value:
                    key: mv_test_…
                    key_prefix: mv_test_Ab3x
                    docs_url: https://mobilevalidate.com/docs/quickstart
                    request_id: req_0VWGgv00hQwazWkblZfw
        '409':
          description: No more test keys can be issued for this e-mail address right now (at most 3 in 30 days). Keys already issued are never shown again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                exists:
                  value:
                    error:
                      code: test_key_exists
                      message: No more test keys can be issued for this e-mail address right now. Keys are shown only once.
                      status: 409
                      retryable: false
                      param: email
                      suggestion: Use a key you received earlier, or request access at https://mobilevalidate.com/request-access.
                      doc_url: https://mobilevalidate.com/docs/errors#test_key_exists
                      request_id: req_0VWGgv00hQwazWkblZfw
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
components:
  schemas:
    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