REST API v1

DogeSMS Control API Documentation

Use the unified /api/control endpoints to automate number inventory, activations, SMS retrieval, cancellations, reuse, and rentals. Supports OAuth2 Client Credentials or API Key signing. All write operations require an Idempotency-Key.

View API Reference Request Postman Collection

Quickstart workflow

A typical integration goes from credentials to delivery tracking in four small steps.

Create credentials

Generate an OAuth2 client or API key in the console before making any control request.

Keep one credential set per environment so rate limits, audits, and key rotation stay predictable.

Query inventory

List supported services and countries first, then choose a valid service-country combination before ordering.

Inventory and pricing can change by supplier state, so avoid hard-coding assumptions.

Create the order

Submit the activation or rental request with an Idempotency-Key to prevent duplicate charges.

Persist the returned requestId or rentalId immediately for reconciliation and customer support.

Track delivery

Poll the request status, collect SMS content, and cancel the order if the delivery window expires.

Treat polling, retries, cancellation, and refund handling as part of the same operational workflow.

Authentication

• OAuth2 Client Credentials recommended; access_token expires after 2 hours.

• Static API Key supported via X-API-Key header.

• Refresh keys anytime in the console; IP whitelist available.

Rate Limiting & Idempotency

• Default limits: 10 writes/sec, 30 reads/sec.

• Use the Idempotency-Key header to prevent duplicate charges; generate a unique UUID per transaction.

• On HTTP 429, apply exponential backoff before retrying.

Operational model

Treat the API as an order workflow rather than a single request-response integration.

Write safety first

Every order-creating or state-changing request should include its own Idempotency-Key so retries stay financially safe.

Model the order lifecycle

Track pending, received, cancelled, and expired states explicitly so support teams can explain outcomes without manual log digging.

Build for retries

Handle HTTP 429, supplier inventory changes, and delayed SMS as normal operational conditions instead of exceptional failures.

Core Endpoints

Common endpoints shown below. See the OpenAPI file for the full list.

Method	Path	Description	Common Responses
GET	/api/control/balance	Get account balance	200 Balance data returned successfully. / 401 Authentication failed. Check the token, API key, or signing context.
GET	/api/control/services	List available services	200 Service catalog returned successfully. / 401 Authentication failed or the credential does not have access to this scope.
GET	/api/control/inventory	Query inventory and starting prices	200 Inventory and pricing data returned successfully. / 404 The requested service code does not exist or is not enabled.
POST	/api/control/activations	Create an OTP activation request	200 Activation order accepted and the allocation result is returned. / 402 Insufficient balance for the requested country-service combination. / 460 No supplier inventory is currently available for the requested combination.
GET	/api/control/activations/{requestId}	Get activation status and SMS content	200 Activation state returned successfully. / 404 The requestId does not exist or is no longer visible to the current credential.
PATCH	/api/control/activations/{requestId}/cancel	Cancel a pending activation request	200 Cancellation completed successfully. / 404 The requestId was not found or the order is already closed. / 409 The order is in a state that can no longer be cancelled.
POST	/api/control/rentals	Create a long-term rental order	200 Rental order accepted and the assigned number is returned. / 402 Insufficient balance for the requested rental term. / 460 No rental inventory is currently available for the selected country.

GET/api/control/balance

Get account balance

Returns available balance, frozen funds, and settlement metadata used before creating new orders.

Parameters

No request parameters are required for this endpoint.

Response semantics

200

Balance data returned successfully.

401

Authentication failed. Check the token, API key, or signing context.

GET/api/control/services

List available services

Returns service codes, categories, and reuse support so the client can render an orderable service catalog.

Parameters

No request parameters are required for this endpoint.

Response semantics

200

Service catalog returned successfully.

401

Authentication failed or the credential does not have access to this scope.

GET/api/control/inventory

Query inventory and starting prices

Returns available countries, starting prices, inventory counts, and reuse capability for a target service.

Parameters

serviceCodestringRequired

Target service code used to scope the inventory response.

countryCodestringOptional

Optional country filter when you want to inspect a single destination market.

Response semantics

200

Inventory and pricing data returned successfully.

404

The requested service code does not exist or is not enabled.

POST/api/control/activations

Create an OTP activation request

Creates a one-time order, allocates a number, and returns the requestId used for polling, cancellation, and refunds.

Parameters

serviceCodestringRequired

Service code to activate, such as whatsapp or telegram.

countryCodestringRequired

Destination country for number allocation.

reusebooleanOptional

Optional flag that prioritizes reusable inventory when the target service supports it.

Response semantics

200

Activation order accepted and the allocation result is returned.

402

Insufficient balance for the requested country-service combination.

460

No supplier inventory is currently available for the requested combination.

GET/api/control/activations/{requestId}

Get activation status and SMS content

Returns the current state, timestamps, reuse window, and latest SMS payload for a previously created activation request.

Parameters

requestIdstringRequired

The activation request identifier returned when the order was created.

Response semantics

200

Activation state returned successfully.

404

The requestId does not exist or is no longer visible to the current credential.

PATCH/api/control/activations/{requestId}/cancel

Cancel a pending activation request

Cancels an order that is still waiting, stops further polling, and releases the supplier reservation when allowed.

Parameters

requestIdstringRequired

The activation request identifier to cancel.

Response semantics

200

Cancellation completed successfully.

404

The requestId was not found or the order is already closed.

409

The order is in a state that can no longer be cancelled.

POST/api/control/rentals

Create a long-term rental order

Allocates a monthly rental number and returns lifecycle information, auto-renew status, and attached service metadata.

Parameters

countryCodestringRequired

Country used to allocate the rental inventory.

monthsintegerRequired

Rental duration in months, usually within the supported 1-12 month range.

notestringOptional

Optional internal note to distinguish projects, channels, or downstream ownership.

Response semantics

200

Rental order accepted and the assigned number is returned.

402

Insufficient balance for the requested rental term.

460

No rental inventory is currently available for the selected country.

Activation Request Example

Request body and response JSON when calling POST /api/control/activations.

POST /api/control/activations
Headers:
  Authorization: Bearer <token>
  Idempotency-Key: 73b7-...-ff2

Body:
{
  "serviceCode": "whatsapp",
  "countryCode": "US",
  "reuse": true
}

Response 200:
{
  "requestId": "act-123",
  "number": "+1 650 555 0101",
  "expiresAt": "<ISO8601 timestamp>",
  "canReuseUntil": "<ISO8601 timestamp>"
}

Supported Services & Countries

Currently 6 services and 10 countries/regions available.

📱 WhatsApp✈️ Telegram🔍 Google🎵 TikTok🛒 Amazon🧧 淘宝

Use inventory endpoints instead of static assumptions so operations, dashboards, and pricing stay aligned with live supplier state.

Common error semantics

These statuses appear frequently in production-style integrations. Handle them explicitly rather than with generic retries.

401

Authentication or scope error

The token, API key, or credential scope is missing, expired, or not allowed to access the target resource.

Refresh credentials, verify the environment, and confirm the request is signed with the correct tenant context.

402

Balance not sufficient

The account does not have enough available balance to create the requested activation or rental order.

Check the balance endpoint before retrying and top up the account before resubmitting the order.

409

State conflict

The order is already completed, cancelled, or otherwise not in a mutable state for the attempted operation.

Re-fetch order state and update the client workflow instead of blindly retrying the same write request.

429

Rate limit reached

The client exceeded the current read or write quota window.

Apply exponential backoff, preserve idempotency keys, and queue retries rather than flooding the endpoint.

460

Supplier inventory unavailable

The target country-service combination cannot be fulfilled with current live supply.

Query inventory again, switch country or service, or surface the shortage to the operator for manual choice.

Technical Support

Telegram Support

@dogesms_support

Hours: Daily 09:00-21:00 UTC+8 for live follow-up

Email Support

support@dogesms.com

Hours: 24/7 ticket intake with business-hour review

For enterprise access or high-concurrency quotas, contact the sales team.