🔧 API Changelog

🧾 Invoices your finance team will accept — over the API

Buying through a company used to mean opening a support ticket for every document. Invoicing is now a first-class API surface: set your company details once, raise an invoice, download it as a real PDF. A receipt is issued automatically the moment a top-up settles — no call needed.

• <code class="font-mono">GET|PUT /api/v1/billing/profile</code> — legal name, address, tax id; partial updates accepted
• <code class="font-mono">GET|POST /api/v1/billing/invoices</code>, <code class="font-mono">GET /api/v1/billing/invoices/{uuid}</code>, <code class="font-mono">POST .../cancel</code>
• <code class="font-mono">GET /api/v1/billing/invoices/{uuid}/pdf</code> → <code class="font-mono">application/pdf</code>, same auth as the detail route
• <code class="font-mono">POST /api/v1/billing/deposits/{deposit}/invoice</code> — invoice a top-up that has <em>already</em> settled, which is the common case
• <code class="font-mono">GET /api/v1/billing/usage</code> — the consumption an invoice is drawn from

🩹 A wrong URL is answered in the API’s own language

The API host returned an HTML error page to JSON clients on unknown routes and on some errors. If your client did response.json(), you got a parse error instead of a 404 — the single most confusing failure mode for a new integrator. Every response from api.eveses.com is now JSON.

• Unknown route → <code class="font-mono">404 application/json</code>, not an HTML page
• Unauthenticated → <code class="font-mono">401 application/json</code>
• The processor’s payment reference is no longer truncated in storage, so a stored reference matches the payment again

🛡️ Proxies: paid extras that actually arrive, and refunds that happen

Proxy add-ons a buyer paid for could be silently dropped on the way upstream. They are now sent where the provider actually reads them, recorded on the order, and verified after provisioning. Alongside that, a real subscription lifecycle and refunds on every failure path.

• <code class="font-mono">extra_requirements</code> (array of strings, max 10) and <code class="font-mono">extra_requirement_labels</code> on <code class="font-mono">POST /api/v1/proxy/orders</code>
• <code class="font-mono">POST /api/v1/proxy/subscription/cancel</code> · <code class="font-mono">/pause</code> · <code class="font-mono">/resume</code>
• A purchase that fails upstream returns the money; so does an order the provider later undoes
• A per-IP order closes once its term has passed instead of lingering active
• A malformed UUID is rejected with <code class="font-mono">422</code> before it reaches the database — used to surface as a <code class="font-mono">500</code>
• Each customer is served the entry node nearest to them

📦 SDKs 0.7.0 — billing in all four languages

The JS, Python, Go and PHP SDKs all reached 0.7.0 with a matching billing module, plus a bytes path so an invoice PDF comes back as binary rather than mangled text. 0.6.0 before it carried the proxy extra_requirements field across all four.

• Eight billing methods per SDK: profile read/update, invoice list/create/detail/cancel/PDF, deposit invoice
• Binary responses: Python <code class="font-mono">request(raw=True)</code>, JS <code class="font-mono">RequestOptions.raw</code> → <code class="font-mono">Uint8Array</code>, Go <code class="font-mono">*[]byte</code> out-param
• Every SDK now ships a CHANGELOG of its own

🏭 Supplier cabinet API

Suppliers who sell to us have their own authenticated surface, separate from the customer API. A supplier organisation only goes live after we approve it, and a cabinet cannot be switched live until a conformance run passes.

• <code class="font-mono">GET /api/v1/supplier/me</code> · <code class="font-mono">/credentials</code> · <code class="font-mono">/api-keys</code> · <code class="font-mono">/traffic</code> · <code class="font-mono">/invoices</code>
• <code class="font-mono">POST|GET /api/v1/supplier/conformance</code> — the integration suite that gates going live
• Token-scoped and unauthenticated: <code class="font-mono">GET /api/v1/supplier-applications/{token}</code>, <code class="font-mono">POST /api/v1/supplier-invites/{token}/accept</code>
• Settlement invoices bill <strong>delivered</strong> orders only

🌍 Proxy catalogue drills down to city and carrier

Per-country state / city / ISP breakdown on the proxy catalogue, so a buyer can narrow to a city or a carrier instead of only a country.

• <code class="font-mono">GET /api/v1/proxy/locations/detail</code>

🛒 Marketplace — buy digital goods over the API

The marketplace moved from a storefront-only feature to a full API product. Delivered credentials are parsed into named fields where the supplier’s format allows it, with the raw line preserved.

• <code class="font-mono">GET /api/v1/marketplace/catalog</code> — filters on <code class="font-mono">kind</code>, <code class="font-mono">platform</code>, <code class="font-mono">country</code>, <code class="font-mono">mail_service</code>, <code class="font-mono">twofa</code> and more; pass <code class="font-mono">per_page</code> or you get the whole catalogue
• <code class="font-mono">POST /api/v1/marketplace/quote</code> — firm price for a quantity before committing
• <code class="font-mono">POST /api/v1/marketplace/buy</code> — validated against the product’s declared <code class="font-mono">input_schema</code>
• <code class="font-mono">POST /api/v1/marketplace/orders/{order}/reveal</code> — the only endpoint that returns credentials; order detail deliberately does not
• Guest-safe public mirrors under <code class="font-mono">/api/public/marketplace/*</code>

👤 Ready-made accounts over the API

Buy pre-made social accounts programmatically. The upstream supplier is never exposed.

• <code class="font-mono">GET /api/v1/accounts/catalog</code> · <code class="font-mono">/quote</code> · <code class="font-mono">POST /api/v1/accounts</code> · <code class="font-mono">GET /api/v1/accounts/{account}</code>

🗺️ One-call country summary + a non-VoIP flag

Per-country availability and price in a single call, so a storefront no longer needs one request per country. Authenticated callers get loyalty-discounted prices.

• <code class="font-mono">GET /api/v1/numbers/summary</code> and its public twin
• <code class="font-mono">nonvoip</code> on an order, for callers who need a number that will not be rejected as VoIP
• Fixed: the public country list ignored <code class="font-mono">?service=</code> and answered with every country we sell — including ones that could not fulfil the request

🧱 Everything consolidated onto /api/v1

The largest public-surface change since v1 launched. It should have been announced here at the time; it was not, and this entry is written after the fact. The entire /api/account/* prefix is gone. It was documented as internal-SPA and outside the stability guarantee, but it was reachable with an API key and some integrators used it.

• Every product exposes the same order shape: <code class="font-mono">GET|POST /api/v1/{product}/orders</code>, then <code class="font-mono">/{uuid}</code>, <code class="font-mono">/cancel</code>, <code class="font-mono">/finish</code>, <code class="font-mono">/retry</code>, <code class="font-mono">/repeat</code>, <code class="font-mono">/auto-renew</code> where supported
• SMS moved into the order resource: <code class="font-mono">GET /api/v1/numbers/orders/{uuid}/sms</code>
• <code class="font-mono">GET /api/v1/orders</code> — one cross-product feed (numbers, proxies, web-unblocker, emails, marketplace)
• <code class="font-mono">GET /api/v1/pricing</code> and <code class="font-mono">GET /api/v1/quotas</code> — unified pricing and remaining quota in one call
• <code class="font-mono">features</code> on <code class="font-mono">GET /api/v1/me</code> — which products this account may use
• <code class="font-mono">RateLimit-*</code> headers plus <code class="font-mono">Retry-After</code> on 429, so a client can back off from the response instead of guessing
• Throttling is now per API token rather than per account — one noisy key cannot exhaust another’s budget

🤖 Captcha solving, free trials, and 18 free tools

Captcha solving billed per solved captcha, a "just to try" allowance for proxy traffic and web-unblocker requests, and a set of free public utilities that need no auth at all.

• <code class="font-mono">POST /api/v1/captcha/solve</code>, <code class="font-mono">GET /api/v1/captcha/result/{task}</code>, <code class="font-mono">/rates</code>, <code class="font-mono">/usage</code> — <code class="font-mono">retry_after</code> is returned when you poll too early
• <code class="font-mono">GET /api/v1/trial</code>, <code class="font-mono">POST /api/v1/trial/subscribe</code>
• <code class="font-mono">/api/tools/*</code> — 18 free routes, no auth (e.g. <code class="font-mono">GET /api/tools/whats-my-ip</code>)
• Fixed: a non-numeric captcha task id returned a database-level <code class="font-mono">500</code>; it now returns <code class="font-mono">404</code>

🌐 Proxies and Web Unblocker on the API

Both products run on the same wallet and the same API key as your numbers. Written up after the fact — the surface shipped without an announcement here.

• Proxies: <code class="font-mono">GET /api/v1/proxy/pricing</code> · <code class="font-mono">/quote</code> · <code class="font-mono">/locations</code> · <code class="font-mono">/endpoints</code> · <code class="font-mono">/usage</code> · <code class="font-mono">/quotas</code>
• <code class="font-mono">GET|POST /api/v1/proxy/orders</code>, then <code class="font-mono">/{uuid}</code>, <code class="font-mono">/extend</code>, <code class="font-mono">/auto-renew</code>; <code class="font-mono">POST /api/v1/proxy/sessions/reset</code>
• Web Unblocker: <code class="font-mono">GET /api/v1/webunblocker/pricing</code> · <code class="font-mono">/quote</code> · <code class="font-mono">/quotas</code>, <code class="font-mono">GET|POST /api/v1/webunblocker/orders</code> — renders JavaScript, works through bot protection, billed for successful requests
• Free allowance on both: <code class="font-mono">POST /api/v1/{proxy|webunblocker}/trial</code>

🏷️ Pricing options now expose the full price ladder + stock counts

The per-duration options[] on GET /public/numbers/pricing and /services now carries a count per price — the numbers available at that price point — and reflects each provider’s full purchasable price ladder, not just its cheapest tier.

• Each entry in <code class="font-mono">options[]</code> gains <code class="font-mono">count</code> (integer or null when a provider doesn’t report stock)
• Providers with tiered inventory contribute every purchasable price point; still fully anonymous (no provider names/ids)
• Fixed: a provider advertising a price with zero real stock no longer surfaces as a phantom option, so a chosen price provisions instead of failing

🧰 Official SDKs (JS · Python · Go · PHP) + MCP server

Build on Eveses in your language of choice, and let AI assistants use Eveses directly. Four official SDKs plus a hosted Model Context Protocol server at POST /api/mcp — point Claude, Cursor, Windsurf or any MCP client at it with your API key and it can buy numbers and read OTP codes natively.

• @eveses/sdk (npm), Eveses (pip), github.com/evesescom/go-sdk, eveses/sdk (composer) — same surface across all four
• MCP tools: buy_number, get_otp, cancel_number, list_countries, list_services, wallet_balance
• 10 ready-to-run example projects: Telegram/WhatsApp OTP, Playwright tests, Next.js + Laravel phone verification, concurrent Go provisioning, an AI-agent SMS tool

📊 Developer API expansion — usage, logs, telemetry

A batch of new read endpoints and fields for building dashboards and monitoring on top of Eveses.

• GET /account/api-logs — per-request API-key call log (method, path, status, latency)
• GET /account/billing/usage — spend broken down by service + daily buckets
• GET /account/orders/summary — order counts + p95 SMS-delivery latency
• GET /account/webhooks/stats — 24h delivery success rate, failures, avg response time
• Public /numbers/services now returns per-service p95 delivery latency + delivery rate
• 2FA recovery-codes download, richer API-key metadata (prefix, environment, today's usage)

🩹 Developer docs render again + runnable code samples

The interactive API reference at /docs is fixed, and every operation now ships copy-paste examples with real request bodies in JS, Python, Go and PHP. Behind the scenes we also hardened refund idempotency and made the FX-rate cache resilient to a missed refresh.

🔗 v1 mirror (round 2): /refunds, /auto-recharge, /spending-alerts

Three more internal-SPA endpoints lifted to /api/v1/* with v1 stability guarantees. Refunds, auto-recharge configuration, and spending alerts are now first-class SDK surfaces.

• POST /api/v1/refunds — request a refund for a wallet transaction (per-transaction ownership check, throttle 10/min)
• GET / PUT /api/v1/auto-recharge — read/update the auto-recharge threshold + top-up amount
• GET / PUT /api/v1/spending-alerts — read/update daily/weekly spending limits + email/in-app alert preferences
• Internal /api/account/* equivalents unchanged.

🔗 v1 mirror: /me, /integrations/telegram, /wallet/transfers + Idempotency-Key

Three internal-SPA endpoints are now public under /api/v1/* with v1 stability guarantees. POST /api/v1/wallet/transfers accepts an optional Idempotency-Key header (24h cache, Stripe pattern).

• GET /api/v1/me
• GET /api/v1/integrations/telegram
• POST /api/v1/integrations/telegram/link-token
• DELETE /api/v1/integrations/telegram
• POST /api/v1/wallet/transfers

⚡ Real-time push over WebSockets (beta) + multi-provider crypto + localized errors

WebSocket push at wss://ws.eveses.com/app/{key} with private user.{id} channel carrying 6 events. Three crypto deposit gateways behind one env switch. API responses now honor Accept-Language.

• notification.created — new notification for the user
• wallet.updated — balance changed
• deposit.updated — deposit status changed
• order.updated — activation/rental state changed
• badges.updated — unread counters refresh
• support.message.received — new message in a support thread
• HTTPS webhooks remain recommended for server-to-server integrations

💸 Wallet P2P transfer (internal SPA, v1 mirror landed 2026-05-25)

POST /api/account/transfers instant balance transfer between accounts. The public /api/v1/wallet/transfers mirror with Idempotency-Key landed in v2.5.5.

⚡ Edge caching on pricing + ETag on SDK-adjacent reads

~280ms → ~35ms on /api/v1/numbers/pricing (p95 anecdotal). Cache-Control headers on /api/public/numbers/* + per-tenant cache on /api/v1/numbers/*. Strong ETag on internal account GETs.

🎟️ Coupons + magic-link auth + batch activations + sms-activate gateway

POST /api/v1/batch/activations provisions up to 50 activations in one round-trip. POST /api/auth/magic-link for passwordless login. sms-activate.io compat shim at /stubs/handler_api.php.

🐍 New PHP + Go SDKs; webhook payloads add X-Webhook-Schema-Version

PHP SDK at github.com/evesescom/php-sdk, Go SDK at go get github.com/evesescom/go-sdk. All webhook deliveries now carry X-Webhook-Schema-Version: 1.

🪝 Webhooks v2 — signed payloads with timestamp + replay protection

All webhook deliveries now include X-Eveses-Timestamp alongside X-Eveses-Signature. Verify in constant time, reject when timestamp > 5 minutes old. Old sha256(body) format disabled.