canonical: https://jentic.com/apis/callerapi.com/callerapi # CallerAPI Jentic publishes the only available OpenAPI specification for CallerAPI, keeping it validated and agent-ready. CallerAPI delivers phone number intelligence - spam score, HLR (Home Location Register) carrier data, KYC and identity verification, ported date and porting history, and online presence signals derived from messaging and social platforms. It also exposes a webhook subscription system for daily spam reports, plus upload endpoints for submitting your own spam reports and contacts to enrich the shared dataset. Authentication is an x-api-key header on every request, and the 14 operations are grouped under Lookup, Reports, Upload, and Account. ## For AI agents Score a phone number for spam, retrieve carrier and HLR data, run KYC checks, and subscribe to daily spam reports through CallerAPI. ## Scope Does not handle outbound call placement, SMS sending, or call recording - use for phone number intelligence, KYC, and spam reporting only. ## Capabilities - Score a phone number for spam likelihood and retrieve HLR carrier data via /api/v1/spam-score - Run KYC and identity verification checks on a phone number via /api/v1/kyc - Look up a number's last ported date and full porting history - Check online presence across messaging and social platforms with /api/v1/online-presence - Subscribe and unsubscribe webhooks to receive daily spam reports - Upload spam reports or contact lists to enrich the CallerAPI dataset - Track remaining credits on the account through /api/v1/account/balance ## Use cases ### Spam Score and Carrier Validation Before initiating outbound calls or SMS, query /api/v1/spam-score to get both a spam likelihood and the underlying HLR carrier record for the destination number. This tells the agent whether the number is live, which carrier hosts it, and whether it has been reported as spam - a single call replaces separate lookups against carrier and reputation services. Example prompt: GET /api/v1/spam-score with the phone number and route the call only when the spam score is below the configured threshold. ### Phone-Based KYC and Identity Verification For lightweight identity verification flows, call /api/v1/kyc with the phone number to retrieve associated identity signals such as ported date, porting history, and online presence. This is much cheaper than document-based KYC and is well-suited to first-line fraud screening before escalating high-risk users to a full document verification provider. Example prompt: GET /api/v1/kyc with the phone number and pass through to a document KYC provider only when the identity score falls below threshold. ### Daily Spam Report Webhook Subscribe to daily spam reports by POSTing to /api/v1/webhooks/subscribe and receive batches of newly reported numbers at the configured URL. Use /api/v1/webhooks/test to verify reachability and /api/v1/webhooks/dispatch to manually trigger a redelivery during incident response. The reports feed your block lists without polling. Example prompt: POST a webhook subscription to /api/v1/webhooks/subscribe with the receiver URL, then call /api/v1/webhooks/test to confirm the endpoint is reachable. ### Bulk Contact Enrichment Upload a batch of contacts to /api/v1/upload/contacts to enrich them in one request rather than calling spam-score for each number. The same Upload tag also exposes /api/v1/upload/spam-reports for sending your own user-reported spam back into the shared dataset, which both improves the global signal and ensures your reports are reflected in future scores. Example prompt: POST a CSV of contacts to /api/v1/upload/contacts and write the returned enriched rows back to the contact database. ### AI Agent Phone Intelligence via Jentic Through Jentic, an AI agent searches for an intent like 'check the spam score of a phone number' and is returned the CallerAPI spam-score operation along with its input schema. The agent calls the operation without ever holding the raw x-api-key value, and can chain into KYC, ported-date, or online-presence checks based on the spam score response. Setup time is under an hour rather than several days of direct integration. Example prompt: Use Jentic search for 'check the spam score of a phone number', load the /api/v1/spam-score schema, and execute it with the inbound phone number. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /api/v1/spam-score | Get spam score and HLR data for a number | | GET | /api/v1/kyc | Run a phone-based KYC check | | GET | /api/v1/ported-date | Get the last ported date of a number | | GET | /api/v1/porting-history | Retrieve full porting history | | GET | /api/v1/online-presence | Check messaging and social online presence | | POST | /api/v1/webhooks/subscribe | Subscribe to daily spam report webhooks | | POST | /api/v1/upload/contacts | Upload contacts for batch enrichment | | GET | /api/v1/account/balance | Check remaining account credits | ## Key resources - **Lookup** — Spam score with HLR data, KYC, ported date, porting history, and online presence lookups. - **Reports** — Daily spam report retrieval and webhook subscription management. - **Upload** — Batch upload of spam reports and contact enrichment lists. - **Account** — Account balance and credit tracking. ## Why Jentic - **Setup:** Wiring CallerAPI by hand means managing its x-api-key header, tracking your account balance, and handling webhook subscription signing yourself. Through Jentic you install once, import CallerAPI from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** CallerAPI takes the phone number as a query parameter rather than a resource in the URL path, so scope the agent to the operations it needs, such as spam-score and kyc lookups. You choose the operations it may call, so write operations like contact upload or webhook subscription are not included unless you add them. - **Credential handling:** Your CallerAPI x-api-key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'check the spam score of a phone number' or 'run a KYC lookup', and Jentic returns the matching CallerAPI operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Call Control API** — Call Control returns a block-or-allow decision against a community blacklist while CallerAPI returns a richer reputation, HLR, KYC, and presence payload. - **CallFire API** — CallFire sends voice and SMS while CallerAPI screens and enriches the destination numbers - combine for cleaner outbound campaigns. - **C-Me API** — C-Me runs full document and biometric KYC; CallerAPI is the lighter phone-based first pass. ## FAQ ### Why is there no official OpenAPI spec for CallerAPI? CallerAPI publishes API documentation at docs.callerapi.com but does not host a downloadable OpenAPI specification on a developer portal. Jentic generates and maintains this spec so that AI agents and developers can call CallerAPI via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does CallerAPI use? CallerAPI uses an API key passed in the x-api-key HTTP header on every request. Through Jentic, the key is stored encrypted in the credential vault and injected at execution time, so the agent never holds the raw value. ### Can I get HLR carrier data for a phone number with CallerAPI? Yes. The /api/v1/spam-score endpoint returns the spam score together with HLR (Home Location Register) carrier data and basic line type information in a single response, so a number lookup does not need to be split across two calls. ### What are the rate limits for CallerAPI? Rate limits are not declared in the OpenAPI specification. CallerAPI uses a credit-based model - call /api/v1/account/balance to check remaining credits before scheduling large batches of lookups, since each lookup type consumes a different credit cost. ### How do I subscribe to daily spam reports through Jentic? Run a Jentic search for 'subscribe to daily spam reports', load the /api/v1/webhooks/subscribe schema, and execute it with the receiver URL. Then load and execute the /api/v1/webhooks/test schema to verify the receiver is reachable. Install the SDK with pip install jentic and use the async search, load, and execute pattern. ### Is CallerAPI free? CallerAPI prices lookups per credit rather than offering a free tier, and different lookup types consume different credit amounts. Pricing is set by CallerAPI and is not declared in the OpenAPI spec - refer to docs.callerapi.com for the current per-lookup cost. ### Can I limit what my agent is allowed to do with the CallerAPI? Yes. Because you run Jentic One yourself, your own rules decide which CallerAPI operations and credentials the agent can use, so you can restrict it to read-only lookups such as spam-score, kyc, ported-date, and online-presence. Write operations like contact upload and webhook subscription are excluded unless you explicitly grant them. The x-api-key is held only by your own instance and injected at execution time, so the agent never sees the raw value.