mobilevalidate-com Webhooks API
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.
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.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/mobilevalidate-com:mobilevalidate-com-webhooks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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