> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to CallerAPI

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.

**Authentication:** API Key
**Categories:** Communication, CRM & Sales
**Tools:** 26: 16 read, 8 write, 2 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=CALLERAPI)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the CallerAPI connection

   In **AgentKit > Connections**, create a CallerAPI connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   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.actions

   const connector = 'callerapi'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { 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 call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'callerapi_account_get',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_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.actions

   connection_name = "callerapi"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_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 call
   result = actions.execute_tool(
       tool_input={},
       tool_name="callerapi_account_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their CallerAPI credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'callerapi_account_get',
  toolInput: {},
  connector: 'callerapi',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="callerapi_account_get",
    tool_input={},
    connection_name="callerapi",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `callerapi_account_get`

Get Account Balance · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `callerapi_did_number_get`

Get Monitored Number · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `phone` (`string`, required): The monitored number in E.164 format. Example: +18883101970.

Example input: `{"phone":"<phone>"}`

### `callerapi_did_numbers_list`

List Monitored Numbers · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cursor` (`string`, optional): The next_cursor value from the previous page. Keep the same status and list_id for every page. Example: eyJpZCI6MTIzfQ.
- `limit` (`integer`, optional): Numbers per page. Default 50, maximum 100. Example: 50.
- `list_id` (`integer`, optional): Return only numbers in this monitoring list. Leave empty for all lists. Example: 12.
- `status` (`string`, optional): Return only numbers with this status. Leave empty for all numbers. Example: flagged. One of: `pending`, `clean`, `flagged`, `unknown`.

Example input: `{}`

### `callerapi_did_schedule_get`

Get Check Schedule · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `list_id` (`integer`, optional): Monitoring list whose schedule to read. Leave empty for the default list. Example: 12.

Example input: `{}`

### `callerapi_did_webhook_get`

Get DID Webhook · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `callerapi_phone_lookup`

Look Up Phone Spam Score · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `phone` (`string`, required): Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 18883578668.
- `hlr` (`boolean`, optional): 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.

Example input: `{"phone":"<phone>"}`

### `callerapi_phone_online_presence_get`

Get Phone Online Presence · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `phone` (`string`, required): Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 12124567890.

Example input: `{"phone":"<phone>"}`

### `callerapi_phone_ported_date_get`

Get Phone Ported Date · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `phone` (`string`, required): Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 18883578668.

Example input: `{"phone":"<phone>"}`

### `callerapi_phone_porting_history_get`

Get Phone Porting History · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `phone` (`string`, required): Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 18883578668.

Example input: `{"phone":"<phone>"}`

### `callerapi_signer_reputation_get`

Get Signer Reputation · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `spc` (`string`, required): Service Provider Code from the TNAuthList extension of the signing certificate. Four digits for US carriers, up to 16 characters. Example: 8080.

Example input: `{"spc":"<spc>"}`

### `callerapi_signer_reputations_list`

List Signer Reputations · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of signers to return. Example: 50.
- `min_score` (`integer`, optional): Only signers with at least this score (0 to 100). Example: 80.

Example input: `{}`

### `callerapi_voice_capabilities_get`

Get Voice Firewall Capabilities · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `callerapi_voice_categories_list`

List Verdict Categories · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `callerapi_voice_personas_list`

List Honeypot Personas · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `callerapi_voice_session_get`

Get Voice Session · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The session_id from an event, from callerapi_voice_sessions_list or from callerapi_voice_scan. Example: 7463336c-c965-450f-b188-e6908e969395.

Example input: `{"id":"<id>"}`

### `callerapi_voice_sessions_list`

List Voice Sessions · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Number of sessions to return, 1 to 200. Other values become 50. Example: 50.

Example input: `{}`

### `callerapi_bcid_verify`

Verify Business Caller ID · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): The calling number as presented to the switch, in E.164. Example: +14155551234.
- `to` (`string`, required): The called number in E.164. The announcement is bound to it. Example: +12125556789.
- `assertion` (`string`, optional): 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.

Example input: `{"from":"<from>","to":"<to>"}`

### `callerapi_did_numbers_submit`

Add Numbers to Monitoring · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `numbers` (`array`, required): 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_country` (`string`, optional): Two-letter ISO 3166 country code used for numbers without a country code. Example: US.
- `list_id` (`integer`, optional): Monitoring list to add the numbers to. Leave empty for the account's default list. Example: 12.

Example input: `{"numbers":["+18883101970","+13058901598"]}`

### `callerapi_did_schedule_update`

Update Check Schedule · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `enabled` (`boolean`, optional): false stops scheduled checks; true starts them again. Example: true.
- `end` (`string`, optional): End of the daily check window in HH:MM. Use 24:00 for the end of the day. Example: 20:00.
- `interval_minutes` (`integer`, optional): 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: `15`, `30`, `60`, `120`, `180`, `240`, `360`, `480`, `720`, `1440`.
- `list_id` (`integer`, optional): Monitoring list whose schedule to set. Leave empty for the default list. Example: 12.
- `mode` (`string`, optional): interval checks at a fixed interval; times checks at set times of day. Example: interval. One of: `interval`, `times`.
- `start` (`string`, optional): Start of the daily check window in HH:MM. Example: 08:00.
- `times` (`array`, optional): Times of day in HH:MM to run checks, used with mode times. 1 to 24 different times. Example: ["09:00", "17:00"]
- `timezone` (`string`, optional): IANA time zone name for times and the daily window. Example: America/New_York.
- `weekdays` (`array`, optional): Days with checks, where 1 is Monday and 7 is Sunday. Example: [1, 2, 3, 4, 5]

Example input: `{}`

### `callerapi_did_webhook_save`

Save DID Webhook · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `url` (`string`, required): 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.

Example input: `{"url":"<url>"}`

### `callerapi_did_webhook_secret_rotate`

Rotate DID Webhook Secret · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs: none.

Example input: `{}`

### `callerapi_did_webhook_test`

Send DID Webhook Test · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs: none.

Example input: `{}`

### `callerapi_phone_kyc_verify`

Verify Phone Identity (KYC) · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `first_name` (`string`, required): First name of the person to verify. Example: John.
- `last_name` (`string`, required): Last name of the person to verify. Example: Doe.
- `phone` (`string`, required): Phone number to look up, digits only with the country code first and no plus sign or spaces. Example: 13146049999.
- `city` (`string`, optional): City of the address. Example: Toronto.
- `country` (`string`, optional): Country of the address as a two-letter code. Example: CA.
- `dob_day` (`string`, optional): Day of birth, 1 to 31. Example: 1.
- `dob_month` (`string`, optional): Month of birth, 1 to 12. Example: 12.
- `dob_year` (`string`, optional): Year of birth, four digits. Example: 1999.
- `email` (`string`, optional): Email address of the person to verify. Example: john@example.com.
- `middle_name` (`string`, optional): Middle name of the person to verify. Example: Smith.
- `postcode` (`string`, optional): Postal code of the address. Example: M4B1B3.
- `state` (`string`, optional): State or province of the address. Example: Ontario.
- `street` (`string`, optional): Street name of the person's address. Example: Omnia.
- `street_no` (`string`, optional): Street number of the address. Example: 23.
- `unit_no` (`string`, optional): Unit or apartment number of the address. Example: 11A.

Example input: `{"first_name":"<first_name>","last_name":"<last_name>","phone":"<phone>"}`

### `callerapi_voice_scan`

Score Call Transcript · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `audio_base64` (`string`, optional): Call audio encoded as base64. Send this or transcript, not both. Set encoding to match. Example: UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQAAAAA=.
- `encoding` (`string`, optional): 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: `wav`, `pcm16`, `mulaw`.
- `from` (`string`, optional): Caller number in E.164 with a leading plus. Required for report. Example: +14155551234.
- `language` (`string`, optional): BCP-47 language hint for transcription. Example: en-US.
- `report` (`boolean`, optional): Set to true to file the caller as spam when the score is 0.8 or more. Needs from. Example: false.
- `sample_rate` (`integer`, optional): Audio sample rate in Hz. Required for pcm16. Example: 8000.
- `to` (`string`, optional): Called number in E.164. Example: +12125556789.
- `transcript` (`string`, optional): 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.

Example input: `{}`

### `callerapi_did_number_remove`

Remove Number from Monitoring · Destructive

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.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `phone` (`string`, required): The number to remove, in E.164 format. Example: +13058901598.

Example input: `{"phone":"<phone>"}`

### `callerapi_did_webhook_delete`

Delete DID Webhook · Destructive

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.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

## Related

Other Communication connectors ([all 132](/agentkit/connectors/?category=communication)):

- [Gmail](/agentkit/connectors/gmail/): Scalekit connector, OAuth, 48 tools
- [Slack](/agentkit/connectors/slack/): Scalekit connector, OAuth, 96 tools
- [Google Calendar](/agentkit/connectors/googlecalendar/): Scalekit connector, OAuth, 30 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
