LookupRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mobilevalidate-com/json-schema/mobilevalidate-com-lookup-request-schema.json",
  "title": "LookupRequest",
  "description": "At least one of numbers / emails; together ≤ 100 identifiers (too_many_numbers above). Identifiers × applicable checks ≤ 2,000 (400 invalid_request, param checks).\n",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mobilevalidate-com-openapi.yaml#/components/schemas/LookupRequest",
  "type": "object",
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "numbers"
      ]
    },
    {
      "required": [
        "emails"
      ]
    }
  ],
  "properties": {
    "numbers": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 32
      },
      "description": "Phone numbers for phone checks, ideally in international format (E.164, e.g. +447700900001). National numbers need `default_country`. 20 or more consecutive numbers → 403 suspected_enumeration.\n"
    },
    "emails": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 254
      },
      "description": "E-mail addresses for e-mail checks. Normalized by trim + lowercase (no dot/plus rewriting); internationalised domains in punycode. ≥ 20 addresses on one domain whose local parts differ only by digits and/or separators (any run of non-letters is one class; googlemail.com = gmail.com), or (live keys) ≥ 50 such addresses of one pattern per account per UTC day → 403 suspected_enumeration.\n"
    },
    "checks": {
      "$ref": "#/$defs/Checks"
    },
    "default_country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$",
      "description": "ISO country for numbers without a country code."
    },
    "max_age": {
      "type": "integer",
      "minimum": 0,
      "description": "Accept a cached answer up to this many seconds old (capped per check); 0 forces a fresh, billed check."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 30,
      "default": 10,
      "description": "Seconds to wait for all answers before returning 202 pending."
    },
    "max_cost": {
      "$ref": "#/$defs/Money",
      "description": "Refuse the request (402 cost_limit_exceeded) if its maximum cost is higher."
    },
    "webhook_endpoint_id": {
      "type": "string",
      "pattern": "^we_",
      "description": "Endpoint to notify with lookup.completed if the lookup answers pending."
    },
    "metadata": {
      "type": "object",
      "maxProperties": 20,
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      },
      "description": "Your own key/value pairs, echoed back."
    }
  },
  "$defs": {
    "Checks": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "type": "string",
        "maxLength": 64
      },
      "default": [
        "whatsapp"
      ],
      "description": "Service codes or aliases (e.g. whatsapp, telegram, viber, carrier, spam; e-mail: email, gmail, outlook, yahoo; full list: GET /v1/services). Order is kept; duplicates are ignored; whatsapp.registered + whatsapp.business collapse to whatsapp.business. Phone checks apply to numbers, e-mail checks (input_type email) to emails: sending e-mails without an e-mail check (or numbers without a phone check) → 400 invalid_request, param checks; a check whose input type has no identifiers → 400 invalid_request, param checks[i]. At most 20 checks (400 invalid_request, param checks).\n"
    },
    "Money": {
      "type": "object",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "string",
          "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
          "description": "Decimal USD amount."
        },
        "currency": {
          "type": "string",
          "enum": [
            "USD"
          ]
        }
      }
    }
  }
}