Skip to main content
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 a Surge verification number, the API returns an opted_out error on the create call. You cannot send verification codes to opted-out numbers. Show the error’s message field to the user which tells them to send the code “START” to the appropriate phone number to opt back in. Alternatively 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 behavior. You cannot customize 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

  • 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.