Usage patterns and delivery gotchas

Verification codes are sent as SMS, which inherits SMS's quirks. Here's what to plan for in production.

Opted-out contacts

If the phone number has previously replied STOP to your number, the API returns an opted_out error on the create call. You cannot send verification codes to opted-out numbers. The right behaviour in your UI is to surface a friendly error and offer the user a different verification path (email, support contact) — don't retry on the same number.

International numbers

Codes deliver to most international numbers, but delivery speed varies by carrier. If a user doesn't receive the code within 60 seconds:

• Prompt them to request a resend (create a new verification).
• The original verification is now wasted from the user's perspective; if the new code arrives and matches, treat it as success.
• For a small number of countries / carriers, delivery can be intermittent. Monitor result: expired rates by region as a leading indicator.

Carrier filtering

Verification codes are generally exempt from spam filtering — carriers know OTP traffic is high-trust by pattern. But:

• Very high volumes of verifications to a single area code or carrier can trigger rate limits.
• A handful of carriers periodically tighten their filters and OTP messages get caught. If you see a spike in incorrect results that's actually "user never got the code," check the per-carrier delivery rate in your message logs.

Sender number

Verification codes are sent from a shared pool of Surge demo numbers, not from any phone number on your account. The sending number varies between verifications — users may see different "from" numbers across OTP flows. This is expected behaviour. You cannot customise the sender number for verifications.

This also means that if a user texts STOP to the sender number from a verification, it opts them out of that specific Surge number, not out of your campaign numbers. Contact support if this creates operational issues.

Implementation tips

• Don't show the verification ID in your UI. The id is opaque; storing it in your session is fine, but exposing it client-side gives an attacker the input to brute-force /checks.
• Lock retries on your side too. Surge enforces an exhausted threshold, but you should also rate-limit resends and re-checks at your application layer to prevent one user from racking up SMS costs.
• Log the result, not the code. When debugging, log verification.id and result — never the six-digit code. Treat the code like a password.
• Carrier lookup runs automatically. When you create a verification, Surge enqueues a carrier lookup in the background. This improves future delivery decisions for that number but adds a small delay before the first code is sent. If delivery speed is critical, ensure your infrastructure can handle codes that may arrive 2–5 seconds after the API response.