Number verification

CallQA places real calls. To make sure nobody uses it to call someone else's line, every number is verified once before runs, schedules and CI runs can call it. The proof: the line itself says a code we gave you. Only whoever controls the greeting or the agent prompt can do that.

How it works

1. You ask for a code (dashboard: Monitoring > Phone numbers, open the number, Verify ownership; API: POST /targets/{id}/verification/start). The first time, you also sign the attestation below. The response holds a 6-digit code and a sentence, shown once:

text Verification code 4 8 2 1 9 3.

1. You add the sentence to the line:

1. You let us call (POST /targets/{id}/verification/call). We dial the number, say "Verification, please." if the line waits for the caller to speak, and listen for up to 20 seconds. The call is free.

2. The number becomes verified as soon as we hear the code. Remove the sentence afterwards.

Poll GET /targets/{id}/verification (or watch the dashboard page, which updates by itself). When it did not work, the number stays pending and last_attempt tells why:

{
  "status": "pending",
  "attempts_left": 2,
  "attempts_max": 3,
  "attempts_reset_at": "2026-10-17T14:02:11Z",
  "last_attempt": {
    "status": "failed",
    "outcome": "not_answered",
    "sip_status": 480,
    "sip_reason": "Temporarily Unavailable",
    "failure_hint": "The line rang but was unavailable or did not pick up. Check that it is online and accepts international calls from a US number (+1); some carriers and call-screening features block them. Then try again."
  }
}

outcome is not_heard (the line answered, no code), not_answered, matched_too_late (the code was heard after the attempt expired), no_result, or call_not_placed (our side failed; not counted). When the line never answered, sip_status and sip_reason give the answer of its carrier. failure_hint says what to fix, in plain words: show it to the user as is (the dashboard and the MCP tool get_number_status do). POST /targets/{id}/verification/retry gives a new code: every attempt uses a fresh one.

When the verification call fails

A call that the line does not answer still counts as a failed attempt: a real call was placed to that number. attempts_left tells how many are left before the number is locked for 24 hours, and attempts_reset_at when the oldest failed attempt stops counting (each one counts for 24 hours after it ended; there is no fixed daily reset). Fix the cause before you try again.

Our verification calls come from a US number (+1). For a line outside the United States this is an international call, and some carriers, mobile plans and call-screening features reject or silence calls from unknown international numbers.

Tips:

• Call the number yourself from a phone abroad, or from a US number if you have one, to check that it answers international calls.
• Mobile lines: some carriers block international calls to prepaid or business plans by default, and Android or iOS call screening may silence unknown numbers.
• Still stuck after a fix? Contact support: we can check the call on our side, or verify the number manually (see Lines that cannot say a code).

Code behind an IVR menu

Often the first prompt of an IVR cannot be changed, but a menu option can lead to a prompt you control. Give us the keys to press: after the line answers, the verification call waits 1 second, presses them, then listens for the code.

curl -X POST https://app.callqa.dev/api/v1/targets/$TARGET_ID/verification/start \
  -H "Authorization: Bearer $CALLQA_API_KEY" -H "Content-Type: application/json" \
  -d '{"dtmf_gate": "9w1#"}'

Here the call presses 9, waits half a second, presses 1 then #. In the IVR, put a text-to-speech prompt with the sentence (Verification code 4 8 2 1 9 3.) at the end of that path: Amazon Connect, a Play prompt block after the Get customer input branch for 9 and 1; Genesys Cloud, a Play Audio task (TTS) in the menu choice; Twilio Studio, a Say/Play widget after the Gather Input on Call split.

• At most 40 characters. Spaces are ignored.
• The keys are remembered on the number: the next verification (or a renewal) presses them again unless you send another dtmf_gate ("" removes them). GET .../verification returns them as dtmf_gate.
• POST .../verification/call accepts {"dtmf_gate": "..."} too, to change the keys of the active code without a new code.
• Dashboard: Keys to press first in the verification form. MCP: the dtmf_gate argument of start_number_verification and place_verification_call.
• The security does not change: pressing keys only reaches the prompt, the line itself must still say the code, and only whoever controls the IVR can put it there.

{code} in the keys types the code itself (71**{code}#). It is meant for test lines that say back what was typed, such as CallQA's own demo lines, and is refused on your numbers (dtmf_gate_code_not_allowed): a line that reads typed digits back would prove nothing.

Verify again before the 180 days

POST /targets/{id}/verification/start with {"renew": true} issues a code for a verified number. It stays verified during the attempt; success renews the 180 days, a failure leaves it as it was (it is never locked by a renewal).

States

Limits

• A code has 6 random digits, is valid 24 hours and serves a single verification call. Only one code is active per number: asking for a new one cancels the previous one.
• 3 failed attempts per number in 24 hours, then the number is locked for 24 hours. A call the line does not answer counts as a failed attempt.
• 10 verification calls per organization in 24 hours, one at a time.
• We never store the code in clear: only a keyed hash. The call's trace masks every number the line says, and the caller only receives a hash of the code (and, for a {code} test-line gate only, the keys to type, never traced).

Sandbox (attestation signed, number not verified)

Enough to try CallQA while you change the greeting:

• 3 test calls per number in 24 hours, one at a time, 3 minutes max;
• manual runs only: scheduled and CI runs are refused (sandbox_no_batch);
• between 8 am and 9 pm local time of the number (when its time zone is unambiguous): a call outside these hours waits until 8 am instead of being refused. A second call waits for the first to end.

A refused call ends blocked_policy with an explicit block_reason (sandbox_daily_cap, sandbox_no_batch, number_not_verified, number_locked, number_suspended, attestation_outdated).

Attestation

Signed once per number, by an admin or a member (POST /targets/{id}/verification/attest, or in the attestation field of .../verification/start), with {"accept": true, "signer_name": "Jane Doe, CTO"} (the full name, at least 3 characters). The signed text, its version, the signer's name and email (or the API key prefix and who created the key), the IP address and the time are kept in the audit log.

The text is shown in full before signing, with the number and your organization filled in. In short, on behalf of your organization, the signer certifies that:

• the organization is the subscriber of the number, or holds a prior written authorization from its subscriber to have it called by automated systems using synthetic voices, for testing;
• the number is not an emergency, premium rate or special number, nor the personal line of someone who has not agreed in writing;
• the calls only test the system that answers this number (no marketing, sales or surveys);
• people who may answer or listen were informed and gave any consent the law requires (automated calls, AI voice, recording and transcription);
• the calls comply with applicable laws (for example the US TCPA, telemarketing, recording and data protection rules) and with the CallQA Terms of Service and Acceptable Use Policy;
• the organization stops calling the number and removes it if it no longer controls it.

The text is versioned. GET /targets/{id}/verification returns attestation_version (signed) and attestation_current_version. When the signed version is no longer accepted, attestation_outdated is true and test calls to the number are blocked (attestation_outdated) until someone signs the new text.

Lines that cannot say a code

• Human call center: someone calls our verification number from the line and types the code on the keypad (method inbound_dtmf). We accept it only when the carrier certifies the caller ID (SHAKEN/STIR attestation A, United States and France). Available on request.
• Recorded greeting you cannot change: contact support. We verify manually from a carrier invoice or a screenshot of your telephony console.

Roles and scopes

Admins and members verify numbers; guests only see the status. API keys need the run scope to ask for codes and place verification calls, write to sign the attestation, read to see the status.