Interoperability Demo

How It Works

Vendors who use Twilio produce call transcripts with text, timestamps, and speaker labels. The NHID-Clinical Twilio adapter reads that format and produces a structured event trace showing when disclosure happened, when data was first requested, and whether the call passes IDG-01.

The same pattern applies to other voice platforms (Bland.ai, Vapi, Retell) — each needs its own adapter, but the output schema is identical.

Case 1: Compliant Call

Agent discloses before requesting any operational data.

Input — Twilio transcript

{
  "call_sid": "CA123456789",
  "start_time": "2026-05-27T14:00:00Z",
  "transcript": [
    {"text": "Hello, this is an automated system calling on behalf of Dr. Smith's office.",
     "timestamp": 0.5, "speaker": "agent"},
    {"text": "Can I get the NPI number please?",
     "timestamp": 3.2, "speaker": "agent"},
    {"text": "Sure, it's 1234567890.",
     "timestamp": 5.8, "speaker": "human"}
  ]
}

Output — NHID-Clinical trace

{
  "trace_id": "twilio_CA123456789",
  "source_format": "twilio_transcript",
  "policy_version": "1.3",
  "events": [
    {"event_type": "DISCLOSURE",    "timestamp_offset_s": 0.5, "nhid_rule": "IDG-01"},
    {"event_type": "DATA_REQUEST",  "timestamp_offset_s": 3.2, "nhid_rule": "PDX-01"}
  ],
  "compliance": {
    "IDG-01": "PASS",
    "disclosure_timestamp_offset_s": 0.5,
    "first_data_request_offset_s": 3.2,
    "disclosure_made": true
  }
}

IDG-01: PASS — disclosure at 0.5s, data request at 3.2s. Disclosure preceded data exchange.

Case 2: Non-Compliant Call (Late Disclosure)

Agent requests data before identifying as automated — impersonation latency.

Input — Twilio transcript

{
  "call_sid": "CA999888777",
  "start_time": "2026-05-27T14:05:00Z",
  "transcript": [
    {"text": "Hi, can I get the member ID and NPI?",
     "timestamp": 0.3, "speaker": "agent"},
    {"text": "Sure — NPI is 1234567890.",
     "timestamp": 2.1, "speaker": "human"},
    {"text": "Thank you. By the way, I'm an automated system.",
     "timestamp": 4.0, "speaker": "agent"}
  ]
}

Output — NHID-Clinical trace

{
  "trace_id": "twilio_CA999888777",
  "source_format": "twilio_transcript",
  "policy_version": "1.3",
  "events": [
    {"event_type": "DATA_REQUEST",  "timestamp_offset_s": 2.1, "nhid_rule": "PDX-01"},
    {"event_type": "DISCLOSURE",    "timestamp_offset_s": 4.0, "nhid_rule": "IDG-01"}
  ],
  "compliance": {
    "IDG-01": "FAIL – disclosure occurred after data request (impersonation latency)",
    "disclosure_timestamp_offset_s": 4.0,
    "first_data_request_offset_s": 2.1,
    "disclosure_made": true
  }
}

IDG-01: FAIL — data requested at 2.1s, disclosure not until 4.0s. 1.9 seconds of impersonation latency.

Run It Yourself

git clone https://github.com/thankcheeses/NHID-Clinical.git
cd NHID-Clinical
git checkout claude/code-review-fixes-98Ir1
python adapters/twilio_adapter.py

Replace SAMPLE_TWILIO_COMPLIANT or SAMPLE_TWILIO_NONCOMPLIANT in the adapter with your own call transcript to test your vendor's output.

Other Vendor Formats

The Twilio adapter demonstrates the mapping pattern. The same approach applies to other voice platforms — the output schema is always the same NHID-Clinical trace format.

Platform	Status	Notes
Twilio Voice Intelligence	✅ Adapter available	See adapters/twilio_adapter.py
Bland.ai	🔲 Planned	Transcript format documented; adapter not yet written
Vapi	🔲 Planned	Transcript format documented; adapter not yet written
Retell AI	🔲 Planned	Transcript format documented; adapter not yet written

If you have logs from a platform not listed here, email contact@nhid-clinical.org — we'll build the adapter together.

← Developers  ·  Spec  ·  Pilot Guide