Customer identity verification & OTP

Overview

Verification is two calls. verify-identity matches the details the customer gives and sends a six-digit code; verify-otp checks the code and returns a session_token. Every account endpoint then requires that session. The same contract applies whether the endpoints are yours (Account Connect) or provided by Silux Chat on top of a connector.

The full sequence

 ┌──────────────┐  name + postcode/email/mobile   ┌────────────────────┐
 │  UNVERIFIED  │ ───────────────────────────────►│  verify-identity   │
 └──────────────┘                                 └─────────┬──────────┘
        ▲   success:false (no detail on WHY)                │ success:true
        │◄──────────────────────────────────────────────────┤ otp_token (10 min)
        │                                                   ▼
        │                                         ┌────────────────────┐
        │   5 wrong codes / token expired         │   CODE SENT        │
        │◄─────────────────────────────────────── │   verify-otp       │◄─┐ wrong code
        │                                         └─────────┬──────────┘  │ (tries < 5)
        │                                                   │ correct ────┘
        │                                                   ▼
        │                                         ┌────────────────────┐
        │   session expires (30 min) → 401        │     VERIFIED       │
        └──────────────────────────────────────── │  session_token     │
                                                  └────────────────────┘
                                   account-summary · orders · invoices · bookings · subscriptions · tickets

1. 1
   The customer asks something personal. The bot asks for their full name and one more detail.
2. 2
   The bot sends verify-identity. On a match, a code goes to contact details already on the account and an otp_token comes back.
3. 3
   The bot tells the customer where the code went (“a text to the mobile ending 123”) and asks for it.
4. 4
   The bot sends verify-otp with the token and the code. On success it receives a session_token.
5. 5
   Account tools are unlocked for that conversation until the session expires.

Step 1: verify-identity

curl -s -X POST "https://www.siluxchat.com/api/account-connect-demo/v1/verify-identity" \
  -H "X-API-Key: demo-account-connect-key" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Test Customer","postcode":"TE5 7ST"}'

{
  "success": true,
  "otp_token": "eyJrIjoib3RwIiwiYyI6IkMxMDAxIiwiZXhwIjoxNzkwNDE2NTg2LjI4NDIyNDN9.443c18a766f3c03f371e3da90a269fdf",
  "message": "Code sent to mobile ending 000"
}

{
  "success": false,
  "message": "We could not match those details to an account."
}

A “no” is HTTP 200 with "success": false. Reserve 401 for a missing or wrong API key. The message is shown to the customer in substance, so keep it short and neutral.

Matching rules

Account Connect

Your system decides, but the specification is: the full name must match, and at least one of postcode, email or mobile must match the same account. Normalise before comparing — lower-case, remove spaces.

Connectors

• The customer is looked up in your vendor system by email, and otherwise by mobile. A postcode alone cannot find an account, so on a connector the bot asks for an email address or mobile number.
• The surname (last word of the name) must match the record exactly, and the first name must either match or start with the same letter — so “Jan Smith” or “Janey Smith” match Jane Smith. Single-letter words are ignored, so a bare initial (“J Smith”) is not enough.
• Then one more detail must agree with the same record: postcode, email or mobile.
• Mobile numbers are compared on their last 10 digits, so 07700900123 and +447700900123 are the same number.
• If the vendor cannot be reached or refuses the credentials, the reply is {"success": false, "system_error": true, "message": "We can't check accounts right now — our team has been told."}. The bot never tells a customer “no account found” when the truth is that it could not look.

Connectors with no customer search

Some vendors (Cal.com, Google Calendar, Etsy, eBay, AfterShip, ShipStation, Printful, Workiz) have no way to search customers, but their bookings or orders name the customer. For these, the customer’s own records are the proof:

• The bot needs the full name and the email address the customer used; a mobile number is not accepted here. Without a valid email the reply is {"success": false, "needs": ["full_name", "email"], …}.
• Their orders or bookings are looked up by that email. A record must name exactly that email and a name that passes the same surname-and-first-name rule above.
• The code is then emailed to that address — never texted, and never sent to a number typed in the chat.
• Once verified, only records that name the customer’s email are shown; a record that does not say whose it is, is not shown.
• A wrong name and a wrong email get the same reply, so the answer never reveals which detail was wrong.

Connectors that hold neither (carriers, Trello, Asana, Twilio and similar) cannot verify customers. verify-identity on them replies {"success": false, "not_supported": true, "message": "<Name> can't be used to check who you are — …"}. Carriers still answer parcel tracking by tracking number without verification — see Orders, delivery tracking & returns.

Where the code is sent

The code always goes to contact details already held on the account. The chat never chooses the destination, so knowing someone’s name and postcode is not enough to read their code.

<Your business name> verification code: 482913. It expires in 10 minutes. Never share it.

Step 2: verify-otp

# export OTP=<otp_token from verify-identity>
: "${OTP:?export OTP first}"
curl -s -X POST "https://www.siluxchat.com/api/account-connect-demo/v1/verify-otp" \
  -H "X-API-Key: demo-account-connect-key" \
  -H "Content-Type: application/json" \
  -d "{\"otp_token\":\"$OTP\",\"otp_code\":\"123456\"}"

{
  "success": true,
  "session_token": "eyJrIjoic2Vzc2lvbiIsImMiOiJDMTAwMiIsImV4cCI6MTc5MDQxODAxMC45MTg4OTY3fQ.9c2f16ac077d2df711c89a5bc412537c"
}

Time and attempt limits

A used code is destroyed on success, so the same code can never open a second session. Store only a hash of each code on your side, as the reference implementations do.

Using the session

Send the session_token in the JSON body of every account call. It identifies the verified customer; the bot never sends a customer ID of its own choosing, so it cannot ask for anyone else’s data.

# export SESSION=<session_token from verify-otp>
: "${SESSION:?export SESSION first}"
curl -s -X POST "https://www.siluxchat.com/api/account-connect-demo/v1/account-summary" \
  -H "X-API-Key: demo-account-connect-key" \
  -H "Content-Type: application/json" \
  -d "{\"session_token\":\"$SESSION\"}"

{"detail": {"success": false, "message": "Session expired — please verify again."}}

Continue with Account lookups.

The test customer

So the dashboard can test the chain without texting anyone, every implementation recognises one fictional customer:

• Account Connect: your code must accept the test customer, issue an otp_token without sending anything, accept 123456 and return a little sample data.
• Connectors: Silux Chat intercepts the test customer, proves the credentials with a real read-only call to your vendor using a made-up customer, and replies "Test customer — no code is sent; use 123456". Account calls in a test session read no customer data and return "test": true.

Why this is safe

• Possession, not knowledge. Names, postcodes and emails leak; the code proves the person controls the phone or inbox on the account.
• Enforced in code. The bot’s account tools will not run without a session, whatever it is told in the chat.
• No enumeration. Identical messages for every mismatch, plus attempt limits, stop guessing.
• Short-lived. Ten-minute codes and thirty-minute sessions limit the value of anything intercepted.
• Honest failures. An unreachable system produces “can’t check right now”, never a false “no account”.

More in Security & data protection.

Get help

If genuine customers are being rejected, or codes are not arriving, email support@siluxcall.co.uk with the time of the attempt and your connection name — never the customer’s code.