Activations

What is an activation?

An activation is a short-lived rental of a phone number for one SMS-OTP. You request it, the platform reserves a number, you read the inbound code, and the activation closes — either successfully (billed) or as expired (free).

Use activations when you only need a single code (signup, password reset, KYC check). For multiple SMS over a longer window see Rentals.

Lifecycle

waiting ─► sms_received ─► finished       (you confirm; billed)
   │                  └──► refunded       (no code; free)
   └─► expired                            (timeout; free)

• waiting — number reserved, no SMS yet.
• sms_received — at least one inbound SMS captured.
• finished — you called the finish endpoint; charged.
• expired — duration elapsed with no SMS; not charged.
• refunded — you cancelled before confirming; not charged.

Create

curl -X POST https://api.eveses.com/v1/activations \
  -H "Authorization: Bearer $EVESES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "country": "ua",
    "service": "telegram",
    "duration_minutes": 15,
    "max_price_cents": 12
  }'

Poll

curl https://api.eveses.com/v1/activations/9a1f2c3d-4e5b-6a7c-8d9e-0f1a2b3c4d5e \
  -H "Authorization: Bearer $EVESES_API_KEY"

Polling at 1.5–2 second intervals is fine; sub-second polling is rate-limited. Webhooks are strongly recommended in production.

Finish

Confirms the activation and triggers the charge. Idempotent — calling twice is safe.

curl -X POST https://api.eveses.com/v1/activations/9a1f2c3d-4e5b-6a7c-8d9e-0f1a2b3c4d5e/finish \
  -H "Authorization: Bearer $EVESES_API_KEY"

Cancel

Cancels before any SMS is delivered. Returns a 409 if an SMS has already arrived (call finish instead).

curl -X POST https://api.eveses.com/v1/activations/9a1f2c3d-4e5b-6a7c-8d9e-0f1a2b3c4d5e/cancel \
  -H "Authorization: Bearer $EVESES_API_KEY"