Fraud Alert Verification Agent

Call customers automatically when a transaction is flagged, walk through a verification flow, and escalate to a human or block the card if verification fails.

DifficultyAdvanced

TrackDeveloper Track

ChannelsVoice (Outbound)

IntegrationsTransaction monitoring system (API)Customer contact databaseEscalation email

What you'll build

An agent that receives a flagged transaction from your transaction monitoring system, places an outbound call to the customer, walks through a structured verification flow, and — depending on the outcome — marks the transaction safe or escalates to a human fraud analyst and instructs the customer to block their card. This pattern is in production at PrimoAI's banking demo, where it handles hundreds of outbound fraud calls per day with no human in the loop for verified transactions.

Prerequisites

BimpeAI account with an API key (sk_…)
Read Anatomy of a workflow agent first — this recipe skips steps covered there
A transaction monitoring system and customer contact database connected in the Console dashboard (see Step 4)
An outbound voice phone number configured in the Console dashboard (see Step 4)
Escalation email configured in Settings → Escalation in the Console dashboard

Steps

1. Find the workflow

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

const page = await bimpe.workflows.list({ scope: "public", search: "fraud verification" });
const workflow = page.data[0];
console.log(workflow.id, workflow.name);

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

page = client.workflows.list(scope="public", search="fraud verification")
workflow = page.data[0]
print(workflow.id, workflow.name)

2. Create the agent

const agent = await bimpe.agents.create(
  {
    name: "Fraud alert verification agent",
    system_prompt:
      "You are a fraud alert agent for a bank. When a transaction is flagged, you call the " +
      "cardholder to verify it. Introduce yourself, state the flagged transaction amount and " +
      "merchant, and ask the customer to confirm or deny. If they confirm, log it as verified. " +
      "If they deny or cannot be reached, instruct them to block their card immediately via " +
      "their banking app and inform them that a fraud analyst will contact them within the hour. " +
      "Never share full card numbers. Never approve a disputed transaction without verification.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-fraud-alert-agent-v1" },
);

console.log(agent.id);

agent = client.agents.create(
    name="Fraud alert verification agent",
    system_prompt=(
        "You are a fraud alert agent for a bank. When a transaction is flagged, you call the "
        "cardholder to verify it. Introduce yourself, state the flagged transaction amount and "
        "merchant, and ask the customer to confirm or deny. If they confirm, log it as verified. "
        "If they deny or cannot be reached, instruct them to block their card immediately via "
        "their banking app and inform them that a fraud analyst will contact them within the hour. "
        "Never share full card numbers. Never approve a disputed transaction without verification."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-fraud-alert-agent-v1",
)

print(agent.id)

3. Add knowledge bases

The fraud response policy gives the agent consistent verification questions and block instructions regardless of the transaction type.

// Fraud response policy
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Fraud response policy",
  content:
    "A transaction is flagged when it exceeds 3× the customer's 30-day average spend, " +
    "originates from a new country, or matches a known fraud merchant pattern.\n" +
    "Verification questions to ask in order:\n" +
    "1. Did you make a purchase of [amount] at [merchant] on [date]?\n" +
    "2. Were you in [location] at that time?\n" +
    "3. Is your card still in your possession?\n" +
    "If the customer says no to question 1 or 2, or yes to losing the card:\n" +
    "- Advise them to block the card immediately in their banking app.\n" +
    "- Tell them a fraud analyst will call back within 60 minutes.\n" +
    "- Do not attempt to block the card yourself — this is handled by the card management team.",
});

// Block instructions
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Card block instructions",
  content:
    "To block a card via banking app: open the app → Cards → select the card → Freeze card.\n" +
    "To block via telephone banking: call the number on the back of the card.\n" +
    "A temporary freeze stops new transactions but does not cancel the card.\n" +
    "A permanent block requires a replacement card to be issued (5–7 business days).",
});

# Fraud response policy
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Fraud response policy",
    "content": (
        "A transaction is flagged when it exceeds 3× the customer's 30-day average spend, "
        "originates from a new country, or matches a known fraud merchant pattern.\n"
        "Verification questions to ask in order:\n"
        "1. Did you make a purchase of [amount] at [merchant] on [date]?\n"
        "2. Were you in [location] at that time?\n"
        "3. Is your card still in your possession?\n"
        "If the customer says no to question 1 or 2, or yes to losing the card:\n"
        "- Advise them to block the card immediately in their banking app.\n"
        "- Tell them a fraud analyst will call back within 60 minutes.\n"
        "- Do not attempt to block the card yourself — this is handled by the card management team."
    ),
})

# Block instructions
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Card block instructions",
    "content": (
        "To block a card via banking app: open the app → Cards → select the card → Freeze card.\n"
        "To block via telephone banking: call the number on the back of the card.\n"
        "A temporary freeze stops new transactions but does not cancel the card.\n"
        "A permanent block requires a replacement card to be issued (5–7 business days)."
    ),
})

4. Connect channels and integrations (dashboard)

Outbound voice and integrations are configured in the dashboard

The API cannot create channel connections or integrations. There is no voice value in the SDK channel filter — outbound calls are initiated from the dashboard or a connected telephony trigger that you configure in the Console. The SDK cannot initiate calls. The transaction monitoring system, customer contact database, and escalation email are all connected in the Console dashboard. Escalation email is set under Settings → Escalation.

Open Console dashboard → Agents → select your agent.
Under Channels, configure an outbound voice phone number. The dashboard handles carrier connection and call routing.
Under Integrations, connect your transaction monitoring system. The agent uses it to receive flagged transaction details at call time.
Under Integrations, connect your customer contact database so the agent can look up the customer's phone number from a transaction ID.
Under Settings → Escalation, set the escalation email address for the fraud analyst team.

5. Verify and go live

const integrations = await bimpe.agents.integrations.list(agent.id);
console.log("Integrations:", integrations.map((i) => i.name));

integrations = client.agents.integrations.list(agent.id)
print("Integrations:", [i.name for i in integrations])

Both integrations must appear before enabling the agent for live fraud alerts. A missing transaction monitoring connection means the agent will have no transaction context when the call connects.

Full example

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

// 1. Find workflow
const page = await bimpe.workflows.list({ scope: "public", search: "fraud verification" });
const workflow = page.data[0];

// 2. Create agent
const agent = await bimpe.agents.create(
  {
    name: "Fraud alert verification agent",
    system_prompt:
      "You are a fraud alert agent for a bank. Call the cardholder to verify a flagged " +
      "transaction. If they deny the transaction, instruct them to block their card and tell " +
      "them a fraud analyst will follow up within 60 minutes.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-fraud-alert-agent-v1" },
);

// 3. Add knowledge bases
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Fraud response policy",
  content:
    "Verification questions:\n" +
    "1. Did you make a purchase of [amount] at [merchant] on [date]?\n" +
    "2. Were you in [location] at that time?\n" +
    "3. Is your card still in your possession?\n" +
    "If denied: advise card block and escalate to fraud analyst.",
});

await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Card block instructions",
  content:
    "Block via banking app: Cards → select card → Freeze card.\n" +
    "Block via telephone banking: call the number on the back of the card.",
});

// 4. Verify integrations (transaction monitoring + contact DB must be connected in dashboard)
const integrations = await bimpe.agents.integrations.list(agent.id);
console.log("Agent ID:", agent.id);
console.log("Integrations:", integrations.map((i) => i.name));

// Outbound calls are triggered from the dashboard or a telephony webhook — the SDK cannot initiate calls.
// Once a call completes, the conversation is available via conversations.list.
const conversations = await bimpe.conversations.list(agent.id);
console.log("Recent conversations:", conversations.data.length);

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

# 1. Find workflow
page = client.workflows.list(scope="public", search="fraud verification")
workflow = page.data[0]

# 2. Create agent
agent = client.agents.create(
    name="Fraud alert verification agent",
    system_prompt=(
        "You are a fraud alert agent for a bank. Call the cardholder to verify a flagged "
        "transaction. If they deny the transaction, instruct them to block their card and tell "
        "them a fraud analyst will follow up within 60 minutes."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-fraud-alert-agent-v1",
)

# 3. Add knowledge bases
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Fraud response policy",
    "content": (
        "Verification questions:\n"
        "1. Did you make a purchase of [amount] at [merchant] on [date]?\n"
        "2. Were you in [location] at that time?\n"
        "3. Is your card still in your possession?\n"
        "If denied: advise card block and escalate to fraud analyst."
    ),
})

client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Card block instructions",
    "content": (
        "Block via banking app: Cards → select card → Freeze card.\n"
        "Block via telephone banking: call the number on the back of the card."
    ),
})

# 4. Verify integrations (transaction monitoring + contact DB must be connected in dashboard)
integrations = client.agents.integrations.list(agent.id)
print("Agent ID:", agent.id)
print("Integrations:", [i.name for i in integrations])

# Outbound calls are triggered from the dashboard or a telephony webhook — the SDK cannot initiate calls.
# Once a call completes, the conversation is available via conversations.list.
conversations = client.conversations.list(agent.id)
print("Recent conversations:", len(conversations.data))

Deploy

Store your API key in BIMPEAI_API_KEY. Confirm that both integrations appear in integrations.list before enabling live alerts — a missing transaction monitoring connection means the agent calls with no context. Update the fraud response policy knowledge base via knowledgeBases.update when new fraud patterns emerge, without recreating the agent. Set the escalation email under Settings → Escalation in the dashboard before go-live.

Variations

Add a third knowledge base entry listing high-risk merchant categories so the agent can provide more specific context during the call.
Update the system_prompt to include the customer's preferred language using agents.update — the agent will conduct the verification call in that language.
Send a follow-up WhatsApp message after the call via conversations.messages.send with a summary of the outcome and next steps.

Fraud Alert Verification Agent

On this page