Verifications

Create a verification

Rents a phone number for one inbound SMS. Idempotent by Idempotency-Key.

Caps

SMS pricing drifts. Set max_price_cents to opt into "always get a number" behaviour: any drift up to your cap charges silently and the actual amount appears as charged_price_cents on the response. Omit max_price_cents to lock in exactly the price you saw on GET /v1/services.

Price over cap

If the lowest available price is above your max_price_cents, the API returns 409 PRICE_OVER_CAP with both values in the error details:

{
  "success": false,
  "error": {
    "code": "PRICE_OVER_CAP",
    "details": {
      "max_price_cents": 35,
      "available_price_cents": 42
    }
  }
}

No partial state is created and no funds are touched. Decide locally whether to retry with a higher cap or surface the price to the user.

post/verifications

Request

  • Base URL: https://dashboard.voidmob.com/api/v1
  • URL: https://dashboard.voidmob.com/api/v1/verifications
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required
Example:7c4f08c2-2a4f-4c8e-a1d2-9c2b9c8f7e10

Client-supplied key (any string, up to 255 chars) that scopes idempotent replay for write requests. Required on every POST, PATCH, and DELETE. Replays with the same key + same body return the cached response; same key with a different body returns IDEMPOTENCY_CONFLICT. Headers are case-insensitive; both Idempotency-Key and idempotency-key work.

Request body

service_idstring required

Opaque public service identifier.

countrystring
max_price_centsinteger

Optional ceiling. If omitted, the API caps at the current quoted_price_cents reported by GET /v1/services. Setting this above the quote opts into "always get a number" mode - price drift within the cap charges the new market price; drift above the cap returns 409 PRICE_OVER_CAP with the current available price in the error details so callers can decide whether to retry with a higher cap.

webhook_endpoint_idstring

Webhook endpoint identifier.

Example request

{
  "service_id": "svc_telegram",
  "webhook_endpoint_id": "whep_01HXYZ123ABC"
}

Response

Verification created. status is always waiting_for_code at this point.

successtrue required

Example response

{
  "data": {
    "verification": {
      "id": "ver_01HXYZ123ABC",
      "display_id": "SMS7K4P2N",
      "phone_number": "+15551234567",
      "service_id": "svc_telegram",
      "service_name": "Telegram",
      "code": "123456",
      "paid_reuse_price_cents": 50
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.