Disclosure: I'm Nabeel, founder of VoiceDash, a white-label client portal for Retell agencies, so I have an obvious interest in this topic. This post is the build list itself, written for engineers who plan to build.

TL;DR: A client portal on top of the Retell API looks like "list calls, show a table." In practice it is eight separate pieces of work: tenant mapping, event ingestion, a local call store, recording access, client auth, per-tenant authorization, branding and domains, and retention. Below is each line item with the Retell API facts that shape it, so you can estimate it honestly before you start.

Why the "just call the API" version breaks

The first version most of us write calls Retell's list endpoint from the client's browser session and renders the result. It stops working quickly, for reasons that come straight from the docs:

  • POST /v3/list-calls is the current list endpoint, and to keep responses lean it omits transcript, transcript_object, transcript_with_tool_calls and recording_url. You need GET /v2/get-call/{call_id} per call for those. A page of 50 calls with transcripts is 51 requests.
  • The API key is account-wide. If one Retell account serves several clients, every request your portal makes can see every client's calls. Filtering has to happen on your side, correctly, every time.
  • If an agent has a data retention period set, calls are permanently deleted after it expires and "will no longer appear in session history or API responses." If your client expects twelve months of history and the agent keeps 90 days, the API cannot give it back.

So the realistic architecture is: Retell pushes events to you, you store what you need, and the portal reads only from your store. Each line item below follows from that.

Line item 1: tenant mapping

Every call needs an owner before anything else works. The cleanest key is the agent:

create table tenants ( id uuid primary key default gen_random_uuid(), name text not null, custom_domain text unique ); create table tenant_agents ( agent_id text primary key, -- Retell agent_id tenant_id uuid not null references tenants(id) ); 

Decisions hiding in this table: what happens when one agent serves two clients (do not allow it), when a client has three agents (fine, three rows), and when you clone an agent for a client (new agent_id, new row, or the calls land nowhere). Calls whose agent_id has no row should go to a quarantine table and alert you, not get dropped.

Line item 2: event ingestion

Retell's webhook docs give you the constraints: the endpoint must answer with a 2xx within 10 seconds or the event is retried up to 3 times, so the same event can arrive more than once. call_ended carries the call object without call_analysis; call_analyzed carries the full call including it. You can limit events per agent with webhook_events, and verify each request with the X-Retell-Signature header (only an API key with the webhook badge can verify).

That means: verify, persist raw, acknowledge, process later.

app.post("/retell/webhook", express.raw({ type: "application/json" }), async (req, res) => { const raw = req.body.toString("utf-8"); const sig = req.headers["x-retell-signature"]; if (typeof sig !== "string" || !(await Retell.verify(raw, process.env.RETELL_WEBHOOK_KEY, sig))) { return res.status(401).end(); } const { event, call } = JSON.parse(raw); // Idempotent: one row per (call_id, event) await db.query( `insert into retell_events (call_id, event, payload) values ($1, $2, $3) on conflict (call_id, event) do nothing`, [call.call_id, event, raw] ); res.status(204).end(); queue.push({ callId: call.call_id, event }); // heavy work after the ack }); 

You also need a reconciliation job. Webhooks tell you something happened; they do not prove you have everything. A nightly pass over list-calls for each agent catches events your server missed while it was deploying.

Line item 3: the local call store

Your portal queries your database, so design the table for the client's questions, not for Retell's payload:

create table calls ( call_id text primary key, tenant_id uuid not null references tenants(id), agent_id text not null, direction text, started_at timestamptz, ended_at timestamptz, duration_ms integer, disconnection_reason text, call_successful boolean, -- from call_analysis, filled on call_analyzed custom_analysis jsonb, -- your post-call fields transcript text, has_recording boolean default false ); create index on calls (tenant_id, started_at desc); 

Two things to budget for: updating the row when call_analyzed arrives after call_ended (two writes per call, in either order if retries reorder them), and backfilling when you change your post-call analysis fields, since old calls will not have the new keys.

Line item 4: recordings

By default Retell's recording and log URLs do not expire. That is convenient and dangerous in a portal: a URL pasted into a client email works forever for anyone. Retell lets you opt in to secure URLs per agent (opt_in_signed_url: true), with an expiry from 1 minute to 7 days, 24 hours by default. Files created before you opt in keep generating unsigned URLs.

So do not store recording URLs. Store has_recording, and when a logged-in client presses play, fetch the call with get-call server side, after checking the call belongs to their tenant, and return the fresh signed URL. If you copy audio into your own storage instead, you now own encryption, retention and deletion of call audio, which is a bigger line item than it looks.

Line item 5: client authentication

Clients need their own logins, separate from yours. The work list: invites, password reset or magic links, sessions, and team members per client (the office manager and the owner both want access). If you use one auth system for agency staff and clients, add a role and make sure a client role can never call an agency route.

Line item 6: per-tenant authorization

This is the item that ends agencies when it is wrong. Every query must be scoped to the caller's tenant. Doing it in application code means every new endpoint is a chance to forget. Postgres row-level security moves the rule into the database:

alter table calls enable row level security; create policy tenant_isolation on calls using (tenant_id = current_setting('app.tenant_id')::uuid); 

Then set app.tenant_id per request from the session, and write a test that logs in as tenant A and requests a known call_id from tenant B. That test should exist before the first client logs in, and run on every deploy.

Line item 7: branding and custom domains

Clients want their own logo and colors, and agencies want portal.clientagency.com instead of your domain. The work: per-tenant theme storage, host-based tenant resolution, TLS certificates issued on demand for each custom hostname, and DNS instructions clients can follow. Then the leaks: the sign-in email's sender and links, the browser tab title and favicon, and any error page that shows your product name or a vendor's.

Line item 8: retention and deletion

You now hold transcripts of other businesses' customers. Decide how long you keep them, match it to the agent's Retell retention setting (data_storage_retention_days, 1 to 730 or null for forever), delete both copies when a client leaves, and write down what you keep. Clients in regulated niches will ask.

The line items that never finish

Everything above is the build. Ownership continues: Retell API changes (list calls is already on v3, and the legacy GET /list-calls is deprecated), webhook outages you need to notice, new metrics clients ask for, and support for "why is last Tuesday missing?"

If you list these out and still want to build, that is a reasonable call: you get full control of the data model and any metric you like. If you would rather compare the work against buying, I wrote up the trade-off in Build vs Buy a Client Portal for Your Voice AI Agency: What a Custom Retell Dashboard Really Costs (2026).

Retell facts in this post come from Retell's docs, read on November 18, 2026: webhook overview, secure the webhook, list calls, secure URLs and data retention.

Drafted with AI assistance and fact-checked against each vendor's docs.