Skip to content

Moving from Twilio

Verify, step by step

Verifications and VerificationCheck become /verify/start and /verify/check. No service to set up, no per-verification fee, and a call-in channel besides SMS and voice.

  • SMS, voice and call-in
  • No per-verification fee
  • Checks are free
Fields

What maps one to one

Verification request fields
On TwilioToOn PacketExchangetoSameE.164.
On TwilioChannel (sms, call, ...)On PacketExchangechannel (sms, voice, call_in)Our waycall is called voice here, and call_in lets the user ring a number so the call itself is the proof.
On TwilioService friendly nameOn PacketExchangebrandOur waySent per request, up to 30 characters, read out or written into the message.
On TwilioService code lengthOn PacketExchangelengthOur way4 to 10 digits, 6 by default, per request.
On TwilioLocaleOn PacketExchangelanguageSameen, es, fr, de, pt and hi for voice; SMS adds ar.
On TwilioService code expiryOn PacketExchangeexpirySecondsOur way60 to 3,600 seconds, 600 by default, per request.
On TwilioVerificationCheck To + CodeOn PacketExchangeverificationId + codeOur wayKeep the verificationId from start. Five wrong codes and it is closed.
On TwilioNoneOn PacketExchangereferenceGoes furtherYour own id for the attempt, echoed on reads and webhooks; starting again with the same reference reuses a pending verification.

Endpoints

Verify endpoints
On TwilioPOST verify.twilio.com/v2/Services/{ServiceSid}/VerificationsOn PacketExchangePOST /verify/startSameChannels sms, voice and call_in (the user calls a number and the call itself verifies them).
On TwilioPOST .../Services/{ServiceSid}/VerificationCheckOn PacketExchangePOST /verify/checkOur wayChecked by verificationId and code, not by phone number and code. A wrong code is a normal 200 with status denied.
On TwilioGET .../Verifications/{Sid}On PacketExchangeGET /verify/{id}SameAlso GET /verify to list by your own reference, status or channel.
Check results

What the check tells you

Verification check outcomes
On Twiliostatus approved, valid trueOn PacketExchangestatus approvedSameThe only answer that proves the user holds the number.
On Twiliostatus pending, valid false (wrong code)On PacketExchangestatus denied, reason wrong_codeOur wayA normal 200, not an HTTP error. attemptsRemaining says how many tries are left.
On TwilioCode reused after approvalOn PacketExchangestatus denied, reason already_usedOur wayAn approved verification can never be approved twice.
On Twilioexpired or canceledOn PacketExchangestatus expiredSameAfter expirySeconds, 600 by default.
On Twiliomax_attempts_reachedOn PacketExchangestatus max_attemptsSameFive wrong codes close the verification.
What changes

Six differences worth knowing first

  • No service to create

    Twilio keeps brand, code length and expiry on a Verify Service. Here they ride on each start request as brand, length and expirySeconds, so keep them in your config.
  • Check by id, not by number

    Start returns a verificationId. Keep it with the user's session and send it with the code to /verify/check.
  • Your own reference

    Pass reference (a user or session id) and it is echoed on every read and webhook. Starting again with the same reference reuses a pending verification instead of sending a second code.
  • No fee per verification

    You pay for the SMS or the call that carries the code, at the route rate plus the capped platform fee. Checking a code is free.
  • Users can call in

    The call_in channel gives the user a number to ring from the phone being verified. The call itself is the proof, so there is no code to type.
  • Codes in six voice languages

    Voice codes are read in English, Spanish, French, German, Portuguese or Hindi, and SMS codes add Arabic, chosen per request.

Verify

You pay for the message or the call, never for the check.

Steps

Moving it over

  1. Step 1

    Create a key

    A live key limited to verify:write, and a test key, both on the main account.
  2. Step 2

    Move the service settings into config

    Brand (up to 30 characters), code length (4 to 10), language and expiry become values your app sends with each start.
  3. Step 3

    Swap start

    Replace verifications.create with POST /verify/start. Map channel call to voice. Save the verificationId.
  4. Step 4

    Swap check

    Replace verificationChecks.create with POST /verify/check and the saved id. Treat only approved as success.
  5. Step 5

    Optionally, listen for approvals

    Subscribe to verification.approved and verification.expired, which matter most for call-in, where approval happens on our side.
  6. Step 6

    Test, then share live traffic

    Run sign-in and sign-up on the test key, then send a share of live codes per country before moving the rest.
Code

Send and check, before and after

Before, on Twilio

twilio: send and check a code
import twilio from 'twilio';

const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const service = client.verify.v2.services(process.env.TWILIO_VERIFY_SERVICE_SID);

// 1. Send the code.
await service.verifications.create({ to: '+447700900123', channel: 'sms' });

// 2. Later, check what the user typed.
const check = await service.verificationChecks.create({ to: '+447700900123', code: '123456' });
console.log(check.status); // "approved" when correct

After, on PacketExchange

packetexchange: send and check a code
import { randomUUID } from 'node:crypto';

const API = 'https://packetexchange.io/api/v1';

// One JSON request with your API key as a Bearer token.
async function px(method, path, body, headers = {}) {
  const res = await fetch(API + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.PACKETEXCHANGE_API_KEY}`,
      'Content-Type': 'application/json',
      ...headers,
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${json.error?.code}: ${json.error?.message}`);
  return json.data;
}

// 1. Send the code. No service to create: brand and options ride on the request.
const v = await px('POST', '/verify/start', {
  to: '+447700900123',
  channel: 'sms',            // or 'voice', or 'call_in'
  brand: 'Acme',
  reference: 'user-8812',    // your own id, echoed back on reads and webhooks
});
// Keep v.verificationId with the user's session.

// 2. Later, check what the user typed. A wrong code is a 200 with status "denied".
const check = await px('POST', '/verify/check', { verificationId: v.verificationId, code: '123456' });
console.log(check.status); // "approved" when correct

Keep verificationId from start; check sends it with the code.

Call-in

Verification with no code to type

Useful where SMS is slow or filtered. Available for numbers in the coverage list; see the Verify product page for the full flow.
call_in, start to approval
# 1. Which numbers can call in, and the number they ring.
curl "https://packetexchange.io/api/v1/verify/call-in/coverage" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

# 2. Start: the reply holds the number to show the user.
curl https://packetexchange.io/api/v1/verify/start \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+447700900123", "channel": "call_in", "reference": "user-8812" }'

# 3. The user rings it from that phone; verification.approved fires.
#    Or poll GET /verify/{id} until status is approved.
Testing

Prove it before live traffic

  1. Step 1

    Test keys show the code

    On a test key the start reply includes the code as testCode, so automated tests can complete the check. A live key never returns it.
  2. Step 2

    Simulate a call-in

    On a test key, POST /verify/{id}/simulate-call approves a call-in verification as if the user had rung.
  3. Step 3

    Try every failure

    A wrong code, an expired verification, five wrong codes and a reused code each return their own status and reason. Make sure your UI says the right thing for each.
Gotchas

Things that catch people out

  • A wrong code is not an error

    It is a 200 with status: denied. Code that waited for a 4xx to mean "wrong code" will treat every attempt as success unless it reads the status.
  • Bring your own code

    If you generate codes yourself, POST /comms/voice-otp reads your code to a phone and hangs up, without Verify holding it.
  • Start limits

    Starts are limited per number, per number range and per account to stop traffic pumping. A paused start says why in the error.
Questions

Verify, answered

Do I need to create a Verify Service first?
No. The brand, code length, language and expiry are sent with each start request, so there is nothing to set up before the first code.
What does a verification cost?
The SMS or call that carries the code, at the route rate plus the platform fee of 2% capped at $0.001. There is no per-verification fee and checks are free.
How does call-in work?
You start with channel call_in and show the user the number in the reply. They ring it from the phone you are verifying, and the call itself approves the verification. GET /verify/call-in/coverage lists where it works.
Can I choose the route the code goes on?
Yes. Pass strategy (cheapest, best_quality or balanced), or route: "direct" for our own routes at a fixed published price.

Start with a test key

Open a free account, create a test key and run your existing flows against the real path without sending anything. Move live traffic when it matches.

Twilio is a trademark of Twilio Inc. PacketExchange is not affiliated with or endorsed by Twilio.