Agent & Supervisor Mapping

Send Birdie an agent-to-supervisor-to-BPO mapping so FI access control can isolate each BPO into its own workspace.

Overview

Birdie isolates FI access per BPO. Rather than inferring the agent → supervisor → BPO relationship from tickets (which can be incomplete or eventually consistent), Birdie relies on a dedicated mapping feed as the source of truth for access control — an authoritative list of, for every agent, who their supervisor is and which BPO they belong to.

---

Requirements

• Separate feed: send the mapping in its own directory or dataset, distinct from your ticket ingestion (e.g. use a dedicated agent_supervisor/ directory).

• Full snapshot: send one row per active agent, covering the full current roster — not an incremental delta. Each refresh replaces the previous state.

• Matching identifiers: the identifiers in the mapping must match exactly the ones that appear in your tickets (see the schema below), otherwise the links cannot be made.

• Kept up to date: the mapping must be refreshed on an ongoing basis so that new hires, role changes, and BPO moves are reflected (see Keeping the mapping up to date).

---

Data Schema

Each row maps one agent to their supervisor and BPO. All three fields below are required.

Column Name	Type	Required	Description	Example	Impact
agent_id	STRING	Yes	The agent's identifier, as it appears in your tickets (author_id) — typically an email, but any identifier that is stable over time works. Must match the ticket value exactly so the agent can be linked to their own data.	"[e-mail]"	When the agent logs in they see none of their own tickets — the agent isn't linked to their data, so no per-agent access, Quality Score, or Agent Feedback.
supervisor_id	STRING	Yes	The identifier of the agent's direct supervisor — typically an email. Grants the supervisor access to their team's data and drives supervisor-level FI rollups.	"[e-mail]"	Supervisor sees no team data; supervisor-level rollups unavailable.
company	STRING	Yes	A stable identifier for the BPO (outsourcing vendor) the agent works for. Determines which workspace the agent and supervisor are isolated into. Must be unique and stable per BPO and match the agent's agent_company in your tickets.	"acme_bpo"	A wrong or ambiguous value breaks per-BPO isolation — an agent may land in the wrong workspace, or a BPO's data may be split or merged.

---

One workspace per BPO

The company field is what routes an agent and their supervisor into a workspace, so it must identify each BPO uniquely and consistently over time:

• One BPO must always be sent as a single, stable value. If the same BPO arrives under two different values (e.g. acme_bpo and acme_bpo_inc), each value is treated independently. Unless both values are intentionally mapped to the same workspace, the BPO's data can become fragmented.

• Two different BPOs must never share the same value. If they do, their data is merged into one workspace and the per-BPO isolation is broken.

Birdie does not create workspaces from the mapping. The feed only synchronizes agents and supervisors with workspaces that already exist in Birdie. If a company value doesn't match an existing workspace (or one of its aliases), those rows are skipped — no new workspace is created automatically.

If your organization has a single BPO (or none), the company value can be the same across all agents — everyone shares one workspace.

Internal (in-house) agents in a mixed setup. If some agents are your own internal team alongside one or more BPOs, those internal agents should also have a stable company value. That value may be a default shared by all internal agents or a custom value chosen for your workspace layout, but it should remain unique and consistent like any other company value.

---

Keeping the mapping up to date

The mapping reflects a live organization: agents are hired, change roles, and move between BPOs. An out-of-date mapping means people lose access they should have, or keep access they shouldn't. So this is an ongoing ingestion, not a one-time load.

• Delivery: send it through any supported file-based source — Cloud Storage (AWS S3, Azure Blob Storage, Google Cloud Storage) or an sFTP share — following the Data Lake / File-based Ingestion path (see Birdie's Integration Paths). See S3 / Azure / GCS or sFTP for setup.

• Cadence: refresh regularly (a daily full snapshot is recommended) so changes propagate. Each snapshot replaces the previous state.

• Fail-closed: the mapping defines a user's scope, not whether they can sign in. If an agent or supervisor is missing from the current mapping, they won't receive a default or broad scope. They'll only see data after they appear in the next refresh.

---

Frequently Asked Questions

What if an agent isn't in the mapping yet?

The mapping defines scope, not authentication. If an agent isn't in the current mapping, they may still be able to sign in, but they'll see no data until they're included in the next refresh. For supervisors, any agents missing from the mapping simply won't be part of their scope. Send the full active roster on every refresh to avoid gaps.

Can an agent move to another BPO?

Yes. Update the agent's company and supervisor_id together in the same snapshot — a move to another BPO means a new supervisor too, so both must change at once. The agent is routed to the new BPO's workspace within 24 hours.

Do agents and supervisors need to exist as separate rows?

No. A supervisor is identified by appearing as the supervisor_id of the agents they manage. If a supervisor is also an agent under someone else, they can additionally appear as an agent_id in their own row.

What file format should we use?

Any format supported by your chosen file-based source (CSV, Parquet, or JSON). The Birdie team will help you configure the feed during setup.