Building with an AI coding agent — Claude Code, Cursor, Windsurf, Copilot? Copy one of the prompts below and paste it in. Each is a self-contained brief with the exact endpoints, auth, response fields, and fail-open rules, so your agent can add a caller name and a supplementary spam-risk signal to a softphone, an Asterisk / FreePBX PBX, a chatbot, an AI voice agent, or your CRM — without you reading the whole API first.
Every prompt assumes a free numbers.online API key. It is self-service — no sales call — and shown exactly once, so save it. Paste this to have your agent walk you through it, then swap {{YOUR_API_KEY}} into any prompt below.
Help me get a numbers.online API key. numbers.online is a phone-number trust API
(caller name + a supplementary, low-confidence spam-risk signal, keyed on E.164).
Sign-up is self-service with no sales call: open https://numbers.online/docs and create a
free key. The key is shown exactly once and stored only as a hash, so save it somewhere safe.
Every endpoint works on the free tier (rate-limited). Then, in any integration prompt I give
you, replace {{YOUR_API_KEY}} with this key. For reference, the machine-readable API summary is
at https://numbers.online/llms.txt and the full OpenAPI spec is at https://numbers.online/api/spec.Pick the target that matches what you’re building. Copy the prompt, paste it into your coding agent, and follow up with anything specific about your setup.
Show the caller’s name, line type and an optional risk note the moment an inbound call rings your desktop softphone.
You are integrating numbers.online into my desktop softphone (e.g. MicroSIP) so each
inbound call shows the caller's name and an optional, supplementary spam-risk note.
About numbers.online: a phone-number trust API keyed on E.164. Given a number it returns a
caller name (CNAM) where available plus a low-confidence, supplementary spam-risk signal.
Base URL: https://numbers.online
Auth header: Authorization: Bearer {{YOUR_API_KEY}} (or X-API-Key: {{YOUR_API_KEY}}).
Get a free key at https://numbers.online/docs.
Task:
- On each incoming call, normalize the caller's number to E.164.
- Plain text (simplest): GET https://numbers.online/api/v1/cid/{number} returns the caller name
as text/plain, or the literal UNAVAILABLE when there is no name. Optional query:
?spam_tag=Spam?&spam_threshold=80&country=US. This endpoint also accepts ?key={{YOUR_API_KEY}}
for clients that cannot send headers.
- JSON (richer): GET https://numbers.online/api/v1/lookup/{e164} with the auth header. Use
formatted, line_type, carrier, cnam, and spam_score (1-99, may be null).
- Show the name + line type as the caller label; only prefix a risk word when spam_score is
above a threshold I choose.
Hard rules (do not violate):
- Treat every value as a supplementary, low-confidence signal, never as proof a call is "safe",
"spam", or lawful. A missing name means "unknown", not a negative signal.
- Fail open: a slow or failed lookup must never delay or drop the call. Fall back to the raw
number and use a short (~1s) timeout. Never hardcode the key in a committed file.
- I keep every display and answer/decline decision; do not auto-reject calls.
References: read https://numbers.online/llms.txt and the OpenAPI at
https://numbers.online/api/spec, and the guide at
https://numbers.online/docs/integrations/microsip.Label inbound calls with a caller name and an optional spam tag before they reach an extension — via CID Superfecta or the dialplan.
You are integrating numbers.online into my Asterisk / FreePBX system so inbound calls
are labeled with a caller name (CNAM) and, optionally, a supplementary spam-risk tag.
About numbers.online: a phone-number trust API keyed on E.164 — caller name plus a
low-confidence, supplementary spam-risk signal.
Base URL: https://numbers.online
Auth header: Authorization: Bearer {{YOUR_API_KEY}} (or X-API-Key). The plain-text CID
endpoint also accepts ?key={{YOUR_API_KEY}}. Free key: https://numbers.online/docs.
Task — pick the path that fits my setup:
- FreePBX: add numbers.online as a CID Superfecta source. Use the drop-in PHP module at
https://numbers.online/integrations/freepbx/source-NumbersOnline.module, enable it in the
inbound route's scheme, and set the API key + optional spam threshold in the source config.
- Plain Asterisk dialplan / AGI: on inbound, call
GET https://numbers.online/api/v1/cid/{E164}?key={{YOUR_API_KEY}} (returns the name as
text/plain, or UNAVAILABLE) and set CALLERID(name) from it. Optional
?spam_tag=Spam?&spam_threshold=80 prefixes a risk word above the threshold I choose.
Hard rules (do not violate):
- The name and risk are supplementary, low-confidence signals — never assert a call is "safe",
"spam", lawful, or unlawful. A missing name = "unknown", not negative.
- Fail open on the call path: set a sub-second HTTP timeout; a slow or failed lookup must
advance the call unchanged and never delay or drop it. Never hardcode the API key in committed
config — read it from an env var / AVP.
- My PBX keeps every routing, labeling, and blocking decision.
References: read https://numbers.online/llms.txt, the OpenAPI at https://numbers.online/api/spec,
and the guides at https://numbers.online/docs/integrations/freepbx-superfecta and
https://numbers.online/docs/integrations/asterisk-freepbx.Give a chat assistant a supplementary trust read of the contact’s number so it can handle unknown high-risk numbers and verified businesses differently.
You are integrating numbers.online into my chatbot / messaging assistant so it can
factor a supplementary trust read of the contact's phone number into how it responds (e.g. extra
caution on a high-risk unknown number, smoother handling of a verified business).
About numbers.online: a phone-number trust API keyed on E.164.
Base URL: https://numbers.online
Auth header: Authorization: Bearer {{YOUR_API_KEY}} (or X-API-Key).
Free key: https://numbers.online/docs.
Task:
- When a conversation has the contact's phone number, normalize it to E.164 and call
POST https://numbers.online/api/v1/inbound/lookup
body: { "number": "+14155551212", "context": "inbound_sms" }
- Use these PII-free response fields in the assistant's context: identity_type
(verified_business | verified_individual | unverified | unknown), display_label (e.g. a
business name; never a personal name), risk_level (low | medium | high | unknown),
recommended_action, and receipt_id.
- Phrase any caller note to the user as advisory context, not a verdict.
Hard rules (do not violate):
- Every field is a supplementary, low-confidence signal. The bot must never tell a user a number
is "safe", "a scammer", or "verified-safe", and must never make an eligibility or denial
decision solely on this signal.
- Fail open: on timeout or error, proceed with no signal rather than blocking the conversation.
- Do not store or log raw numbers. The receipt_id is bound to a specific number — treat it as
sensitive, not anonymized.
References: read https://numbers.online/llms.txt, the OpenAPI at https://numbers.online/api/spec,
and https://numbers.online/docs/integrations/ai-voice-agents-mcp.Let a voice agent look up the caller before it talks — over the MCP server or a direct inbound webhook — and adapt, fail-open within the response budget.
You are integrating numbers.online into my AI voice agent (Vapi, Retell, Pipecat, or
LiveKit) so it can look up the caller before or while it talks and adapt: who is this caller,
and is this a number to think twice about.
About numbers.online: read-only phone intelligence over the Model Context Protocol plus direct
webhooks.
Base URL: https://numbers.online
Auth: Authorization: Bearer {{YOUR_API_KEY}}.
Free key: https://numbers.online/docs.
Task — pick the path for my platform:
- MCP (Vapi / Pipecat / LiveKit): register an MCP server at
https://numbers.online/api/v1/mcp (JSON-RPC 2.0 over Streamable HTTP; in Vapi set
metadata.protocol = "shttp" and an Authorization: Bearer header). It exposes these tools, each
taking an E.164 number: phone_lookup, line_type, caller_risk, dnc_check, reassigned_check.
- Retell: point the agent's call_inbound webhook at
https://numbers.online/api/v1/integrations/retell/inbound?key={{YOUR_API_KEY}} — it injects
dynamic variables ({{caller_name}}, {{caller_risk}}, {{caller_on_dnc}}, and friends) and
always returns 200. Vapi custom-function alternative:
https://numbers.online/api/v1/integrations/vapi/tool.
- Reference the returned values in the agent prompt as labeled supplementary signals.
Hard rules (do not violate):
- Supplementary, low-confidence signals only — never have the agent state a call is "safe",
"spam", or lawful, and never auto-terminate a call solely on this.
- This is a live-call path: it must fail open and stay within the platform's response budget
(Vapi ~7.5s, Retell ~10s). A slow or failed lookup degrades to a neutral signal, never a
dropped or delayed call.
- The agent keeps every routing and dialing decision.
References: read https://numbers.online/llms.txt, the OpenAPI at https://numbers.online/api/spec,
and https://numbers.online/docs/integrations/ai-voice-agents-mcp.Enrich contact records with a supplementary trust read and scrub do-not-contact before every outbound dial — with optional spoofing defence on your own numbers.
You are integrating numbers.online into my AI-based CRM / dialer so contact records
carry a supplementary trust read, and outbound campaigns respect do-not-contact before dialing.
About numbers.online: a phone-number trust + compliance-aid API keyed on E.164.
Base URL: https://numbers.online
Auth: Authorization: Bearer {{YOUR_API_KEY}}.
Free key: https://numbers.online/docs.
Task:
- Inbound / enrichment: for a contact number call
GET https://numbers.online/api/v1/lookup/{e164} and store line_type, carrier, cnam,
spam_score and verstat on the record. Batch up to 100 numbers via
POST https://numbers.online/api/v1/lookup/batch.
- Outbound pre-call (right before you dial): POST https://numbers.online/api/v1/precall/lookup
body: { "to": "+14155551212", "from": "+442071838750" }
returns a do-not-call scrub status: SUPPRESS (do not dial), NO_MATCH, or UNKNOWN. IMPORTANT:
NO_MATCH is NOT a consent grant — it only means we hold no suppression for that number.
- Optional spoofing defence: enrol one of my own verified business numbers via
POST https://numbers.online/api/v1/precall/enroll so spoofed calls later reported against it
can be distinguished from calls I actually placed.
Hard rules (do not violate):
- Every signal is supplementary and low-confidence; the scrub is a compliance aid, not a legal
determination — my own consent / TCPA process still governs whether a call is allowed. Never
label a number "safe" or "compliant".
- Fail open on the dialing path; never let a slow lookup block a live call.
- Do not store raw numbers in logs. The receipt id is bound to a specific number — treat it as
sensitive.
References: read https://numbers.online/llms.txt, the OpenAPI at https://numbers.online/api/spec,
and the guides at https://numbers.online/docs/integrations/precall-call-provenance and
https://numbers.online/docs/integrations/fcc-evidence-bundle.These prompts get your agent moving fast, but you own the result. numbers.online returns a supplementary, low-confidence caller name and spam-risk signal — never an assertion that a call is “safe”, “spam”, lawful, or unlawful, and a missing name means “unknown”, not a negative signal. On any live-call path the integration must fail open: a slow or failing lookup should advance the call unchanged, never delay or drop it. Your system keeps every routing, labeling, and blocking decision and remains responsible for compliance. Point your agent at the machine-readable llms.txt and the authoritative OpenAPI spec for the full contract.
If you’d rather drop in a tested config than have an agent write one, the integrations page has copy-paste artifacts and step-by-step guides for FreePBX, FreeSWITCH / FusionPBX, 3CX, MicroSIP, Vapi, Retell, and the Kamailio / OpenSIPS / dSIPRouter SBC recipe. Each runs on the free tier and fails open on the call path. New to the API? Start with the API reference.