Verify: OTP codes by SMS, WhatsApp, call and e-mail
Prove that a person owns a phone number. Codes are random, single use, expire, and are never shown to you or stored in clear.
- sms
- A code by SMS from your phone.
- Echo emails the code from one of your email accounts; the person types it.
- A code by WhatsApp from your linked number.
- phone_call
- Echo calls the number and hangs up as it rings; the person types the number that called.
- missed_call
- The person calls your phone; no code to type.
Start
POST /v1/echo/verificationschannel is optional. Without it Echo picks the first method your app uses and can serve: email when to is an address; otherwise WhatsApp, then SMS, then a phone call, then a missed call. If none can, the answer is 409 no_method_available.
Check the code
POST /v1/echo/verifications/VERIFICATION_ID/checkPhone call: Echo calls the person
With channel phone_call, Echo calls the number from one of your SIMs and hangs up as soon as it rings. The person types the number that called them; send it to /check as code (the full number, or its last 6 digits or more; spaces, + and a leading 0 are fine). Only 2 wrong tries. The API never returns that number. The method is only as strong as the number of different numbers Echo can call from, so on its own (a session whose only method is phone_call, or a single code) it is accepted only when at least 20 different numbers can call that destination; combine it with sms, whatsapp or missed_call otherwise.
POST /v1/echo/verifications/VERIFICATION_ID/checkMissed-call verification
With missed_call, show the person the number in call_to and ask them to call it. Your phone sees the call, hangs up, and the verification turns approved. Poll it or wait for the webhook.
- Five wrong codes end a verification (two wrong numbers for a phone call).
- Starting again for the same number resends a new code (at most 5 sends).
- A code expires after the lifetime set on your app (10 minutes by default).
- Every code says the same one line, whoever sends it: Your OTP is 123456, in English unless you ask for locale ar or tr (Arabic or Turkish). Nothing can be added to it, not even a brand name.
Several methods, one customer
Send methods (and email and/or phone) instead of channel and to. Echo answers with a link: the customer opens it on Echo's own page, asks for each code in turn and types it. require says how many methods must be verified, from 1 up to all of them.
POST /v1/echo/verifications- Nothing is sent when the session is made. The customer taps Get code for each method, one at a time, like a security verification.
- All methods required: they are done in order, one at a time. Fewer required: the customer picks which ones.
- Each method has a 60-second wait between codes and at most 3 codes. A session lasts 30 minutes.
- Each code is a verification: it costs what a code costs, with your app's devices, its switches and Echo devices as for any code. The code says the same fixed line (locale en, ar or tr).
- The customer never types an email address or a number: you give them when you make the session, and Echo shows them masked.
- echo.verification.approved is sent when the session is approved. Optional return_url (https) adds a Continue button at the end.
To build your own page instead: GET the session, then POST /send with a method and POST /check with a method and the code (the method may be left out when the session has one).
POST /v1/echo/verifications/VERIFICATION_ID/sendEmbedding the page, and redeeming the proof
To show the customer's page inside your own page, give embed_origin (your page's origin, https, or http on localhost) when you make the session, and open the link with ?embed=1 (add &theme=dark for a dark page). Only that origin may frame it, and only that origin receives the result.
- The embedded page tells yours what happens with postMessage, always with source: "echo": its height ({type: "resize", height}), the result ({type: "verified", proof}) or that the session ended ({type: "ended"}), and that the customer closed it ({type: "closed"}). Check event.origin is Echo's.
- Your server turns the proof in with POST /v1/echo/verifications/redeem {proof}: valid: true, the verified methods and your reference. A proof works once, only for your own app, and only for an approved session.
- reference (up to 800 characters) is your private note: Echo keeps it sealed, never shows it to the customer, hands it back once at redeem and then erases it.
- skip_unavailable: true asks for everything you would like and leaves out what your app cannot serve (at least one must remain). decoy: true makes a session that looks real but sends nothing, costs nothing and can never succeed, for a name that does not exist, so the screen reveals nothing.
POST /v1/echo/verifications/redeem