Activations

An activation is one purchased number waiting for one code. Create it, poll it, and read the code when it lands. See the activation lifecycle for the full state machine.

Create an activation

Buy a number for a service + country. Charges your wallet upfront and returns the number immediately in WAITING. Pass an optional max_price (USD decimal string) to reject the buy if the price has risen above your ceiling.

Body

{
  "service": "whatsapp",
  "country": "us",
  "max_price": "1.00"
}

• service — required, slug from /v1/services.
• country — required, ISO code from /v1/countries.
• max_price — optional, reject the buy if the price exceeds this (USD).
• reusable — optional boolean. When true, buy only a reusable number you can re-acquire within 20 minutes (see Reuse a number).

curl -X POST https://api.otp.black/v1/activations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"us"}'

{
  "id": "act_9f2c1a",
  "phone": "+15551234567",
  "status": "WAITING",
  "expires_at": "2026-07-09T12:20:00.000Z"
}

Get an activation

Fetch the current status. Poll every few seconds. While the code is pending, status is WAITING and code is null. Once the SMS arrives, status becomes COMPLETED and both code and full_text are populated.

curl https://api.otp.black/v1/activations/act_9f2c1a \
  -H "Authorization: Bearer $API_KEY"

{
  "id": "act_9f2c1a",
  "phone": "+15551234567",
  "status": "COMPLETED",
  "code": "483920",
  "full_text": "Your code is 483920",
  "reusable": false,
  "created_at": "2026-07-09T12:00:00.000Z"
}

status is one of WAITING, COMPLETED, CANCELLED, EXPIRED, REFUNDED, or FAILED. code is present only when status is COMPLETED.

Cancel an activation

Cancel a WAITING activation you no longer need. The number is released and your wallet is refunded. Already-terminal activations return 400.

curl -X POST https://api.otp.black/v1/activations/act_9f2c1a/cancel \
  -H "Authorization: Bearer $API_KEY"

{ "ok": true }

Reuse a number

Re-acquire the same number for another code, for up to 20 minutes after the original order. Only works for numbers bought with reusable: true. This creates a new activation (a fresh wallet charge) bound to the same number and returns it in WAITING.

• 400 — the number isn't reusable, or the 20-minute window has passed.
• 402 — wallet balance too low.

curl -X POST https://api.otp.black/v1/activations/act_9f2c1a/reuse \
  -H "Authorization: Bearer $API_KEY"

{
  "id": "act_7b3d2e",
  "phone": "+15551234567",
  "expires_at": "2026-07-09T12:40:00.000Z"
}