Build on your AI voice agent.

Start here

Overview

The REENG API connects your bank's own systems to your AI voice agent. Everything a call produces arrives as a ticket, ranked by priority, with a response deadline. Your systems can read and update tickets, receive events the moment they happen, keep the agent's knowledge up to date, and ask the agent to call a customer back.

With your connector, the agent can also verify a caller against your own records and answer about their own account, such as whether a transfer went through, or block their card after they say yes. You decide who is verified and exactly what the agent may say. REENG keeps none of your answers.

Five minutes

Quick start

1. Create a key. In the dashboard, open API & Webhooks and press Create key. Copy it straight away: it's shown once.
2. List your open tickets, most urgent first.

curl https://api.reeng-ai.dev/v1/tickets?status=open \
  -H "Authorization: Bearer rk_live_..."

3. Add a webhook on the same page, so new tickets reach you during the call instead of on your next poll. Then press Send a test.

Keys and tokens

Authentication

Send your API key as a bearer token on every request. Each key belongs to one bank and sees only its tickets, calls and files.

Authorization: Bearer rk_live_9xQ2...

• One key per system, named for what uses it, so you can revoke one without the others. Up to 10 at a time.
• Shown once. REENG keeps only a hash. If a key is lost, revoke it and create another.
• IP allowlists. Limit a key to your servers' addresses or ranges (up to 20). From anywhere else it's refused with 403.

OAuth 2.0 client credentials

If your security team prefers short-lived tokens, exchange a key for a token that lasts an hour. Your client_id is shown next to the key in the dashboard.

curl -X POST https://api.reeng-ai.dev/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials", "client_id": "key_14", "client_secret": "rk_live_9xQ2..."}'

{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 3600 }

Use the token exactly like a key: Authorization: Bearer eyJhbGciOi.... It stops working when it expires or when its key is revoked.

How requests behave

Conventions

Idempotency

Send an Idempotency-Key header with any update or callback request. Repeating the same key within 24 hours returns the first result instead of doing it twice, so a retry after a timeout is always safe.

Idempotency-Key: 4f1c2a7e-ticket-1042-close

Paging

List tickets with order=updated to page through everything that changed, newest first. Each response carries a next_cursor; pass it back as cursor until it's null.

curl "https://api.reeng-ai.dev/v1/tickets?status=all&order=updated&limit=100&cursor=MjAyNi0xMS0xMFQwOToxNDowMyswMDowMHwxMDQy" \
  -H "Authorization: Bearer rk_live_..."

Core resource

Tickets

A ticket is everything one call produced that your team has to act on: the caller, what they asked for, its priority, its status and its deadline. A call that produced several requests (a message and a branch appointment, say) is one ticket with several requests.

{
  "id": 1042,
  "status": "new",
  "priority": "urgent",
  "priority_label": "P1 Critical",
  "created_at": "2026-11-10T09:14:03+00:00",
  "updated_at": "2026-11-10T09:14:03+00:00",
  "caller": { "name": "Musa Ibrahim", "phone": "+2348095551002", "email": null, "address": null },
  "requests": [
    {
      "id": 1042, "type": "callback", "label": "Callback", "priority": "urgent",
      "item": null, "quantity": 1, "total": 0, "currency": null,
      "details": "Three card debits overnight in Lagos he didn't make. Card blocked by USSD."
    }
  ],
  "team_note": null,
  "assigned_to": null,
  "due_at": "2026-11-10T09:29:03+00:00",
  "overdue": false,
  "call": { "id": 88213, "summary": "Caller reported unauthorised POS debits and blocked his card." }
}

{ "tickets": [ { "id": 1042, "priority": "urgent", "...": "..." } ], "count": 37, "next_cursor": null }

curl -X PATCH https://api.reeng-ai.dev/v1/tickets/1042 \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1042-fraud-desk" \
  -d '{"status": "contacted", "assigned_to": "Ada (fraud desk)", "team_note": "Card replaced, dispute opened"}'

The response is the updated ticket, and a ticket.updated event goes to your webhook.

What comes first

Priorities and deadlines

The agent sets each ticket's priority from what happened on the call. Your team can change it at any time.

Use your own names and times. On API & Webhooks, rename the four levels to match your service policy (P1 to P4, say) and set each one's deadline. Your names appear on Follow-ups and in every ticket as priority_label; the keys above never change, so your integration keeps working when a name does.

The times shown are the default deadlines. A ticket still open past its deadline is marked overdue, and a ticket.overdue event is sent once (checked every minute). Changing a ticket's priority starts a new deadline.

Every conversation

Calls

{
  "id": 88213,
  "call_sid": "CA9f2c...",
  "direction": "inbound",
  "caller": "+2348095551002",
  "started_at": "2026-11-10T09:11:40+00:00",
  "ended_at": "2026-11-10T09:14:03+00:00",
  "duration_seconds": 143,
  "summary": "Caller reported unauthorised POS debits and blocked his card.",
  "sentiment": "Negative",
  "outcome": null,
  "ticket_ids": [1042],
  "transcript": [ { "role": "agent", "text": "Thank you for calling Kestrel Trust Bank..." }, { "role": "user", "text": "..." } ]
}

What the agent knows

Knowledge base

Keep the agent's documents current from your own systems: your fees schedule, branch list or rates, the moment they change. The same rules apply as in the dashboard: .txt, .md, .pdf, .csv or .xlsx, up to 10 MB each.

curl -X PUT https://api.reeng-ai.dev/v1/knowledge \
  -H "Authorization: Bearer rk_live_..." \
  -F "file=@fees-and-charges.pdf"

The agent rings them

Outbound callbacks

Ask the agent to call a customer back, for example once a dispute is resolved. It calls only the caller behind one of your tickets, from your REENG number, and opens with your reason: “Hello, this is Kestrel Trust Bank calling you back about your card dispute. Is now a good time to talk?” From there it's an ordinary call.

curl -X POST https://api.reeng-ai.dev/v1/tickets/1042/call \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1042-callback-1" \
  -d '{"purpose": "your card dispute"}'

{ "id": 311, "status": "calling", "call_sid": "CA41d0...", "to": "+2348095551002" }

• Needs an active plan and a REENG number. A forwarded-only number can't place calls (409).
• Up to 3 callbacks a day for one ticket, and 30 an hour in total (429).
• The minutes count like any real call. When the customer doesn't answer, is busy or rejects it, you get outbound_call.failed; when they answer, the usual call.started and call.ended.

Pushed to you

Webhooks

Add one https address on API & Webhooks and choose its events. Each event is a POST with a JSON body.

{
  "id": "6f2a9a3e-1c1e-4c1f-9d6b-0b9a5d1e2c77",
  "event": "ticket.created",
  "created_at": "2026-11-10T09:14:04.218Z",
  "data": { "id": 1042, "priority": "urgent", "...": "the ticket" }
}

• Answer with any 2xx once you've stored it, within 10 seconds. Redirects aren't followed.
• Retries: up to three tries, straight away, after 30 seconds and after 5 minutes.
• Delivery log: every event of the last 7 days, with its result, is on API & Webhooks, where you can send any of them again.
• Order isn't guaranteed. Use updated_at to keep the newest state.

Trust, but check

Verifying webhooks

Every request is signed with your secret: an HMAC-SHA256 of the timestamp, a full stop and the raw body. Check it before you trust anything in the body, and reject requests more than 5 minutes old.

import hashlib, hmac, time

def is_from_reeng(secrets, timestamp, raw_body, signature_header):
    # Reject anything older than 5 minutes: a replayed request.
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = timestamp.encode() + b"." + raw_body
    for secret in secrets:              # your current secret, plus the old one while rotating
        want = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(want, s.strip()) for s in signature_header.split(",")):
            return True
    return False

import crypto from "node:crypto";

export function isFromReeng(secrets, timestamp, rawBody, signatureHeader) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const sent = signatureHeader.split(",").map((s) => s.trim());
  return secrets.some((secret) => {
    const want = "v1=" + crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
    return sent.some((s) => s.length === want.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(want)));
  });
}

Verified account help

Your connector

Your connector is an https address on your side. During a call the agent asks it to verify the caller, then to look things up or act, as you allow. Your system makes every decision; the agent only reads out what you return.

1. The caller asks about their account. The agent asks your chosen security questions, one at a time.
2. REENG sends a verify request with their answers and the number they're calling from. You reply verified or not.
3. Once verified, the agent can send lookup requests for what you allowed, and read your say text aloud.
4. For an action such as blocking a card, the agent reads it back, waits for a clear yes, then sends action.

Set it up on API & Webhooks: the address, 1 to 3 security questions, and what a verified caller can ask about and have done. Saving gives the connector its own signing secret; requests are signed exactly like webhooks.

Requests you receive

{
  "type": "verify",
  "call_id": "CA9f2c...",
  "is_test": false,
  "caller_phone": "+2348095551002",
  "answers": { "date_of_birth": "4 May 1990", "account_last4": "4471" }
}

{ "verified": true, "customer_ref": "CUST-77", "say": "" }

// or, when the details don't match:
{ "verified": false, "say": "Those details didn't match our records." }

{
  "type": "lookup", "call_id": "CA9f2c...", "is_test": false,
  "customer_ref": "CUST-77", "lookup": "transfer_status", "details": "Monday, 45,000 naira to Riverbend Bank"
}

{ "say": "Your transfer of forty-five thousand naira on Monday was reversed to your account this morning." }

{ "type": "action", "call_id": "CA9f2c...", "is_test": false, "customer_ref": "CUST-77", "action": "block_card" }

{ "done": true, "say": "Your card ending 1234 is now blocked. You can order a new one in the app." }

A ping request ({"type": "ping"}) is sent when you press Test it; answer it with any JSON object.

When things go wrong

Errors and limits

Errors return a status code and a JSON body you can show to a person: { "detail": "Ticket not found" }.

Stability

Versioning

Everything here is version 1. We add fields and events without notice, so ignore what you don't recognise. Anything that would break your integration comes as a new version, announced in advance, with the old one kept running alongside.

Last updated 10 November 2026.