mobilevalidate-com Account API

openapi: 3.2.0
info:
  title: Mobilevalidate Com Account API
  version: 1.0.0
  contact:
    name: MobileValidate
    url: https://mobilevalidate.com/contact
  termsOfService: https://mobilevalidate.com/legal/terms
  description: 'Operations tagged account 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: Account
  description: Balance, limits and usage of the key's account.
paths:
  /account:
    get:
      tags:
      - Account
      operationId: getAccount
      summary: Get the account balance
      description: Balance, reserved amount and today's usage (UTC) of the key's account. Needs `account:read`.
      responses:
        '200':
          description: The account.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - org_id
                - balance
                - reserved
                properties:
                  object:
                    type: string
                    const: account
                  org_id:
                    type: string
                  name:
                    type: string
                  livemode:
                    type: boolean
                  balance:
                    $ref: '#/components/schemas/Money'
                  reserved:
                    $ref: '#/components/schemas/Money'
                  today:
                    type: object
                    properties:
                      numbers:
                        type: integer
                        description: Live identifiers checked today.
                      billed_units:
                        type: integer
                      cost:
                        $ref: '#/components/schemas/Money'
                      resets_at:
                        type: string
                        format: date-time
              examples:
                account:
                  value:
                    object: account
                    org_id: org_sandbox
                    name: Public sandbox
                    livemode: false
                    balance:
                      amount: '0'
                      currency: USD
                    reserved:
                      amount: '0'
                      currency: USD
                    today:
                      numbers: 0
                      billed_units: 0
                      cost:
                        amount: '0'
                        currency: USD
                      resets_at: '2026-09-26T00:00:00.000Z'
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
  /limits:
    get:
      tags:
      - Account
      operationId: getLimits
      summary: Get limits and remaining allowances
      description: 'Request rate, request sizes, the daily identifiers cap and the key''s daily spend cap. Daily counters reset at 00:00 UTC. The public sandbox key is limited per client IP address instead: it answers `sandbox: true`, `rate_limit` with `per: "ip"`, `requests_per_minute` and `requests_per_day` (no `requests_per_second`/`burst`), `jobs.max_numbers` 10 and no `daily_numbers`.'
      responses:
        '200':
          description: Current limits.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                properties:
                  object:
                    type: string
                    const: limits
                  sandbox:
                    type: boolean
                    description: Present (true) only for the public sandbox key.
                  rate_limit:
                    type: object
                    properties:
                      requests_per_second:
                        type: integer
                        description: Per-key token bucket rate (not for the sandbox key).
                      burst:
                        type: integer
                        description: Per-key token bucket size (not for the sandbox key).
                      per:
                        type: string
                        enum:
                        - key
                        - ip
                        description: 'What the limit applies to: the API key, or (sandbox key) the client IP address.'
                      requests_per_minute:
                        type: integer
                        description: Sandbox key only
                        per client IP.: null
                      requests_per_day:
                        type: integer
                        description: Sandbox key only, per client IP and UTC day.
                  lookup:
                    type: object
                    properties:
                      max_numbers:
                        type: integer
                      max_wait_seconds:
                        type: integer
                      realtime_enabled:
                        type: boolean
                  jobs:
                    type: object
                    properties:
                      max_numbers:
                        type: integer
                  daily_numbers:
                    type: object
                    properties:
                      cap:
                        type: integer
                      used:
                        type: integer
                      remaining:
                        type: integer
                  key_daily_spend:
                    type:
                    - object
                    - 'null'
                    properties:
                      cap:
                        $ref: '#/components/schemas/Money'
                      used:
                        $ref: '#/components/schemas/Money'
                      remaining:
                        $ref: '#/components/schemas/Money'
                  resets_at:
                    type: string
                    format: date-time
              examples:
                limits:
                  summary: A personal key
                  value:
                    object: limits
                    rate_limit:
                      requests_per_second: 10
                      burst: 20
                      per: key
                    lookup:
                      max_numbers: 100
                      max_wait_seconds: 30
                      realtime_enabled: true
                    jobs:
                      max_numbers: 50000
                    daily_numbers:
                      cap: 10000
                      used: 0
                      remaining: 10000
                    key_daily_spend: null
                    resets_at: '2026-09-26T00:00:00.000Z'
                sandbox:
                  summary: The public sandbox key (per-IP limits)
                  value:
                    object: limits
                    sandbox: true
                    rate_limit:
                      per: ip
                      requests_per_minute: 30
                      requests_per_day: 1000
                    lookup:
                      max_numbers: 100
                      max_wait_seconds: 30
                      realtime_enabled: true
                    jobs:
                      max_numbers: 10
                    key_daily_spend: null
                    resets_at: '2026-10-19T00:00:00.000Z'
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
  /usage:
    get:
      tags:
      - Account
      operationId: getUsage
      summary: Get usage by day or by check
      description: Checks, conclusive answers, cached answers, billed units and cost for an inclusive UTC date range (at most 366 days), for the key's mode (live or test). Rows past the retention period are no longer counted.
      parameters:
      - name: from
        in: query
        required: true
        description: First day (UTC).
        schema:
          type: string
          format: date
        example: '2026-09-01'
      - name: to
        in: query
        required: true
        description: Last day (UTC), inclusive.
        schema:
          type: string
          format: date
        example: '2026-09-30'
      - name: group_by
        in: query
        description: One row per day or per check.
        schema:
          type: string
          enum:
          - day
          - service
          default: day
      responses:
        '200':
          description: Usage rows.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                - total_cost
                properties:
                  object:
                    type: string
                    const: usage
                  from:
                    type: string
                    format: date
                  to:
                    type: string
                    format: date
                  group_by:
                    type: string
                    enum:
                    - day
                    - service
                  livemode:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        service:
                          type: string
                        checks:
                          type: integer
                        conclusive:
                          type: integer
                        cached:
                          type: integer
                        billed_units:
                          type: integer
                        cost:
                          $ref: '#/components/schemas/Money'
                  total_cost:
                    $ref: '#/components/schemas/Money'
              examples:
                by_service:
                  value:
                    object: usage
                    from: '2026-09-01'
                    to: '2026-09-30'
                    group_by: service
                    livemode: false
                    data:
                    - service: whatsapp.registered
                      checks: 4
                      conclusive: 3
                      cached: 0
                      billed_units: 0
                      cost:
                        amount: '0'
                        currency: USD
                    total_cost:
                      amount: '0'
                      currency: USD
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
components:
  schemas:
    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