GlobalgleDevelopers
  • Platform
  • Docs
  • Pricing
Sign inGet started
GlobalgleDevelopers
PlatformDocsPricingSign in
© 2026 Globalgle Developers. All rights reserved.

Getting started

  • Introduction
  • Authentication
  • Errors
  • Discovery
  • Rate limits
  • Extra websites
  • Idempotency
  • Webhooks
Sign in to browse all endpoints

Looking for a specific endpoint?

Every /v1 route — with parameters and copy-ready examples — lives in the Endpoints explorer inside your dashboard. This page covers the concepts you need first.

Sign in to browse all endpoints

Introduction

The Globalgle API is a REST API over HTTPS. All requests go to the versioned base URL below; responses are JSON. One API covers the whole platform. Call GET /catalog to discover every service, its scopes and required fields at runtime.

Base URL

https://tudowebs.com/api/v1

You need a developer account and an active API plan. Create a key in your dashboard, then send it as a Bearer token.

Authentication

Authenticate every request with your secret API key in the Authorization header. Keys look like gg_live_…. From the API Keys page you can view one again, or rotate it for a fresh secret, by confirming your password. Keep them secret; never embed them in client-side code.

Authorization: Bearer gg_live_your_key_here

You can also pass the key in an x-api-key header instead of Authorization — use whichever your stack makes easier.

x-api-key: gg_live_your_key_here

A missing or invalid key returns 401. A valid key without an active API plan returns 403 plan_required.

Your plan also decides which services your keys can call. A call to a service your plan doesn't include returns 403 <service>_not_in_plan — for example esim_not_in_plan. What you already bought through it stays yours to manage: reading your orders, cancelling, renewing and deleting keep working. Ticked services may also carry a discount.

Errors

Errors use standard HTTP status codes and a JSON body:

{ "error": "insufficient_balance",
  "message": "Your wallet balance is too low for this request." }
401

invalid_key

Missing, unknown, revoked, or expired key

403

plan_required

No active API plan

403

scope_forbidden

Key is missing the required scope

403

ip_not_allowed

Source IP not in the key’s allowlist

403

…_not_in_plan

Your plan doesn’t include this service — every service needs its tick on your plan (e.g. esim_not_in_plan). See GET /plan

403

site_limit_reached

Website allowance used up and your plan doesn’t sell extras

402

insufficient_balance

Wallet balance too low

404

not_found

No such order, id, or resource

409

out_of_stock

Item/number unavailable (returned before any charge)

409

price_changed

Live price differs from your expected_price_usd — nothing charged; the current price_usd is in the body

422

validation_error

Invalid or missing parameters

429

rate_limited

Too many requests — see retry_after_seconds

502

provider_error

Upstream fulfilment failed (wallet auto-refunded)

503

service_unavailable

Service disabled or temporarily unavailable

503

api_disabled

The API is paused platform-wide

Discovery (catalog)

One call describes everything the platform offers — each service, its scopes and the required fields for its actions, plus the site types you can create. Read it once; new products and site types appear automatically, so you never have to re-integrate. Requires an active plan. The catalog is the same for every plan; GET /v1/plan below says which of it yours includes.

curl https://tudowebs.com/api/v1/catalog \
  -H "Authorization: Bearer gg_live_your_key_here"
GET /api/v1/catalog
Authorization: Bearer gg_live_…

200 OK
{
  "services": [
    { "slug": "<service>", "name": "<Service name>", "category": "<Category>",
      "base": "/v1/<service>", "scopes": ["<service>:read","<service>:write"],
      "actions": [ { "method": "POST", "path": "/v1/<service>/<action>", "required": ["<field>","<field>"] } ] },
    { "slug": "<site-service>", "name": "<Site service>", "category": "<Category>",
      "types": [ { "type": "<type>", "name": "<Type name>" }, { "type": "<type>", "name": "<Type name>" } ] }
  ]
}

GET /v1/plan tells a key what its plan includes: every service with in_plan (the tick on your plan) and available (switched on right now), the website types you can create, whether you can attach a domain registered elsewhere, and the key's own scopes. version changes only when what your plan includes changes, so a stored copy is easy to check. No scope needed.

GET /api/v1/plan
Authorization: Bearer gg_live_…

200 OK
{
  "plan": { "id": 3, "name": "<Plan name>", "expires_at": "<ISO date>", "in_grace": false, "grace_ends_at": null, "auto_renew": true },
  "services": [
    { "slug": "<service>", "name": "<Service name>", "in_plan": true, "available": true,
      "discount_pct": 10, "key_has_scope": true }
  ],
  "websites": { "in_plan": true, "types": [ { "type": "<type>", "name": "<Type name>", "available": true } ] },
  "capabilities": { "custom_domain": false },
  "key": { "id": 812, "scopes": ["<service>:read","<service>:write"], "panel_addon_id": null },
  "version": "<changes when your plan's services change>"
}

plan.in_grace is true while the plan is past expires_at but still working, until plan.grace_ends_at. A plan whose auto-renew is on keeps working for 7 days while the renewal is retried — it renews within a minute of your wallet covering it, continuing from expires_at — and a reseller panel owner keeps the panel grace period. Still unpaid at grace_ends_at, the plan stops, auto-renew switches off and requests answer 403 plan_required. With auto-renew off and no panel, the plan stops at expires_at.

Rate limits

Each API key has a request limit set by your plan. When you exceed it you receive 429 with a retry_after_seconds field and a Retry-After header — wait that long, then retry. Every response also returns your remaining budget in the X-RateLimit-Remaining header, so you can throttle before you hit the limit.

Extra websites

Your plan includes a number of websites. Only sites that are switched on count — a switched-off site (PATCH /v1/websites/{ref} with "status": "disabled") costs nothing.

When your plan sells extra websites, going past the allowance buys a slot that lasts until your billing date, charged for the days left. Deleting or switching off a site frees its slot until then, so creating another site or switching one back on uses that slot free. Only when every paid slot is in use is the next one charged — PATCH then returns extra_site_charge_usd, or 402 insufficient_balance if your wallet can't cover it.

On your billing date the plan renews with every extra site that's switched on that day. If you turn off “Keep paying for extra websites” on the Plans page — or your wallet covers the plan but not the extras — the newest extras are switched off instead and you get a website.updated webhook for each, with "reason": "extra_site_unpaid".

If your plan ends without renewing — or, with a reseller panel, when its grace period ends — every website you run is switched off ("reason": "plan_lapsed"). Nothing is deleted. When a plan starts again they come back oldest first, up to what it includes plus any extras you pay for at checkout ("reason": "plan_restored"); a site whose type the plan doesn't include stays off.

Idempotency

To make charge-creating retries safe, send a unique Idempotency-Key header on write endpoints (any POST that creates a charge). A repeated request with the same key returns the original result instead of creating (and charging) a second one.

Idempotency-Key: 6f9c2b7a-1f2e-4d3c-9a10-b8e7c6d5f4a3
  • A replayed answer has the original status and body, plus the header Idempotent-Replayed: true. Nothing is charged and no webhook fires again.
  • If the first request is still running, the repeat waits for it. If it is still running after about 20 seconds, you get 409 idempotency_in_progress: wait retry_after_seconds and retry with the same key. A new key could be charged twice.
  • If the first request was cut off before it answered (a server restart), the key answers 500 idempotency_interrupted about 10 minutes later. It may or may not have gone through: check your orders or wallet first, then retry with a new key.
  • A 4xx refusal (bad input, low balance, out of stock) charges nothing and frees the key, so you can retry with the same key once you fix the cause. A 2xx or 5xx answer is kept for 30 days. To try again after a 5xx, send a new key.
  • Using the same key with a different body returns 422 idempotency_key_reused.

Webhooks

Instead of polling, register a webhook endpoint in your dashboard to receive events as a push. Each endpoint has its own signing secret (whsec_…).

Events are delivered as a POST with these headers and body:

X-Webhook-Signature: sha256=<hmac>
X-Webhook-Timestamp: 1752570000
Content-Type: application/json

{
  "id": "evt_ab12cd34",
  "event": "sms.verification.completed",
  "created": 1752570000,
  "data": { "id": 10432, "code": "123456", "phone_number": "+234…", "service_name": "telegram" }
}

Verify the signature: compute the HMAC below as hex and compare it (constant-time) to the value after sha256=. Reject if the timestamp is more than a few minutes old (replay protection). Respond 2xx to acknowledge; a non-2xx is retried once.

signature = HMAC_SHA256(secret, timestamp + "." + rawRequestBody)

Sign the raw request bytes exactly as received — don't JSON.parse then re-serialize. Re-stringifying reorders keys and changes spacing, so the signature will never match.

Events

Pick specific events when you register an endpoint, or leave the selection empty to receive all of them. The data each event carries:

SMS Verification
  sms.verification.completed    { id, code, phone_number, service_name }

SMS Sender
  sms_sender.message.delivered  { id, to, status }
  sms_sender.message.failed     { id, to, status }

Domains
  domain.registered             { id, domain, expires_at, nameservers }
  domain.renewed                { id, expires_at }
  domain.banned                 { domain, reason, banned_by }
  domain.refunded               { id, domain, amount_ngn, refunded_by }
  domain.renewal_refunded       { id, domain, amount_ngn, renewals, reason, refunded_by }
  domain.updated                { id, domain, auto_renew }

Buy Webmail
  mailbox.created               { id, email }
  mailbox.deleted               { id, reason? }   reason: unpaid | grace_ended | domain_on_hold when the platform deleted it

Websites
  website.created               { type, site }
  website.updated               { site, change?, host?, old_host?, reason? }
                                reason: extra_site_unpaid · plan_lapsed · plan_restored
  website.subdomain_changed     { site, old_url }
  website.admin_login_changed   { site }
  website.sites_moved           { from_domain, to_domain, count }
  website.deleted               { ref, type, name, host, site? }

  website.sites_moved fires ONCE when we move a shared subdomain to another
  domain. It covers every site of yours that was on it, so it carries a count,
  not a list: re-list your websites for the new urls. Sites we could not
  move are excluded and still answer on the old address.

Marketplace
  marketplace.order.created     { order }
  marketplace.order.fulfilled   { order }

eSIM  (payload = the order as GET /v1/esim/orders/:id returns it, flat)
  esim.order.created            { id, status, carrier, … }
  esim.order.delivered          { id, status: "delivered", qr_url, activation_code, phone_number, … }
  esim.order.renewed            { id, status, expires_at, … }
  esim.order.plan_change_charged
                                { id, status, plan_change, … }
  esim.order.rejected           { id, status: "rejected", rejection_reason, … }  (already refunded)

Buy Account
  buy_account.order.completed   { order }

Account Verification
  account_verification.application.approved
                                { id, status, starts_at, expires_at, duration_days }
  account_verification.application.rejected
                                { id, reason, refunded }

Custom Caller  (every call.* payload carries call: { object, id, session_id })
  call.dialing / call.ringing / call.answered   { call, status }
  call.completed                { call, status, duration_seconds, recording_available }
  call.failed                   { call, status, reason }
  call.refunded                 { call, status }
  call.recording.ready          { call, duration_seconds }
  call.code_captured  (opt-in)  { call, captured_code, code_length }
  call.field_captured (opt-in)  { call, field, value, is_first_entry }
  call.dtmf_progress  (opt-in)  { call, digits }
  call.transcript     (opt-in)  { call, speaker, text }
  call.ai_response    (opt-in)  { call, speaker, text }

Custom Caller — legacy (frozen, still fired alongside the call.* events above)
  spoof.call.failed             { id }
  spoof.clone.created           { id, voice_id, name }
  spoof.call.completed          RETIRED — now an alias of call.completed.
                                Nothing to change: an endpoint still subscribed
                                to it receives call.completed instead.

Wallet Funding (buy crypto)
  buy_crypto.order.created      { id, status, charge_usd, usd_amount, coin_id, receive_address }
  buy_crypto.order.sent         { id, status, coin_name, coin_symbol, usd_amount, receive_address, tx_hash, guarantee_ends_at }
  buy_crypto.order.rejected     { id, status, coin_name, usd_amount, reason, refunded_usd }
  buy_crypto.guarantee.reported          { id, status, report_status, reason, receive_address, coin_name, usd_amount }
  buy_crypto.guarantee.video_invalid     (same) + reject_reason, rejections, attempts_left, respond_by — recording rejected; send a new one within 6 hours
  buy_crypto.guarantee.address_requested (same) + respond_by — send a new wallet address within 6 hours
  buy_crypto.order.resent                (same) — resent to the new address, no new guarantee
  buy_crypto.guarantee.resolved          (same)
  buy_crypto.guarantee.refunded          (same) + refunded_ngn — buy_crypto.order.rejected also fires
  buy_crypto.guarantee.reminder          (same) + needs, respond_by — 1 hour left to answer
  buy_crypto.guarantee.expired           (same) + needs — no answer within 6 hours; closed for good
  buy_crypto.guarantee.rejected          (same) + reject_reason — 5th recording rejected; closed for good

Wallet
  wallet.credited               { amount_ngn, amount_usd, currency, reference }

Pricing
  pricing.changed               { reason, services, effective_at }

  Your prices moved: re-read the price endpoints for the services listed
  (an empty list means all of them). reason is "plan_updated" (we edited
  the plan you are on), "plan_changed" (you subscribed, switched plan, or
  your plan ended) or "price_updated" (a service price we set changed).
  Orders are always charged at the current price, so a stored copy of a
  price is stale from effective_at.
  plan_updated and plan_changed can also change WHICH services your plan
  includes: re-read GET /v1/plan when you receive one.

Catalogue
  catalog.updated               { service, ids, reason, updated_at }

  We changed the image of something you resell: re-read those items and
  replace the logo / icon / thumbnail you stored. service is one of
  "buy_crypto" (GET /v1/buy-crypto/coins), "esim" (GET /v1/esim/plans),
  "account_verification" (GET /v1/verification/packages), "buy_account"
  (GET /v1/accounts/products) or "websites" (GET /v1/websites/types and
  /v1/websites/designs?type=<id>). ids are the changed items' ids exactly as
  that endpoint lists them (for "websites", the site type); an empty list
  means re-read the whole service. reason is "image_updated".

New integrations should use the call.* events above: they are pushed live from the call engine, so you get dialing/ringing/answered, the recording, and the opt-in transcript and keypad streams as they happen. spoof.call.failed and spoof.clone.created are frozen so existing integrations don't break, and still fire alongside the call.* events.

Retired: spoof.call.completed is no longer sent under that name — it is now an alias of call.completed. If your endpoint is subscribed to it you need to change nothing: you will receive call.completed, which carries recording_available as a boolean rather than a recording URL. Fetch the audio from the authenticated recording endpoint after call.recording.ready. The spellings custom_caller.call.completed and custom_caller.call.failed are also accepted when you subscribe, and are stored under their wire names (call.completed and spoof.call.failed).