Verify

Verify phone numbers

Send a one-time code by SMS or voice call, then check what the person typed. Pulsr generates the code, enforces expiry and attempt limits, and never shows you the code itself.

How it works

01Once: create an application (the rules) and a message template (the text).
02Each time: send a code to a number. You get a pinId.
03Then: send the code the person typed with that pinId. Pulsr answers verified: true or says why not.

1. Create an application

POST/2fa/2/applications

An application holds the security rules for one use case, such as sign-in or a payment confirmation. Every setting has a default, so only change what you need.

configuration

pinAttemptsinteger: Wrong codes allowed before the code is blocked. Default 10.
pinTimeToLivestring: How long a code stays valid, like 10m or 1h. Default 15m.
allowMultiplePinVerificationsboolean: Whether one code can be verified more than once. Default true; set false for sign-in.
verifyPinLimitstring: Verification attempts per time window, like 2/4s. Default 1/3s.
sendPinPerPhoneNumberLimitstring: Codes sent to one number per window. Default 3/1d. Your main protection against SMS pumping.
sendPinPerApplicationLimitstring: Codes sent by the whole application per window. Default 10000/1d.

2. Create a message template

POST/2fa/2/applications/{appId}/messages

The template sets the code format and the text. messageText must contain {{pin}}; you can add your own placeholders like {{firstName}} and fill them when sending. pinType is NUMERIC, ALPHA, HEX or ALPHANUMERIC.

setup-verify.ts

// Run once, then store both IDs in your configconst app = await pulsr("POST", "/2fa/2/applications", {  name: "YourApp sign-in",  enabled: true,  configuration: {    pinAttempts: 5,    allowMultiplePinVerifications: false,    pinTimeToLive: "10m",    verifyPinLimit: "2/4s",    sendPinPerApplicationLimit: "5000/12h",    sendPinPerPhoneNumberLimit: "3/1d",  },});const appPath = `/2fa/2/applications/${app.applicationId}`;const template = await pulsr("POST", `${appPath}/messages`, {  pinType: "NUMERIC",  pinLength: 6,  messageText: "Your YourApp code is {{pin}}. It expires in 10 minutes.",  senderId: "YourApp",});console.log(app.applicationId, template.messageId);

3. Send a code

POST/2fa/2/pin

send-code.ts

import { pulsr } from "./client";const pin = await pulsr("POST", "/2fa/2/pin", {  applicationId: process.env.PULSR_2FA_APP_ID,  messageId: process.env.PULSR_2FA_MESSAGE_ID,  from: "YourApp",  to: "33639981234",});// Keep pinId on the server, tied to the sign-in attempt.// Never send it to the browser.await session.set("pinId", pin.pinId);

Response · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "to": "33639981234",  "ncStatus": "NC_DESTINATION_REACHABLE",  "smsStatus": "MESSAGE_SENT"}

smsStatus is MESSAGE_SENT or MESSAGE_NOT_SENT. To read the code out in a phone call instead, send the same body to POST /2fa/2/pin/voice; the template’s language sets the voice.

4. Check the code

POST/2fa/2/pin/{pinId}/verify

check-code.ts

const pinId = await session.get("pinId");const result = await pulsr("POST", `/2fa/2/pin/${pinId}/verify`, {  pin: codeTypedByUser,});if (result.verified) {  // The person owns this number} else if (result.pinError !== "WRONG_PIN" || result.attemptsRemaining === 0) {  // Offer to send a new code} else {  // WRONG_PIN: let them try again}

Response · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "msisdn": "33639981234",  "verified": true,  "attemptsRemaining": 0}

pinError	Meaning
`WRONG_PIN`	The code does not match. `attemptsRemaining` says how many tries are left.
`TTL_EXPIRED`	The code is too old. Send a new one.
`NO_MORE_PIN_ATTEMPTS`	Too many wrong codes. Send a new one.

Resend a code

POST/2fa/2/pin/{pinId}/resend

Resending keeps the same pinId and counts towards the per-number limit. Offer it after 30 seconds or so, and offer a voice call as a second option.

resend-code.ts

const pinId = await session.get("pinId");// Same pinId, a new code by SMS...await pulsr("POST", `/2fa/2/pin/${pinId}/resend`, {});// ...or read out by a voice call, for landlines and people who cannot read SMSawait pulsr("POST", `/2fa/2/pin/${pinId}/resend/voice`, {});

Good practices

Keep `pinId` server-side, attached to the session or sign-in attempt. The browser only ever sends the code.
Rate-limit your own endpoint by IP and account, on top of Pulsr’s per-number limits, to stop SMS pumping fraud.
Say where the code goes. Show the number with most digits masked, and let people correct it.
Use one application per use case, so a sign-in code can never confirm a payment.

1. Create an application

POST/2fa/2/applications

An application holds the security rules for one use case, such as sign-in or a payment confirmation. Every setting has a default, so only change what you need.

configuration

pinAttemptsinteger: Wrong codes allowed before the code is blocked. Default 10.
pinTimeToLivestring: How long a code stays valid, like 10m or 1h. Default 15m.
allowMultiplePinVerificationsboolean: Whether one code can be verified more than once. Default true; set false for sign-in.
verifyPinLimitstring: Verification attempts per time window, like 2/4s. Default 1/3s.
sendPinPerPhoneNumberLimitstring: Codes sent to one number per window. Default 3/1d. Your main protection against SMS pumping.
sendPinPerApplicationLimitstring: Codes sent by the whole application per window. Default 10000/1d.

2. Create a message template

POST/2fa/2/applications/{appId}/messages

setup-verify.ts

// Run once, then store both IDs in your configconst app = await pulsr("POST", "/2fa/2/applications", {  name: "YourApp sign-in",  enabled: true,  configuration: {    pinAttempts: 5,    allowMultiplePinVerifications: false,    pinTimeToLive: "10m",    verifyPinLimit: "2/4s",    sendPinPerApplicationLimit: "5000/12h",    sendPinPerPhoneNumberLimit: "3/1d",  },});const appPath = `/2fa/2/applications/${app.applicationId}`;const template = await pulsr("POST", `${appPath}/messages`, {  pinType: "NUMERIC",  pinLength: 6,  messageText: "Your YourApp code is {{pin}}. It expires in 10 minutes.",  senderId: "YourApp",});console.log(app.applicationId, template.messageId);

3. Send a code

POST/2fa/2/pin

send-code.ts

import { pulsr } from "./client";const pin = await pulsr("POST", "/2fa/2/pin", {  applicationId: process.env.PULSR_2FA_APP_ID,  messageId: process.env.PULSR_2FA_MESSAGE_ID,  from: "YourApp",  to: "33639981234",});// Keep pinId on the server, tied to the sign-in attempt.// Never send it to the browser.await session.set("pinId", pin.pinId);

Response · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "to": "33639981234",  "ncStatus": "NC_DESTINATION_REACHABLE",  "smsStatus": "MESSAGE_SENT"}

smsStatus is MESSAGE_SENT or MESSAGE_NOT_SENT. To read the code out in a phone call instead, send the same body to POST /2fa/2/pin/voice; the template’s language sets the voice.

4. Check the code

POST/2fa/2/pin/{pinId}/verify

check-code.ts

const pinId = await session.get("pinId");const result = await pulsr("POST", `/2fa/2/pin/${pinId}/verify`, {  pin: codeTypedByUser,});if (result.verified) {  // The person owns this number} else if (result.pinError !== "WRONG_PIN" || result.attemptsRemaining === 0) {  // Offer to send a new code} else {  // WRONG_PIN: let them try again}

Response · 200 OK

{  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",  "msisdn": "33639981234",  "verified": true,  "attemptsRemaining": 0}

pinError	Meaning
`WRONG_PIN`	The code does not match. `attemptsRemaining` says how many tries are left.
`TTL_EXPIRED`	The code is too old. Send a new one.
`NO_MORE_PIN_ATTEMPTS`	Too many wrong codes. Send a new one.

Resend a code

POST/2fa/2/pin/{pinId}/resend

Resending keeps the same pinId and counts towards the per-number limit. Offer it after 30 seconds or so, and offer a voice call as a second option.

resend-code.ts

const pinId = await session.get("pinId");// Same pinId, a new code by SMS...await pulsr("POST", `/2fa/2/pin/${pinId}/resend`, {});// ...or read out by a voice call, for landlines and people who cannot read SMSawait pulsr("POST", `/2fa/2/pin/${pinId}/resend/voice`, {});

Good practices

Keep `pinId` server-side, attached to the session or sign-in attempt. The browser only ever sends the code.
Rate-limit your own endpoint by IP and account, on top of Pulsr’s per-number limits, to stop SMS pumping fraud.
Say where the code goes. Show the number with most digits masked, and let people correct it.
Use one application per use case, so a sign-in code can never confirm a payment.