The CallerAPI connector lets your AI agent act in each user's CallerAPI account. Each user connects their own CallerAPI API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 26 tools.
- Tools
- 26
- What they doRead · write · destructive
- 16 · 8 · 216 read8 write2 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the CallerAPI connection
In AgentKit > Connections, create a CallerAPI connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'callerapi'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize CallerAPI:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'callerapi_account_get',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "callerapi"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize CallerAPI:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="callerapi_account_get",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their CallerAPI credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolcallerapi_account_getGet the CallerAPI account's email and credit balance.Read-onlyGet Account Balance
Get the CallerAPI account's email and credit balance. Returns email, status, credits_left, credits_monthly and credits_spent. Use this to check remaining credits before running paid lookups such as callerapi_phone_lookup or callerapi_phone_kyc_verify.
Inputs
This tool takes no inputs.
callerapi_did_number_getGet the result of the last spam-label check for one monitored phone number.Read-onlyGet Monitored Number
Get the result of the last spam-label check for one monitored phone number. Returns phone, status, label, status_changed_at, last_checked_at and next_check_at. Use callerapi_did_numbers_list to browse all numbers. Does not run a new check or use credits.
Inputs
phonestringrequired- The monitored number in E.164 format. Example: +18883101970.
callerapi_did_numbers_listList the phone numbers (DIDs) in DID monitoring with the result of their last spam-label check, one page at a time.Read-onlyList Monitored Numbers
List the phone numbers (DIDs) in DID monitoring with the result of their last spam-label check, one page at a time. Returns numbers with phone, status (pending, clean, flagged, unknown), label, status_changed_at, last_checked_at and next_check_at, plus next_cursor for the next page. Use this to review all monitored numbers. Use callerapi_did_number_get for one number. Does not use credits.
Inputs
cursorstring- The next_cursor value from the previous page. Keep the same status and list_id for every page. Example: eyJpZCI6MTIzfQ.
limitinteger- Numbers per page. Default 50, maximum 100. Example: 50.
list_idinteger- Return only numbers in this monitoring list. Leave empty for all lists. Example: 12.
statusstring- Return only numbers with this status. Leave empty for all numbers. Example: flagged.one of
pendingcleanflaggedunknown
callerapi_did_schedule_getGet the DID monitoring check schedule and its estimated monthly credit cost.Read-onlyGet Check Schedule
Get the DID monitoring check schedule and its estimated monthly credit cost. Returns enabled, mode, interval_minutes or times, weekdays, the daily window and timezone, and a one-month credit estimate. Use this before callerapi_did_schedule_update. Returns 404 when no numbers were submitted yet. Does not use credits.
Inputs
list_idinteger- Monitoring list whose schedule to read. Leave empty for the default list. Example: 12.
callerapi_did_webhook_getGet the DID monitoring webhook URL and its delivery state.Read-onlyGet DID Webhook
Get the DID monitoring webhook URL and its delivery state. Returns url, active and, when CallerAPI turned the webhook off, a note with the reason. The signing secret is not returned. Use this to check webhook health. Use callerapi_did_webhook_save to set the URL.
Inputs
This tool takes no inputs.
callerapi_phone_lookupLook up a phone number's spam score, reputation and owner information, with an optional live HLR carrier check.Read-onlyLook Up Phone Spam Score
Look up a phone number's spam score, reputation and owner information, with an optional live HLR carrier check. Returns data with business_info (owner name and entity type), carrier_info (carrier, line type, country) and complaints (reported spam subjects and counts), plus HLR status fields when hlr is true. Use this to screen a caller or a number before calling or texting it. Use callerapi_phone_ported_date_get or callerapi_phone_porting_history_get for porting data. Each lookup uses credits.
Inputs
phonestringrequired- Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 18883578668.
hlrboolean- Set to true to also run a live HLR (Home Location Register) lookup that reports whether the number is active and reachable on its carrier. Example: true.
callerapi_phone_online_presence_getCheck which messaging and social platforms a phone number is registered on.Read-onlyGet Phone Online Presence
Check which messaging and social platforms a phone number is registered on. Returns online_presence with one flag per platform (for example whatsapp, telegram, facebook, google, office365): 1 registered, 0 not registered, -1 unknown. Use this as a fraud signal: real, long-used numbers usually have an online footprint. Costs about EUR 0.15 per lookup.
Inputs
phonestringrequired- Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 12124567890.
callerapi_phone_ported_date_getGet the date a phone number was last ported to another carrier.Read-onlyGet Phone Ported Date
Get the date a phone number was last ported to another carrier. Returns ported (whether the number was ever ported), ported_date, ported_date_type and a status message. Use this for SIM-swap and account-takeover checks. Use callerapi_phone_porting_history_get for every past port. Costs about EUR 0.008 per lookup.
Inputs
phonestringrequired- Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 18883578668.
callerapi_phone_porting_history_getGet every past porting event for a phone number.Read-onlyGet Phone Porting History
Get every past porting event for a phone number. Returns the list of dates (and carriers where known) on which the number moved between carriers. Use this when you need the full history. Use callerapi_phone_ported_date_get for only the latest port. Costs about EUR 0.02 per lookup.
Inputs
phonestringrequired- Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 18883578668.
callerapi_signer_reputation_getGet the reputation of a STIR/SHAKEN call signer by its Service Provider Code (SPC).Read-onlyGet Signer Reputation
Get the reputation of a STIR/SHAKEN call signer by its Service Provider Code (SPC). Returns spc, name, known, score, band, confidence and install counts. An unknown signer has known false and no score. Use this to judge how trustworthy a signed call's originating carrier is. Use callerapi_signer_reputations_list to rank signers.
Inputs
spcstringrequired- Service Provider Code from the TNAuthList extension of the signing certificate. Four digits for US carriers, up to 16 characters. Example: 8080.
callerapi_signer_reputations_listList STIR/SHAKEN call signers ranked by reputation score.Read-onlyList Signer Reputations
List STIR/SHAKEN call signers ranked by reputation score. Returns signers with spc, name, score, band and confidence, best first. Use this to find trusted or risky signers. Use callerapi_signer_reputation_get for one SPC.
Inputs
limitinteger- Maximum number of signers to return. Example: 50.
min_scoreinteger- Only signers with at least this score (0 to 100). Example: 80.
callerapi_voice_capabilities_getGet which Voice firewall products are on for this account and the credit prices in force.Read-onlyGet Voice Firewall Capabilities
Get which Voice firewall products are on for this account and the credit prices in force. Returns capabilities with flags such as scan, live_filter and honeypot, and prices in credits per product. Use this before scoring calls with callerapi_voice_scan. Free.
Inputs
This tool takes no inputs.
callerapi_voice_categories_listList every category a Voice firewall verdict can take, with a description of each.Read-onlyList Verdict Categories
List every category a Voice firewall verdict can take, with a description of each. Returns the category values, which match CallerAPI complaint subjects; none means a clean call. Use this to interpret verdict.category in callerapi_voice_scan and callerapi_voice_session_get results. Free.
Inputs
This tool takes no inputs.
callerapi_voice_personas_listList the personas the Voice firewall honeypot can use to answer scam calls.Read-onlyList Honeypot Personas
List the personas the Voice firewall honeypot can use to answer scam calls. Returns personas with id, name, age, gender, archetype, language and greeting. Use this to pick a persona id for a honeypot number. Free.
Inputs
This tool takes no inputs.
callerapi_voice_session_getGet one Voice firewall session with its verdict and extracted intel.Read-onlyGet Voice Session
Get one Voice firewall session with its verdict and extracted intel. Returns the session record plus verdict (category, score) and intel objects. Use this to recover a missed webhook event or answer a dispute. Get ids from callerapi_voice_sessions_list or callerapi_voice_scan. Free.
Inputs
idstringrequired- The session_id from an event, from callerapi_voice_sessions_list or from callerapi_voice_scan. Example: 7463336c-c965-450f-b188-e6908e969395.
callerapi_voice_sessions_listList recent Voice firewall sessions (live filter, honeypot and scan) for this API key, newest first.Read-onlyList Voice Sessions
List recent Voice firewall sessions (live filter, honeypot and scan) for this API key, newest first. Returns sessions with session id, type, caller and called numbers, timestamps and verdict summary. Use callerapi_voice_session_get for one session's full verdict and intel. Free.
Inputs
limitinteger- Number of sessions to return, 1 to 200. Other values become 50. Example: 50.
callerapi_bcid_verifyCheck whether a business registered with CallerAPI Business Caller ID announced this exact call, so its name and logo can be shown.WriteVerify Business Caller ID
Check whether a business registered with CallerAPI Business Caller ID announced this exact call, so its name and logo can be shown. Returns a verdict (verified, or a reason it is not) and, when verified, the identity with name and logo_id. Use this at call setup, before the phone rings. Verify is free; a verified verdict credits the telco 1 credit.
Inputs
fromstringrequired- The calling number as presented to the switch, in E.164. Example: +14155551234.
tostringrequired- The called number in E.164. The announcement is bound to it. Example: +12125556789.
assertionstring- Optional compact JWS the switch received in-band, for example in a SIP header. Do not send a publish token here. Example: eyJhbGciOiJFUzI1NiJ9.eyJmcm9tIjoiKzE0MTU1NTUxMjM0In0.c2lnbmF0dXJl.
callerapi_did_numbers_submitAdd phone numbers to DID monitoring so CallerAPI regularly checks whether carriers label them as spam.WriteAdd Numbers to Monitoring
Add phone numbers to DID monitoring so CallerAPI regularly checks whether carriers label them as spam. Returns status and data describing the submitted numbers. Use this to start monitoring your outbound caller IDs. New numbers start as pending and are checked at about 80 numbers a minute. Checks use credits per the check schedule.
Inputs
numbersarrayrequired- Phone numbers to monitor in E.164 format, at most 100,000. National numbers are accepted when default_country is set. Example: ["+18883101970", "+13058901598"]
default_countrystring- Two-letter ISO 3166 country code used for numbers without a country code. Example: US.
list_idinteger- Monitoring list to add the numbers to. Leave empty for the account's default list. Example: 12.
callerapi_did_schedule_updateChange when CallerAPI checks your monitored numbers.WriteUpdate Check Schedule
Change when CallerAPI checks your monitored numbers. Send only the fields to change; the others keep their saved values. Returns the saved schedule and a one-month credit estimate. Use mode interval with interval_minutes for a fixed interval, or mode times with 1 to 24 times of day. Use callerapi_did_schedule_get to read the current schedule.
- Idempotent
Inputs
enabledboolean- false stops scheduled checks; true starts them again. Example: true.
endstring- End of the daily check window in HH:MM. Use 24:00 for the end of the day. Example: 20:00.
interval_minutesinteger- Minutes between two check passes, used with mode interval. One of 15, 30, 60, 120, 180, 240, 360, 480, 720, 1440. Example: 360.one of
1530601201802403604807201440 list_idinteger- Monitoring list whose schedule to set. Leave empty for the default list. Example: 12.
modestring- interval checks at a fixed interval; times checks at set times of day. Example: interval.one of
intervaltimes startstring- Start of the daily check window in HH:MM. Example: 08:00.
timesarray- Times of day in HH:MM to run checks, used with mode times. 1 to 24 different times. Example: ["09:00", "17:00"]
timezonestring- IANA time zone name for times and the daily window. Example: America/New_York.
weekdaysarray- Days with checks, where 1 is Monday and 7 is Sunday. Example: [1, 2, 3, 4, 5]
callerapi_did_webhook_saveSave the URL that receives DID monitoring events (number flagged, number cleared).WriteSave DID Webhook
Save the URL that receives DID monitoring events (number flagged, number cleared). An account has one webhook URL and a new save replaces the old one. Returns status and data for the saved webhook. The URL must be https on port 443 or 8443 with a public host. Webhooks are not available on the Free plan.
- Idempotent
Inputs
urlstringrequired- An https URL on port 443 or 8443 with a public host, up to 2,048 characters. Redirects are not followed. Example: https://example.com/hooks/callerapi.
callerapi_did_webhook_secret_rotateCreate a new signing secret for the DID monitoring webhook.WriteRotate DID Webhook Secret
Create a new signing secret for the DID monitoring webhook. Returns the new secret once. For 24 hours events are signed with both the new and old secret, then only the new one. Use this when the secret may have leaked. Update your receiver within 24 hours.
Inputs
This tool takes no inputs.
callerapi_did_webhook_testSend one signed webhook.test event to the saved DID monitoring webhook URL.WriteSend DID Webhook Test
Send one signed webhook.test event to the saved DID monitoring webhook URL. Returns the HTTP status your endpoint answered with; 502 when it did not reply within 10 seconds. Use this to test your signature check after callerapi_did_webhook_save. Does not use credits.
Inputs
This tool takes no inputs.
callerapi_phone_kyc_verifyVerify a person's name, date of birth, address and email against the mobile network operator's records for their phone number.WriteVerify Phone Identity (KYC)
Verify a person's name, date of birth, address and email against the mobile network operator's records for their phone number. Returns a match score per field: 100 is a perfect match, 75-99 strong, 50-74 partial, 1-49 weak and 0 no match. Use this for lightweight identity checks during signup or payments. Costs about EUR 0.30 per lookup.
Inputs
first_namestringrequired- First name of the person to verify. Example: John.
last_namestringrequired- Last name of the person to verify. Example: Doe.
phonestringrequired- Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 13146049999.
citystring- City of the address. Example: Toronto.
countrystring- Country of the address as a two-letter code. Example: CA.
dob_daystring- Day of birth, 1 to 31. Example: 1.
dob_monthstring- Month of birth, 1 to 12. Example: 12.
dob_yearstring- Year of birth, four digits. Example: 1999.
emailstring- Email address of the person to verify. Example: john@example.com.
middle_namestring- Middle name of the person to verify. Example: Smith.
postcodestring- Postal code of the address. Example: M4B1B3.
statestring- State or province of the address. Example: Ontario.
streetstring- Street name of the person's address. Example: Omnia.
street_nostring- Street number of the address. Example: 23.
unit_nostring- Unit or apartment number of the address. Example: 11A.
callerapi_voice_scanClassify one finished call as scam or clean from its transcript or base64 audio.WriteScore Call Transcript
Classify one finished call as scam or clean from its transcript or base64 audio. Returns a session_id and a verdict with score (0 to 1), level, category, tactics, signals and summary. Send exactly one of transcript or audio_base64. With report true and from set, a score of 0.8 or more files the caller as spam. Costs 2 credits plus 1 credit per started minute of audio; the body limit is 25 MB.
Inputs
audio_base64string- Call audio encoded as base64. Send this or transcript, not both. Set encoding to match. Example: UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQAAAAA=.
encodingstring- Audio encoding for audio_base64: wav needs a RIFF header, pcm16 is 16-bit little-endian and needs sample_rate, mulaw defaults to 8000 Hz. Example: wav.one of
wavpcm16mulaw fromstring- Caller number in E.164 with a leading plus. Required for report. Example: +14155551234.
languagestring- BCP-47 language hint for transcription. Example: en-US.
reportboolean- Set to true to file the caller as spam when the score is 0.8 or more. Needs from. Example: false.
sample_rateinteger- Audio sample rate in Hz. Required for pcm16. Example: 8000.
tostring- Called number in E.164. Example: +12125556789.
transcriptstring- Text of the call. Send this or audio_base64, not both. Example: Hello, this is the IRS. You owe back taxes and must pay today with gift cards.
callerapi_did_number_removeRemove one phone number from DID monitoring.DestructiveRemove Number from Monitoring
Remove one phone number from DID monitoring. Returns a confirmation. All checks, status updates, webhook events and email alerts for the number stop, and pending webhook events for it are deleted. Use this when you retire a caller ID. Credits already used are not refunded.
- Idempotent
Inputs
phonestringrequired- The number to remove, in E.164 format. Example: +13058901598.
callerapi_did_webhook_deleteDelete the DID monitoring webhook URL and its secret.DestructiveDelete DID Webhook
Delete the DID monitoring webhook URL and its secret. Returns a confirmation. CallerAPI stops all deliveries and drops undelivered events. Use callerapi_did_webhook_save to set a new URL later.
- Idempotent
Inputs
This tool takes no inputs.
No tools match.