Caller check

A tool your agent calls during a conversation to ask about the person on the line. The answer is written for the model: a one-line summary it can act on, with the fields behind it. Part of Guard.

Check the caller

POST/v1/tools/caller-checkany key

One URL for a Vapi function tool, a Retell custom function, or anything that can POST JSON. It reads the caller and your number from the platform's own request, so the tool needs no arguments. A call already on record is answered from the score it got when it rang; anything else is scored as a dry run, like a score. Nothing is blocked or recorded.

Query parameters

detail"score" | "verdict" | "count" | "all": How much to say. all by default. Can also be the tool's detail argument.
windownumber: Minutes to count this caller's calls over, for count and all. 60 by default, at most 1440. Can also be the tool's window_min argument.

Request body

callerstring: The other party, E.164. Only when you call it yourself: Vapi and Retell requests carry it already.
numberstring: Your own number on the call, E.164. Same.
direction"inbound" | "outbound": Inbound by default.
call_idstring: Your id for the call, if it is on record, so it is answered from its own score.

Response

summarystring: One line for the model: how risky, why, what to do, and how often this number has called.
risk"low" | "medium" | "high": With verdict or all.
advicestring: What the agent should do about it. With verdict or all.
scorenumber: 0 to 100. With score or all.
calls_recentnumber: This caller's calls to this number in the last window_min minutes. With count or all.
window_minnumber: The window that count covers.
whystring[]: What drove it, in words. With all.

Errors

guard_only402: The caller check is part of Guard.
invalid_caller400: No caller number on the request.
invalid_number400: No number of yours on the request.
invalid_detail400: detail is not one of the four.
unauthorized401: Missing or unknown key.

Asked by a Vapi or Retell tool, the reply is always a 200 so the agent keeps going: an error comes back as a summary that says to carry on normally, with error beside it. From Vapi, the same object arrives as the result of your tool call.

RequestShell

BASE=https://api.murusai.com

curl -X POST "$BASE/v1/tools/caller-check" \
  -H "Authorization: Bearer $MURUSAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caller": "+15125550142",
    "number": "+14155550100"
  }'

RequestNode

const BASE = "https://api.murusai.com";
const KEY = process.env.MURUSAI_KEY;

const url = new URL("/v1/tools/caller-check", BASE);
const res = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "caller": "+15125550142",
    "number": "+14155550100"
  }),
});
const data = await res.json();

RequestPython

import os, requests

BASE = "https://api.murusai.com"
KEY = os.environ["MURUSAI_KEY"]

r = requests.post(
    f"{BASE}/v1/tools/caller-check",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "caller": "+15125550142",
        "number": "+14155550100",
    },
)
data = r.json()

200OKResponseJSON

{
  "summary": "High risk: it's one of a block of numbers calling together; it's calling other businesses right now. Don't book, transfer or take payment; wrap up politely and end the call. Calls from this number in the last 60 minutes: 6.",
  "score": 92,
  "risk": "high",
  "advice": "Don't book, transfer or take payment; wrap up politely and end the call.",
  "calls_recent": 6,
  "window_min": 60,
  "why": [
    "it's one of a block of numbers calling together",
    "it's calling other businesses right now"
  ]
}

On Vapi

In Vapi, create a Bearer Token credential holding your Murusai API key. Then create a function tool named check_caller, point its server at the URL above with that credential, and add the tool to your assistant. Or through their API:

Vapi toolJSON

{
  "type": "function",
  "function": {
    "name": "check_caller",
    "description": "Checks whether the caller is likely spam, a bot or part of a call flood. Call it at the start of every call, and before booking, transferring or taking payment. Follow the advice it returns.",
    "parameters": { "type": "object", "properties": {} }
  },
  "server": {
    "url": "https://api.murusai.com/v1/tools/caller-check",
    "credentialId": "your Bearer Token credential's id"
  }
}

On Retell

In your Retell agent, add a custom function named check_caller with the same description. Method POST, URL as above, and a header Authorization set to Bearer followed by your Murusai API key. Leave the parameters empty, and leave "Payload: args only" off: the check reads the caller from the call Retell sends with it.

Telling the agent to use it

A line in the agent's instructions is enough:

Prompt

At the start of every call, and before booking, transferring or taking payment, call check_caller.
If it says the risk is high, follow its advice.

The check is advice, not a block. Your agent decides what to do with it. To stop callers before your agent ever answers, see how scoring works and Guard's hang-up.