mobilevalidate-com Webhooks API

openapi: 3.2.0
info:
  title: Mobilevalidate Com Webhooks API
  version: 1.0.0
  contact:
    name: MobileValidate
    url: https://mobilevalidate.com/contact
  termsOfService: https://mobilevalidate.com/legal/terms
  description: 'Operations tagged webhooks 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: Webhooks
  description: Signed notifications (Standard Webhooks) when lookups and jobs finish. See the `webhooks` section for the event payloads and https://mobilevalidate.com/docs/webhooks for signature verification.
paths:
  /webhook_endpoints:
    get:
      tags:
      - Webhooks
      operationId: listWebhookEndpoints
      summary: List webhook endpoints
      description: Every endpoint of the account that is not deleted and has the same mode as the key (test keys list test endpoints, live keys live endpoints). Needs `webhooks:manage`.
      responses:
        '200':
          description: Endpoints.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                - has_more
                properties:
                  object:
                    type: string
                    const: list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
                  has_more:
                    type: boolean
              examples:
                list:
                  value:
                    object: list
                    data:
                    - object: webhook_endpoint
                      id: we_0VWGguzNt6zD31ghz2pa
                      url: https://example.com/hooks/mobilevalidate
                      events:
                      - lookup.completed
                      - job.completed
                      status: active
                      livemode: false
                      created_at: '2026-09-25T14:30:00.000Z'
                    has_more: false
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
      - Webhooks
      operationId: createWebhookEndpoint
      summary: Create a webhook endpoint
      description: Registers a public HTTPS URL (at most 20 per account). The response contains the signing `secret` — shown only once. The endpoint stays `pending_verification` until it answers our signed `webhook.verification` event with a 2xx status. Not available with the public sandbox key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - events
              additionalProperties: false
              properties:
                url:
                  type: string
                  format: uri
                  pattern: ^https://
                  maxLength: 2048
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/WebhookEvent'
                  minItems: 1
            examples:
              endpoint:
                value:
                  url: https://example.com/hooks/mobilevalidate
                  events:
                  - lookup.completed
                  - job.completed
      responses:
        '201':
          description: Endpoint created; `secret` is shown only this once.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WebhookEndpoint'
                - type: object
                  required:
                  - secret
                  properties:
                    secret:
                      type: string
                      pattern: ^whsec_
                      description: 'Signing secret: the base64 part after whsec_ is the HMAC key.'
              examples:
                created:
                  value:
                    object: webhook_endpoint
                    id: we_0VWGguzNt6zD31ghz2pa
                    url: https://example.com/hooks/mobilevalidate
                    events:
                    - lookup.completed
                    - job.completed
                    status: pending_verification
                    livemode: false
                    created_at: '2026-09-25T14:30:00.000Z'
                    secret: whsec_…
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
  /webhook_endpoints/{id}:
    patch:
      tags:
      - Webhooks
      operationId: updateWebhookEndpoint
      summary: Update a webhook endpoint
      description: Changes the URL and/or the subscribed events. A new URL must be verified again (`pending_verification`).
      parameters:
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                url:
                  type: string
                  format: uri
                  pattern: ^https://
                  maxLength: 2048
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/WebhookEvent'
                  minItems: 1
            examples:
              events:
                value:
                  events:
                  - job.completed
      responses:
        '200':
          description: The updated endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
              examples:
                updated:
                  value:
                    object: webhook_endpoint
                    id: we_0VWGguzNt6zD31ghz2pa
                    url: https://example.com/hooks/mobilevalidate
                    events:
                    - job.completed
                    status: active
                    livemode: false
                    created_at: '2026-09-25T14:30:00.000Z'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
      - Webhooks
      operationId: deleteWebhookEndpoint
      summary: Delete a webhook endpoint
      description: Nothing is delivered to a deleted endpoint.
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: Deleted.
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
  /webhook_endpoints/{id}/test:
    post:
      tags:
      - Webhooks
      operationId: testWebhookEndpoint
      summary: Send a test event
      description: Queues a signed `webhook.test` event to the endpoint (delivered even before verification). Use it to check your signature code.
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '202':
          description: Test event queued.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - id
                - endpoint_id
                - status
                properties:
                  object:
                    type: string
                    const: webhook_test
                  id:
                    type: string
                    description: Event id (the webhook-id header).
                  endpoint_id:
                    type: string
                  status:
                    type: string
                    const: queued
              examples:
                queued:
                  value:
                    object: webhook_test
                    id: evt_a5188025bd4f1316da68efd2
                    endpoint_id: we_0VWGguzNt6zD31ghz2pa
                    status: queued
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.mobilevalidate.com/v1
      description: Production (live and test keys)
components:
  schemas:
    WebhookEndpoint:
      type: object
      required:
      - object
      - id
      - url
      - events
      - status
      - created_at
      properties:
        object:
          type: string
          const: webhook_endpoint
        id:
          type: string
          pattern: ^we_
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEvent'
        status:
          type: string
          enum:
          - pending_verification
          - active
          - disabled
        livemode:
          type: boolean
          description: 'Mode of the key that created the endpoint. Test keys see and manage only test endpoints, live keys only live endpoints; test-mode events are delivered only to test endpoints and live events only to live endpoints.

            '
        created_at:
          type: string
          format: date-time
    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
    WebhookEvent:
      type: string
      enum:
      - lookup.completed
      - job.completed
      - job.failed
      - job.progress
      - balance.low
      - limits.cap_reached
  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
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: Object id (`lkp_…`, `job_…` or `we_…`).
      schema:
        type: string
        pattern: ^(lkp|job|we)_[0-9A-Za-z]+$
  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