> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCID — the malicious-call trace model

> How Malicious Call Identification (MCID, the `*57` service) works in Devotel Orbit — a provisioning and audit surface that flags inbound nuisance calls inside a 7-day window, writes a tamper-evident marker, and exports a regulated report; carrier-side capture stays out of platform scope.

# MCID — the malicious-call trace model

<Warning>
  Orbit provides **flagging, storage, and an auditable workflow only**. MCID
  never taps media, captures call content, or performs the carrier-side
  trace itself. Flagging records that a specific inbound call was reported
  and preserves the originating identity Orbit already held — actual
  trace/capture and law-enforcement delivery are carrier and mediation-layer
  concerns, out of platform scope. The same honesty register applies as on
  the CALEA provisioning surface: this page is not legal advice.
</Warning>

## What MCID is

Malicious Call Identification (MCID) is the regulated UCaaS supplementary
service a callee invokes to report a threatening, harassing, or nuisance
call — dialed as `*57` on NANP handsets, with equivalents in EU/APAC
regions. The service exists so a trap-trace at the carrier preserves the
**originating caller's identity** for a law-enforcement or abuse-team
handoff, even when the caller spoofed or withheld their display name.

In Orbit, MCID is a provisioning and audit surface. Flagging a call does
three durable things and nothing else:

1. Writes an append-only, SHA-256 hash-chained entry to your audit log
   under the `voice_mcid.flagged` action — the tamper-evident record an
   abuse team can rely on later.
2. Stores a small marker on the call record itself so the dashboard can
   render "flagged" on the call and recording detail pages.
3. Makes the call eligible for the regulated export (see below).

Flagging does not touch the carrier leg, originate a call, or capture
audio. The carrier-side trace that makes MCID meaningful at the PSTN
layer is requested by your organization's callee (or handed to the carrier
through the export); Orbit holds the evidence.

Two surfaces reach the same flag path, so the record is identical
regardless of how the report arrives:

* **Dashboard** — an agent flags from the call or recording detail page.
* **Softphone star code** — the receiver dials `*57` after hanging up;
  the platform resolves the most recent inbound call to that mailbox and
  flags it.

## The eligibility model — inbound and recent only

Two gates decide whether a flag can land. Both exist for the same reason:
MCID reports the *originating party of an inbound call*, and the
carrier-side signaling trail that makes the report actionable degrades
with age.

| Gate | Rule | Why it exists |
| - | - | - |
| Direction | Only `inbound` calls can be flagged. | A callee reports an inbound nuisance **caller** — an outbound call has no originating identity to preserve from the callee's side. |
| Recency | The call must have started within the trailing **7 days**. | The CDR/SIP trace data a carrier's abuse team needs ages out; a stale call can't be retroactively traced. |

The 7-day window is generous relative to the "immediately" framing of the
classic PSTN service while still covering a callee who decides to escalate
a few days later. Because the window has a hard edge, prompts and flag
controls decay after it closes: the dashboard hides the **Flag** action
on rows older than the window, and the API refuses the POST with a
`409 MCID_CALL_TOO_OLD`. Coach agents to flag promptly — same-day flags
carry the strongest trace data.

## The flag lifecycle

The dashboard path is the one most operators use:

1. Open the **Call** or **Recording** detail page for an inbound call
   inside the window.
2. Choose **Flag for malicious-call trace**; optionally add a free-text
   reason (up to 500 characters).
3. The page sends `POST /api/v1/voice/mcid/:callId`. The API validates
   the call, writes the audit entry, then claims a metadata cache cell
   on the call row.
4. The marker lives in the call record's `metadata.mcid` JSONB cache —
   Orbit's extend-metadata pattern (the same one KBA verification uses),
   so the feature ships with no schema migration and everything stays
   inside your tenant schema. The cache holds the flag timestamp, the
   flagging user, the optional reason, the preserved originating
   identity, and a reference to the audit entry that anchors it.

The metadata cache is a convenience projection only; the audit chain
remains the source of truth. A re-flag of an already-flagged call is
idempotent — the API returns `200` with the existing record, so repeat
clicks and retried POSTs are safe and never produce duplicate markers.

The full marker shape (as it appears on `metadata.mcid`):

```json theme={null}
{
  "flagged": true,
  "flaggedAt": "2026-09-30T08:15:27.000Z",
  "flaggedBy": "user_0a1b2c3d",
  "reason": "Caller made threats",
  "originatingIdentity": "+14155550123",
  "normalizedOriginatingIdentity": "+14155550123",
  "calledNumber": "+14155550999",
  "auditId": "a-log-entry-id",
  "auditHash": "sha256-of-chain-anchor"
}
```

`auditId` and `auditHash` point at the exact hash-chain anchor for this
report, so an export or an abuse-team review can verify the entry without
trusting the mutable dashboard state.

## The direction gate

Post a flag against a call whose `direction` is not inbound and the API
refuses before writing anything:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/mcid/call_abc123" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Caller made threats"}'
```

```json theme={null}
{
  "error": {
    "code": "MCID_INVALID_DIRECTION",
    "message": "Only inbound calls can be flagged for a malicious-call trace"
  }
}
```

The response is a hard `400` — the request never writes a marker or an
audit entry. Filter the call list to inbound rows before rendering the
flag action, and the gate never fires in the first place.

## Export — the regulated report

When a carrier abuse team or law-enforcement officer asks for the flagged
calls, an **owner** or **admin** pulls the export:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/mcid/export?from=2026-09-01&to=2026-09-30&limit=200" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

The export lists every flagged call in an optional date range (`from` and
`to`; default the last 90 days; `limit` of 1–500, default 200), with each
item carrying the call identifiers and the full marker above. Because it
surfaces preserved caller identity across many calls, the export is
gated to owner/admin only — an agent or developer token gets a `403`.

Treat the export as a regulated handoff artifact: keep it inside the
role-gated lane, and point the asking authority at exactly the rows they
requested.

## Where the endpoints live

* [Voice API → MCID](/api-reference/endpoints/voice) — the endpoint
  contract for `POST /voice/mcid/{callId}`, `GET /voice/mcid/{callId}`,
  and `GET /voice/mcid/export`.
* [Troubleshooting: MCID flag failures](/troubleshooting/mcid-flag-failures)
  — the runbook mapping every reject code to the gate that fired and the
  fix you own.
* [CALEA lawful-intercept provisioning](/compliance/calea-intercept) —
  the sibling surface with the same "Orbit provisions and audits, the
  carrier captures" honesty register.
* [KBA caller verification](/concepts/caller-verification-kba) — the
  extend-metadata pattern MCID borrows for its no-migration ledger.