GlobeVerify API Documentation

Explore the complete REST API reference for virtual number purchases, SMS verification, rentals, wallet balances, webhooks, and white-label services. All endpoints use the base URL https://api.globeverify.com and authenticate with your developer API key.

Services Catalog

The Catalog API provides resources for querying available countries, services, precise pricing, and current stock levels for virtual numbers. Base URL: https://api.globeverify.com

Get Countries

Fetch all countries currently supported by the provider. Each entry includes an integer ID (use this for other API calls), the full country name, a short_name ISO code, the international calling code (cc), and a region label for grouping. Available regions: Favourites, Europe, Asia, Africa, North America, South America, Central America, Carribeans, Oceania, Virtuals.

GEThttps://api.globeverify.com/v1/countries

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

[
  {
    "ID": 1,
    "name": "United States",
    "short_name": "US",
    "cc": "1",
    "region": "Favourites"
  },
  {
    "ID": 14,
    "name": "Nigeria",
    "short_name": "NG",
    "cc": "234",
    "region": "Africa"
  },
  {
    "ID": 9,
    "name": "Indonesia",
    "short_name": "ID",
    "cc": "62",
    "region": "Asia"
  }
]

Get Available Services

Fetch all services available on the platform (e.g., WhatsApp, Telegram, Google, Discord). Results are sorted with favourites (favourite: 1) at the top, followed by alphabetical listings. Use the integer ID when purchasing a number.

GEThttps://api.globeverify.com/v1/services

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Query Parameters

Parameter	Description
country string	Optional country ID or short_name to filter services by availability.

Responses

Response200 OK

[
  {
    "ID": 273,
    "name": "Discord",
    "favourite": 1,
    "successRate": null
  },
  {
    "ID": 1012,
    "name": "WhatsApp",
    "favourite": 1,
    "successRate": null
  },
  {
    "ID": 907,
    "name": "Telegram",
    "favourite": 1,
    "successRate": null
  },
  {
    "ID": 395,
    "name": "Google/Gmail",
    "favourite": 1,
    "successRate": null
  }
]

Get Stock Levels

Fetch current inventory stock levels for a specific service in a specific country.

GEThttps://api.globeverify.com/v1/stock

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Query Parameters

Parameter	Description
countryRequired string	Target country ID or short_name.
serviceRequired string	Target service ID.

Responses

Response200 OK

{
  "amount": 17312,
  "success": true
}

Get Area Codes

Fetch available area codes for the specified service and country. Returns a flat array of integer area codes. Used mainly for North American numbers.

GEThttps://api.globeverify.com/v1/areacodes

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Query Parameters

Parameter	Description
countryRequired string	Target country ID or short_name.
serviceRequired string	Target service ID.
pool string	Optional provider pool.

Responses

Response200 OK

Get Instant Price

Calculate the exact billing cost for purchasing a service, accounting for the developer's specific discounts and multi-currency exchange rates.

GEThttps://api.globeverify.com/v1/price

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Query Parameters

Parameter	Description
country string	Target country ID or short_name.
service string	Target service ID.
currency string	Optional desired output currency (e.g. NGN, USD).
pricing_option integer	0 for Economy, 1 for High Success Rate.
pool string	Optional explicit pool alias to lock pricing.
max_price number	Optional maximum price budget. If the pool exceeds this, returns NO_POOL.

Responses

Response200 OK

{
  "success": true,
  "price": 80.1,
  "currency": "NGN",
  "formatted": "₦80.1",
  "supportsPoolSelection": true,
  "pricingOption": 1,
  "successRate": 98,
  "poolAlias": "Nova"
}

Get Available Pools

Fetch all available underlying provider pools for a specific service and country. Includes their unique aliases, pricing, and success rates.

GEThttps://api.globeverify.com/v1/pools

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Query Parameters

Parameter	Description
countryRequired string	Target country ID or short_name.
serviceRequired string	Target service ID.

Responses

Response200 OK

{
  "supportsPoolSelection": true,
  "pools": [
    {
      "alias": "Nova",
      "price": 0.24,
      "high_price": 0.24,
      "success_rate": 98
    }
  ]
}

Virtual Numbers (OTP)

Provides core mechanics for creating and managing one-time virtual numbers for SMS verifications. Automatically deducts funds from your internal wallet balances. Base URL: https://api.globeverify.com/v1/numbers

Purchase a One-Time Number

Provision a number for a targeted service. Purchases are immediately debited from your wallet.

POSThttps://api.globeverify.com/v1/numbers/purchase

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "country": "US",
  "service": 273,
  "serviceName": "Discord",
  "pricing_option": 1,
  "pool": "Nova",
  "max_price": 500
}

Responses

Number Purchased Successfully200 OK

{
  "success": true,
  "message": "Number purchased successfully",
  "data": {
    "_id": "6a1ac6d8511382ccc15007d6",
    "phoneNumber": "+1 5033051381",
    "countryCode": "US",
    "countryName": "United States",
    "service": "273",
    "serviceName": "Discord",
    "status": "active",
    "cost": 80.1,
    "currency": "NGN",
    "type": "sms",
    "autoRenew": false,
    "orderSource": "api",
    "isReactivated": false,
    "freeResendAt": null,
    "freeResendCount": 0,
    "expiresAt": "2026-05-30T11:35:36.000Z",
    "otps": [],
    "purchasedAt": "2026-05-30T11:15:36.469Z"
  }
}

Queued (Returned if internal stock is low)202 Accepted

{
  "success": true,
  "pending": true,
  "message": "Order queued due to high demand. You will receive an email when your number is ready.",
  "orderId": "queue_817...",
  "estimatedWait": "5-25 minutes"
}

Check Inbox (OTP)

Poll this endpoint repeatedly to read incoming SMS OTPs for a specific active number. The numberId is the _id field returned from the purchase endpoint.

GEThttps://api.globeverify.com/v1/numbers/:numberId/otp

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

No Message Yet200 OK

{
  "success": true,
  "data": {
    "otps": [],
    "status": "active"
  }
}

OTP Received200 OK

{
  "success": true,
  "data": {
    "otps": [
      {
        "code": "849201",
        "message": "Your Discord verification code is: 849201",
        "sender": "Discord",
        "receivedAt": "2026-05-30T11:20:00.000Z"
      }
    ],
    "status": "completed"
  }
}

Cancel & Refund Number

Cancel an active number. If cancelled before OTP extraction, funds are refunded to your wallet. The full updated order object is returned.

POSThttps://api.globeverify.com/v1/numbers/:numberId/cancel

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

{
  "success": true,
  "message": "Number cancelled and refunded.",
  "data": {
    "_id": "6a1ac6d8511382ccc15007d6",
    "phoneNumber": "+1 5033051381",
    "countryCode": "US",
    "countryName": "United States",
    "service": "273",
    "serviceName": "Discord",
    "status": "cancelled",
    "cost": 80.1,
    "currency": "NGN",
    "type": "sms",
    "autoRenew": false,
    "orderSource": "api",
    "isReactivated": false,
    "freeResendAt": null,
    "freeResendCount": 0,
    "expiresAt": "2026-05-30T11:35:36.000Z",
    "otps": [],
    "purchasedAt": "2026-05-30T11:15:36.469Z"
  }
}

Retrieve Reuse Capability

Determine if a number can be reused (resent for free or reactivated for a fee).

GEThttps://api.globeverify.com/v1/numbers/:numberId/reuse

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

{
  "success": true,
  "data": {
    "success": true,
    "canResendForFree": true,
    "message": "This phone number is available for resend!",
    "resendCost": 0
  }
}

Execute Number Reuse

Initiate a reactivation (paid) or resend trigger (free).

POSThttps://api.globeverify.com/v1/numbers/:numberId/reuse

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "payToReactivate": true
}

Responses

Response200 OK

{
  "success": true,
  "message": "Number reactivated successfully"
}

Developer Rental API

Manage long-term virtual numbers, read incoming SMS, and send outbound SMS. Important: Access to these endpoints requires explicit administrative approval. If you receive an unauthorized error, please contact support to activate your Rental API status. Base URL: https://api.globeverify.com

Get Rental Options

Fetch a live list of available phone numbers for rent, including pricing and supported durations.

GEThttps://api.globeverify.com/v1/rentals/options

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Query Parameters

Parameter	Description
countryCode string	The 2-letter ISO country code (e.g. US, GB, CA). Defaults to US.
areaCode string	Optional 3-digit area code to filter numbers (e.g. 212).
currency string	Optional desired output currency (e.g. NGN, USD).

Responses

Response200 OK

[
  {
    "phoneNumber": "+19482417375",
    "region": "US",
    "pricing": {
      "30": 8.5
    },
    "type": 1,
    "currency": "USD"
  },
  {
    "phoneNumber": "+19482417376",
    "region": "US",
    "pricing": {
      "30": 8.5
    },
    "type": 1,
    "currency": "USD"
  }
]

Buy Rental Number

Purchase one of the available rental numbers returned from the Options endpoint. Pass the phoneNumber string into the rentalId field.

POSThttps://api.globeverify.com/v1/rentals/buy

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "rentalId": "+19482417375",
  "days": 30,
  "serviceId": "global",
  "country": "US"
}

Responses

Response200 OK

{
  "success": true,
  "data": {
    "id": "6a3c51705d305ae92f84a129",
    "phoneNumber": "+19482417375",
    "countryCode": "US",
    "countryName": "United States",
    "service": "global",
    "serviceName": "Number Rental",
    "status": "active",
    "cost": 8.5,
    "currency": "USD",
    "purchasedAt": "2026-06-25T14:15:00.000Z",
    "expiresAt": "2026-07-25T14:15:00.000Z"
  }
}

Insufficient funds or unavailable number400 Bad Request

{
  "success": false,
  "message": "Insufficient balance"
}

Extend Rental Duration

Extend the expiration date of an active rental by 30 days. Uses the GlobeVerify rental ID (_id) of the number.

POSThttps://api.globeverify.com/v1/rentals/extend

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "rentalId": "6a3c51705d305ae92f84a129",
  "days": 30
}

Responses

Response200 OK

{
  "success": true,
  "message": "Rental extended by 30 days",
  "data": {
    "rentalId": "6a3c51705d305ae92f84a129",
    "expiresAt": "2026-08-25T14:15:00.000Z"
  }
}

List Active Rentals

Retrieve a list of all your currently active rental numbers.

GEThttps://api.globeverify.com/v1/rentals

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

{
  "success": true,
  "rentals": [
    {
      "id": "6a3c51705d305ae92f84a129",
      "phoneNumber": "+19482417375",
      "status": "active",
      "country": "US",
      "purchasedAt": "2026-06-25T14:15:00.000Z",
      "expiresAt": "2026-07-25T14:15:00.000Z"
    }
  ]
}

Get Rental Messages

Fetch the SMS and voicemail history for a specific rental number using its GlobeVerify rental ID.

GEThttps://api.globeverify.com/v1/rentals/:rentalId/messages

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

{
  "success": true,
  "messages": [
    {
      "id": "7b4d62816e416bf83f95b230",
      "direction": "inbound",
      "from": "+15551234567",
      "to": "+19482417375",
      "body": "Your verification code is 123456",
      "status": "received",
      "createdAt": "2026-06-25T10:15:00.000Z"
    }
  ]
}

Send Outbound SMS

Send an outbound SMS from your rental number. The cost per SMS is deducted natively from your active balance.

POSThttps://api.globeverify.com/v1/rentals/:rentalId/sms

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "to": "+15551234567",
  "text": "Hello from Globeverify!"
}

Responses

Response200 OK

{
  "success": true,
  "message": {
    "direction": "outbound",
    "rentalPhoneNumber": "+19482417375",
    "remotePhoneNumber": "+15551234567",
    "text": "Hello from Globeverify!",
    "status": "sent",
    "costUSD": 0.05,
    "timestamp": "2026-06-25T12:00:00.000Z"
  }
}

Insufficient funds or bad number400 Bad Request

{
  "success": false,
  "message": "Insufficient telecom credits"
}

Wallet API

Exposes your internal GlobeVerify account balance to integrate balance checks before dispatching orders. Base URL: https://api.globeverify.com/v1

Get Wallet Balance

Fetch your current active wallet balance bounded by your active session currency.

GEThttps://api.globeverify.com/v1/balance

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

{
  "success": true,
  "data": {
    "balance": 2626.65,
    "currency": "NGN",
    "balances": {
      "usd": 0,
      "ngn": 2626.65
    }
  }
}

Webhooks (Outbound Events)

Receive real-time HTTP POST callbacks on your server when an OTP is delivered, avoiding the need to continuously poll the Check Inbox endpoint. Configure your Webhook URL and Secret from the Developer Dashboard.

OTP Received Event (Payload Format)

This is the payload GlobeVerify sends to your server. Authenticate the source by calculating an HMAC SHA256 of the raw body using your Webhook Secret and comparing it against the X-GlobeVerify-Signature header.

POSThttps://api.globeverify.com<Your Webhook URL>

Headers

Parameter	Description
X-GlobeVerify-Signature string	HMAC SHA256 signature of the payload
Content-Type string	application/json

Responses

ResponseExample Payload

{
  "event": "otp.received",
  "timestamp": "2026-05-30T08:00:00.000Z",
  "data": {
    "orderId": "6a1ac6d8511382ccc15007d6",
    "phoneNumber": "+1 5033051381",
    "service": "273",
    "otp": {
      "code": "849201",
      "message": "Your Discord verification code is: 849201",
      "sender": "Discord"
    }
  }
}

Pending Order Allocated Event

Fired instantly when a background job successfully resolves your queued "pending" order into an active number.

POSThttps://api.globeverify.com<Your Webhook URL>

Headers

Parameter	Description
X-GlobeVerify-Signature string	HMAC SHA256 signature of the payload
Content-Type string	application/json

Responses

ResponseExample Payload

{
  "event": "order.allocated",
  "timestamp": "2026-05-30T08:00:00.000Z",
  "data": {
    "orderId": "6a1ac6d8511382ccc15007d6",
    "phoneNumber": "+1 5033051381",
    "service": "273",
    "cost": 80.1,
    "currency": "NGN"
  }
}

White-Label Provisioning

Automate the creation of white-label reseller sites directly via the API. Note: For Pro and Enterprise users, if your balance is insufficient, you can purchase sites on loan up to a limit of -$200.00 (or -₦300,000).

Get Plans

Fetch available whitelabel plans and prices, applying your custom user discounts. Plans include mini, pro, and max tiers with both USD and NGN pricing.

GEThttps://api.globeverify.com/v1/whitelabel/plans

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

{
  "success": true,
  "data": [
    {
      "_id": "69ab4c8de83636f9c8e086b7",
      "tier": "mini",
      "name": "Mini Plan",
      "priceUSD": 5,
      "priceNGN": 7500,
      "currency": "NGN",
      "isActive": true,
      "features": []
    },
    {
      "_id": "69ab4c8de83636f9c8e086b8",
      "tier": "pro",
      "name": "Pro Plan",
      "priceUSD": 38,
      "priceNGN": 57000,
      "currency": "NGN",
      "isActive": true,
      "features": []
    },
    {
      "_id": "69ab4c8ee83636f9c8e086b9",
      "tier": "max",
      "name": "Max Plan",
      "priceUSD": 128.99,
      "priceNGN": 193485,
      "currency": "NGN",
      "isActive": true,
      "features": []
    }
  ],
  "domainMarkup": 7500,
  "currency": "NGN"
}

Check Domain Availability & Price

Check if a custom domain is available for registration and get its full cost breakdown including base price, markup, and totals in both USD and NGN.

GEThttps://api.globeverify.com/v1/whitelabel/check-domain

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Query Parameters

Parameter	Description
domainRequired string	Domain to check (e.g., example.com)

Responses

Response200 OK

{
  "success": true,
  "available": true,
  "basePriceUSD": 12,
  "basePriceNGN": 18000,
  "markupUSD": 5,
  "markupNGN": 7500,
  "totalPriceUSD": 17,
  "totalPriceNGN": 25500,
  "currency": "NGN"
}

Purchase a White-Label Site

Provision a new white-label site. Pro/Enterprise users can purchase on loan up to a maximum debt of -$200.00 or -₦300,000.

POSThttps://api.globeverify.com/v1/whitelabel/purchase

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "tier": "pro",
  "domain": "my-cool-site.com",
  "isSubdomain": false,
  "siteName": "My Site",
  "ownerEmail": "admin@my-cool-site.com",
  "ownerPassword": "secure123",
  "ownerFirstName": "John",
  "ownerLastName": "Doe"
}

Responses

Response201 Created

{
  "success": true,
  "message": "White-label site ordered.",
  "data": {
    "domain": "my-cool-site.com",
    "createdOnLoan": true
  }
}

List My Sites

Fetch all white-label sites provisioned by your account.

GEThttps://api.globeverify.com/v1/whitelabel/sites

Headers

Parameter	Description
x-api-key string	Your Developer API Key

Responses

Response200 OK

{
  "success": true,
  "data": [
    {
      "_id": "69d606c380db0a5972360435",
      "siteName": "My Site",
      "domain": "mysite.getsms.site",
      "isSubdomain": true,
      "domainStatus": "active",
      "tier": "mini",
      "status": "active",
      "ownerEmail": "admin@example.com",
      "costUSD": 5,
      "chargedAmount": 7500,
      "currency": "NGN",
      "createdAt": "2026-04-08T07:41:55.350Z"
    }
  ]
}

Validate Coupon

Validate a discount coupon code before purchasing a white-label site.

POSThttps://api.globeverify.com/v1/whitelabel/validate-coupon

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "code": "SUMMER20"
}

Responses

Response200 OK

{
  "success": true,
  "discountPercentage": 20
}

Upgrade/Downgrade Site Tier

Change the subscription tier of an existing white-label site. The price difference will be deducted from your balance.

POSThttps://api.globeverify.com/v1/whitelabel/upgrade

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "orderId": "6a20b55c8a85b55fa05c7a51",
  "newTier": "pro"
}

Responses

Response200 OK

{
  "success": true,
  "message": "Upgraded successfully",
  "data": {
    "tier": "pro",
    "domain": "mysite.getsms.site"
  }
}

Update Branding

Update the logo URL and theme colors of an existing white-label site.

PUThttps://api.globeverify.com/v1/whitelabel/branding

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "orderId": "6a20b55c8a85b55fa05c7a51",
  "logo": "https://example.com/logo.png",
  "primaryColor": "#ff0000",
  "secondaryColor": "#06b6d4"
}

Responses

Response200 OK

{
  "success": true,
  "message": "Branding updated successfully",
  "data": {
    "logoUrl": "https://example.com/logo.png",
    "primaryColor": "#ff0000",
    "secondaryColor": "#06b6d4"
  }
}

Sync Site Data

Synchronize the status and tier of your white-label site with the upstream master network.

POSThttps://api.globeverify.com/v1/whitelabel/sync

Headers

Parameter	Description
x-api-key string	Your Developer API Key
Content-Type string	application/json

Request Body

Payload

{
  "orderId": "6a20b55c8a85b55fa05c7a51"
}

Responses

Response200 OK

{
  "success": true,
  "message": "Site synced successfully",
  "data": {
    "status": "active",
    "tier": "pro"
  }
}