Verify (voice OTP)
Check that a user owns a phone number. Your app asks Contactivity to verify the number; we call it and speak a
one-time code. The user types the code into your app, and your app sends it to us to check. Paths are relative to
https://api.contactivity.io/v1/projects/{project_id}; see the overview.
The code is never returned by the API. It is not in any response, webhook, event or log you can read. We never store the code itself, only a random seed and a keyed hash that are useless without a secret key on our side; both are deleted when the verification ends. Your servers never see the code, so it cannot leak from them. Codes are always generated by Contactivity; you cannot choose one.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| POST | /verify/profiles |
verify:write |
Create a profile |
| GET | /verify/profiles |
verify:read |
List profiles (paged) |
| GET | /verify/profiles/{profile_id} |
verify:read |
Get a profile |
| PATCH | /verify/profiles/{profile_id} |
verify:write |
Update, pause or resume a profile |
| DELETE | /verify/profiles/{profile_id} |
verify:write |
Archive a profile |
| GET | /verify/countries |
verify:read |
Countries a profile may allow |
| GET | /verify/phrases |
verify:read |
Call languages and phrase presets |
| POST | /verifications |
verify:write |
Start a verification (places the call), or resend the code |
| GET | /verifications |
verify:read |
List verifications (paged) |
| GET | /verifications/{verification_id} |
verify:read |
Get a verification |
| POST | /verifications/{verification_id}/check |
verify:write |
Check a code |
| POST | /verifications/by-number/{e164}/check |
verify:write |
Check a code by phone number |
| POST | /verifications/{verification_id}/cancel |
verify:write |
Cancel a verification |
How it works
- Create a profile once. It holds the settings of a group of verifications (one per app or flow, for example "Sign-in" and "Password reset").
- When a user enters a phone number, start a verification. We call the number from one of our managed Verify numbers and say "This is Acme. Your verification code is 4, 8, 1, 2, 9, 3." in the profile's language. The digits are spoken slowly, the code is repeated, and the user can press 1 to hear it again. If voicemail answers, the code plays after the beep.
- The user types the code. Your server checks it.
approvedmeans the user owns the number.
A verification is pending until it is approved, expires, runs out of attempts, is canceled, or its call cannot be
placed (failed). Once it ends, its code no longer works.
Create a profile
Only name is required.
curl -X POST https://api.contactivity.io/v1/projects/$PROJECT_ID/verify/profiles \
-H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "Sign-in", "brand_name": "Acme", "language": "en-US", "lead_in": "login_code"}'const profile = await client.verifyProfiles.create({ name: "Sign-in", brand_name: "Acme", language: "en-US", lead_in: "login_code" });profile = client.verify_profiles.create(name="Sign-in", brand_name="Acme", language="en-US", lead_in="login_code")| Field | Default | Description |
|---|---|---|
name |
1-100 characters. Required on create | |
brand_name |
null |
Your brand, spoken in the intro ("This is Acme."): 1-30 letters, spaces or . & ' -. Digits are not allowed, so no number can be read out |
language |
en-US |
The language of the call. See Languages |
intro |
this_is with a brand_name, else none |
Spoken first. A preset other than none needs brand_name. See Phrases |
lead_in |
verification_code |
Spoken before the code |
outro |
none |
Spoken after the code |
code_length |
6 |
Digits in the code, 4-10 |
expiry_secs |
600 |
How long a code works, 60-3600 seconds |
repeat_count |
2 |
Times the code is spoken in one call, 1-5 |
max_attempts |
5 |
Checks allowed per verification, 1-10 |
allowed_countries |
["US", "CA"] |
ISO 3166-1 alpha-2 codes. Only countries listed by GET /verify/countries |
machine_detection |
true |
Detect voicemail and play the code after the beep. Each detection run is charged |
auto_pause |
false |
Pause the profile when its approval rate collapses (see Fraud protection) |
The response is the profile with id (vp_…), the fields above, brand_audio, paused, paused_at,
pause_reason, created_at, updated_at and archived_at.
PATCH changes only the fields you send. {"brand_name": null} clears the brand and sets intro to none unless
you send intro too. {"paused": true} pauses the profile (new verifications get 409 profile_paused) and
{"paused": false} resumes it. DELETE archives the profile, cancels its pending verifications and returns the
archived profile (200). A change to an archived profile is 409 archived.
Caller ID. Every Verify call comes from one of our managed Verify numbers, chosen by us and signed with A
attestation. You cannot set the caller ID. The verification's from shows the number used.
Brand audio. After a create, or a change of brand_name, language or intro, we prepare the intro with your
brand in the profile's language. brand_audio is pending until it is ready (none without an intro). Calls never
wait for it: until it is ready, an English profile hears the intro in a fallback voice and other languages skip the
intro.
Languages
The call is spoken by our built-in voice. GET /verify/phrases lists the languages.
language |
Name |
|---|---|
en-US |
English (US) |
es-ES |
Spanish (Spain) |
fr-FR |
French (France) |
de-DE |
German |
it-IT |
Italian |
Phrases
What the call says is chosen from fixed presets, never free text, so a profile cannot be used to read out a scam
script. {brand} is the profile's brand_name. "Again" and "Press 1 to hear the code again" are always spoken.
| Field | Preset | English |
|---|---|---|
intro |
none |
(nothing) |
intro |
this_is |
This is {brand}. |
intro |
hello_from |
Hello from {brand}. |
intro |
security_check |
{brand} security check. |
lead_in |
verification_code |
Your verification code is |
lead_in |
one_time_passcode |
Your one-time passcode is |
lead_in |
login_code |
Your login code is |
lead_in |
security_code |
Your security code is |
outro |
none |
(nothing) |
outro |
do_not_share |
Do not share this code with anyone. |
outro |
ignore_if_not_requested |
If you did not request this code, you can ignore this call. |
GET /verify/phrases?language=es-ES returns the languages and each preset's English text and localized text:
{
"language": "es-ES",
"languages": [{"code": "en-US", "name": "English (US)"}, {"code": "es-ES", "name": "Spanish (Spain)"}, …],
"intro": [{"id": "none", "text": null, "localized": null},
{"id": "this_is", "text": "This is {brand}.", "localized": "Este es un mensaje de {brand}."}, …],
"lead_in": [{"id": "verification_code", "text": "Your verification code is", "localized": "Su código de verificación es"}, …],
"outro": [{"id": "none", "text": null, "localized": null}, …]
}Countries
GET /verify/countries lists the countries a profile may allow, sorted by name:
{"data": [{"code": "CA", "name": "Canada", "dial_code": "+1"}, {"code": "US", "name": "United States", "dial_code": "+1"}]}The US and Canada are always listed. Other countries are listed only while international calling is enabled for them
in the project (tier 3 and an approved international request). Saving a country that is not listed is
400 invalid_parameter (param allowed_countries).
Start a verification
curl -X POST https://api.contactivity.io/v1/projects/$PROJECT_ID/verifications \
-H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: signup-7f3a9c21" \
-d '{"to": "+14155550123", "profile_id": "vp_us1_6c1f0a9e3b7d2c8f4a5e1b90"}'const v = await client.verifications.create({ to: "+14155550123", profile_id: profile.id });v = client.verifications.create(to="+14155550123", profile_id=profile["id"])201 returns the verification and places the call:
{
"id": "ve_us1_3b7d2c8f4a5e1b906c1f0a9e",
"profile_id": "vp_us1_6c1f0a9e3b7d2c8f4a5e1b90",
"to": "+14155550123",
"from": "+12125550188",
"status": "pending",
"attempts": 0,
"sends": 1,
"call_status": "queued",
"answered_by": null,
"call_id": "CA5f2b8c1e9a4d4e7b8c3f6a1d2e9b7c40",
"call_ids": ["CA5f2b8c1e9a4d4e7b8c3f6a1d2e9b7c40"],
"test": false,
"fee": null,
"call_price": null,
"machine_detection_price": null,
"price": {"amount": "0.0000", "currency": "USD"},
"last_sent_at": "2026-10-27T14:05:00.210Z",
"expires_at": "2026-10-27T14:15:00.210Z",
"created_at": "2026-10-27T14:05:00.210Z",
"approved_at": null,
"ended_at": null
}Keep the id with the user's session. call_status follows the latest call: queued, answered, machine
(voicemail), completed, busy, no_answer, failed or canceled. price is the sum of fee, call_price and
machine_detection_price.
Resend. To send the code again ("Call me again"), make the same request. While a verification of the same profile
and number is pending, it calls again with the same code and returns 200 with the same id. Resends are allowed
every 30 seconds (429 resend_cooldown, with Retry-After) and 5 sends in all (429 max_sends). Each call is billed.
Destinations. The number's country must be in the profile's allowed_countries (US and Canada by default), else
403 destination_not_allowed. If international calling is later turned off for a listed country, its sends get
403 international_not_enabled. Premium-rate destinations are blocked. Sandbox
projects can verify only their verified numbers (Numbers) and the
test numbers.
Check the code
Send the digits the user typed from your server. Each check of a pending verification counts one attempt.
curl -X POST https://api.contactivity.io/v1/projects/$PROJECT_ID/verifications/$VERIFICATION_ID/check \
-H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
-d '{"code": "481293"}'const { result } = await client.verifications.check(v.id, { code: "481293" });
if (result === "approved") markPhoneVerified(user);r = client.verifications.check(v["id"], code="481293")
if r["result"] == "approved":
mark_phone_verified(user)The response is {"result": …, "verification": {…}}:
result |
Meaning | Verification |
|---|---|---|
approved |
The code matches | Ends approved; the Verify fee is charged once |
rejected |
Wrong code | Stays pending; the user can try again |
max_attempts |
Wrong code, no attempts left | Ends max_attempts |
expired |
Past expires_at |
Ends expired |
Checking again after expired or max_attempts returns the same result. A verification that is approved,
canceled or failed is 409 verification_ended.
By number. If your app does not keep the verification id, check by the number instead (URL-encode the +):
curl -X POST https://api.contactivity.io/v1/projects/$PROJECT_ID/verifications/by-number/%2B14155550123/check \
-H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
-d '{"code": "481293"}'It checks the pending verification of that number (404 not_found when none is pending). When several profiles have
one pending for the number, send profile_id too (else 409 ambiguous).
Cancel. POST /verifications/{verification_id}/cancel ends a pending verification; its code stops working and no
Verify fee is charged. A call already in progress is not hung up.
GET /verifications lists verifications, newest first, with filters profile_id, to, status, created_after
and created_before (RFC 3339), plus limit and starting_after.
Webhooks
Verify sends four events to the project's webhook endpoint (Events and webhooks), in the native
envelope and signed like every webhook. Subscribe to them with event_types, or leave event_types empty for all
types.
| Event | When | Extra data fields |
|---|---|---|
verification.call.answered |
A person or voicemail answered the call | call_id, answered_by (human or a machine result such as machine_end_beep) |
verification.call.failed |
The call was not answered | call_id, reason: busy, no_answer, canceled or failed |
verification.approved |
A check matched the code | attempts, fee |
verification.expired |
The code expired before it was approved |
Every event's data also has verification_id, profile_id and to. No event carries the code.
{
"id": "evt_us1_9a4d4e7b8c3f6a1d2e9b7c40",
"type": "verification.approved",
"created_at": "2026-10-27T14:05:41.877Z",
"project_id": "6a1f…",
"data": {
"verification_id": "ve_us1_3b7d2c8f4a5e1b906c1f0a9e",
"profile_id": "vp_us1_6c1f0a9e3b7d2c8f4a5e1b90",
"to": "+14155550123",
"attempts": 1,
"fee": {"amount": "0.0300", "currency": "USD"}
}
}A handler that offers a resend when the call fails (Express):
import express from "express";
import { Contactivity, verifyStandardWebhook } from "@contactivity/sdk";
const client = new Contactivity();
const { public_key } = await client.project.webhookPublicKey();
const app = express();
app.post("/contactivity-events", express.raw({ type: "application/json" }), (req, res) => {
if (!verifyStandardWebhook(public_key, req.headers, req.body)) return res.sendStatus(401);
const event = JSON.parse(req.body.toString());
switch (event.type) {
case "verification.call.failed":
notifyUser(event.data.verification_id, `We could not reach you (${event.data.reason}). Try again?`);
break;
case "verification.expired":
notifyUser(event.data.verification_id, "Your code expired. Request a new one.");
break;
}
res.sendStatus(204);
});Answer with a 2xx within a few seconds. Do not use verification.approved alone to log the user in: the check
response your server receives is the answer.
Sandbox test numbers
In a sandbox project (account tier 1), these numbers place no call. The code is the first code_length digits of
1234567890 (123456 for 6 digits), the call result is simulated, and an approved test verification has no fee.
| Number | Simulated result |
|---|---|
+15005550006 |
Answered: call_status answered, verification.call.answered |
+15005550007 |
Voicemail: call_status machine, verification.call.answered |
+15005550001 |
Busy: call_status busy, verification.call.failed with reason busy |
+15005550002 |
No answer: call_status no_answer, verification.call.failed with reason no_answer |
Test verifications have test: true and behave like real ones otherwise: checks, attempts, expiry, resends and
events. A live project gets 400 invalid_parameter (param to) for any +1500555 number, and it is never dialed,
so a known code can never pass a live phone check.
Rate limits
| Limit | Value |
|---|---|
| Calls to one number | 5 per hour |
| Calls to one destination prefix (+1 and the area code) | 30 per hour |
| Verification calls per project | 60 per minute |
| Resend of a pending verification | Every 30 seconds, 5 sends in all |
| Ringing | 30 seconds |
Over a limit, the API answers 429 with Retry-After (seconds). Test numbers do not count towards the call limits.
Fraud protection
Every minute, we look at each profile's last hour. When at least 20 verifications ended and fewer than 20% were
approved, your team is notified, at most once an hour. A collapsed approval rate usually means someone is pumping
traffic to expensive numbers through your sign-up form. With auto_pause: true the profile is also paused, with a
pause_reason; resume it with PATCH {"paused": false} once you have found the cause.
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_parameter |
A field is out of range or not a preset, a country is not available, to is not E.164, profile_id is not a profile of the project, a test number in a live project, or code is not 1-20 digits |
| 400 | unknown_parameter, invalid_json |
The body has an unknown field or is not a JSON object |
| 402 | insufficient_balance |
Not enough balance to place the call |
| 403 | destination_blocked |
The number is in a blocked (for example premium-rate) range |
| 403 | destination_not_allowed |
The number's country is not in the profile's allowed_countries |
| 403 | international_not_enabled |
A number outside the US and Canada, and international calling is not enabled for it |
| 403 | sandbox_unverified_destination |
A sandbox project calling a number that is not one of its verified numbers |
| 403 | account_inactive, email_unverified |
The account cannot place calls yet |
| 404 | not_found |
No such profile or verification, or no pending verification for the number |
| 409 | archived |
The profile is archived |
| 409 | profile_paused |
The profile is paused |
| 409 | verification_pending |
A verification of this number is being started; retry |
| 409 | verification_ended |
Check or cancel of a verification that already ended |
| 409 | ambiguous |
Check by number with several profiles pending for it; send profile_id |
| 429 | resend_cooldown, max_sends, rate_limit |
See Rate limits |
| 503 | no_caller_id_available |
No managed Verify number is free right now; retry later |
| 503 | service_unavailable |
Verify is unavailable; retry later |
Every POST takes an Idempotency-Key header, so a retried request never places a second call
(overview).
Pricing
Verify charges a fee of $0.03 for each approved verification. Every call is also billed at the programmable voice rate
(Billing), and voicemail detection is charged per run when machine_detection is on.
Failed, expired and canceled verifications pay no Verify fee, but their calls are billed. Test numbers cost nothing.
Current prices are on the pricing page and in
GET https://api.contactivity.io/v1/public/pricing (features.verify.price_per_success). Each verification's
fee, call_price, machine_detection_price and price show what it cost.

