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.