Phone Verification (OTP)

Send OTP verification code

post/verify/send

Request

  • Base URL: https://api.envoisms.ma/v1
  • URL: https://api.envoisms.ma/v1/verify/send
  • Auth: HTTP bearer

Request body

tostring required

Recipient phone number in international E.164 format (e.g. +212612345678, +33612345678). International destinations are fully supported via the whatsapp channel when configured on a Verify App with allowed_countries.

channel'sms' | 'whatsapp' | 'telegram' | 'voice' | 'rcs'

whatsapp = EnvoiSMS generates a 6-digit code and delivers it with its own WhatsApp authentication template, nothing to store on your side. Supports domestic (Morocco) and international delivery. The code is valid for expiry seconds, capped at 600 (10 minutes, also the default). If WhatsApp refuses the submission, the code is sent by SMS instead; an SMS follow-up after a delay happens only with a Verify application (app_id) whose channel list includes sms with auto-cascade on. code_length and template are ignored in this mode. sms = classic mode: you control code length, expiry, template and sender. Both modes are confirmed with the same /verify/check call.

otp_type'copy_code' | 'one_tap' | 'zero_tap' | 'url'

WhatsApp Authentication template button type (copy_code, one_tap autofill, zero_tap, or url).

package_namestring

Android application package name for One-Tap / Zero-Tap Autofill

signature_hashstring

Android app signature hash (SMS Retriever / Autofill API)

code_lengthinteger

sms channel only — whatsapp verifications always use 6 digits

expiryinteger

Code validity in seconds, 60–1800 (default 600). On the whatsapp channel it is capped at 600, the authentication template's own limit.

app_idstring

Verify Application ID configured in dashboard or via /v1/verify/apps. Enforces channel cascade and security policies (allowed_countries geofencing). Direct /verify/send calls without an app_id are restricted to Morocco (["MA"]) by default to protect against toll fraud.

cascadestring[]

Ordered channel cascade list for validation routing (e.g. ['whatsapp', 'sms', 'voice']). ignored if app_id is set.

brandstring

Brand name shown in OTP message

templatestring

Custom OTP message. Use {{code}} and {{brand}} placeholders.

otp_button_textstring

Custom label for the WhatsApp click-to-copy OTP button

web_otp_domainstring

Target domain for W3C WebOTP browser autofill (appends @domain #code to the SMS)

app_hashstring

11-character Android SMS Retriever API application hash for automatic Android OTP detection

Example request

{
  "to": "+212612345678",
  "package_name": "ma.monapp.ecommerce",
  "signature_hash": "AbCdEf12345",
  "app_id": "vra_82fb5a71",
  "cascade": [
    "whatsapp",
    "sms"
  ],
  "brand": "MaSociété",
  "template": "Code {{brand}}: {{code}}. Ne partagez jamais ce code.",
  "otp_button_text": "Copier le code",
  "web_otp_domain": "https://monsite.ma",
  "app_hash": "vG1k6XyZ1aB"
}

Response

OTP sent

session_idstring
message_idstring

Underlying message id (sms channel only)

tostring
channelstring
expires_atstring date-time
statusstring
sandboxboolean

Present and true on env_test_ keys; nothing was delivered

sandbox_codestring

Sandbox keys only — the generated code, returned so the check endpoint can be exercised in tests. Never present on a live key.

Example response

{
  "status": "sent"
}

Changes

No recorded changes to this operation across all 1 revision of this API.