Contactivity
Numbers and SIPMarkdown

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

  1. 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").
  2. 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.
  3. The user types the code. Your server checks it. approved means 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.

sh
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"}'
ts
const profile = await client.verifyProfiles.create({ name: "Sign-in", brand_name: "Acme", language: "en-US", lead_in: "login_code" });
python
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:

json
{
  "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:

json
{"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

sh
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"}'
ts
const v = await client.verifications.create({ to: "+14155550123", profile_id: profile.id });
python
v = client.verifications.create(to="+14155550123", profile_id=profile["id"])

201 returns the verification and places the call:

json
{
  "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.

sh
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"}'
ts
const { result } = await client.verifications.check(v.id, { code: "481293" });
if (result === "approved") markPhoneVerified(user);
python
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 +):

sh
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.

json
{
  "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):

ts
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.