# ARKA-TCOC — Data request

**Turnaround: ten business days from receipt.** (Vol III §31.3)

This is the extract we need to run Module 1 (attribution + low-value imaging ledger) on your population. An analyst who already pulls claims for finance or quality can produce it without a call. If they cannot produce this in an hour, tell us and we will simplify the request.

## What to send

One flat file (CSV preferred; Parquet accepted) with **one row per claim line**. Month grain is enough for dates of birth on the member side; day of service is required on the claim. Member identifiers may be your internal id — we hash them at the boundary and never store the raw value.

| Field | Required? | Notes |
|---|---|---|
| Member id | **Required** | Opaque plan/member id. Not an MRN, SSN, or name. |
| Claim id | **Required** | Payer claim number or internal claim key. |
| Line number | Optional | Defaults to 1 when omitted. |
| Date of service | **Required** | Day precision (`YYYY-MM-DD`, `YYYYMMDD`, or `MM/DD/YYYY`). |
| HCPCS / CPT | **Required** | Procedure code on the line. |
| HCPCS modifiers | Optional | Pipe- or comma-separated. |
| Units | Optional | Defaults to 1. |
| Allowed amount | Optional | Dollars (or cents — say which). Integer cents preferred. |
| Paid amount | Optional | Same unit as allowed. |
| Billing NPI | Optional | 10-digit NPI; leading zeros OK. |
| Rendering NPI | Optional | Performing clinician. |
| **Ordering / referring NPI** | **Required** | Item 17b / 837P referring loop. Tier-1 attribution key. |
| Principal diagnosis | Optional | ICD-10-CM; with or without decimal. |
| Other diagnoses | Optional | Pipe-separated ICD-10-CM. |
| Place of service | Optional | CMS POS code (professional). |
| Revenue code | Optional | UB revenue code (institutional). |
| DRG | Optional | MS-DRG when institutional. |
| Claim type | Optional | Professional vs institutional flag if you have one. |
| Provider specialty | Optional | Rendering specialty label or CMS specialty code. |
| Provider state | Optional | Two-letter state of rendering provider. |

Column names can be yours. Send a one-page YAML (or spreadsheet) mapping your headers to the fields above — see `examples/acme.yaml`. We do not need a code change to onboard you.

## Nothing else

Do **not** send:

- Member or clinician names
- Street addresses, emails, or phone numbers
- Medical record numbers (MRNs)
- Social Security numbers
- Free-text clinical notes or imaging reports
- Member date of birth at day precision — **year and month only** if you include DOB at all

If a column is not in the table above, leave it out. Extra PHI columns slow legal review and do not improve the ledger.

## Sample file

A 200-row synthetic professional extract your analyst can diff against:

[`examples/acme/sample-200.csv`](../../examples/acme/sample-200.csv)

Load test (from repo root):

```bash
npm run tcoc -- ingest --source generic --map ./examples/acme.yaml --dry-run
```

That command prints an `IngestionQualityReport` and writes nothing.

## File transfer

Pick one:

1. **SFTP** — we provision a tenant drop folder; you push the file.
2. **S3 pre-signed URL** — we send a time-limited PUT URL; you upload once.
3. **Secure upload** — browser upload to our BAA-covered intake (link on request).

Encrypt at rest on your side before transfer if your policy requires it; TLS in transit either way.

## BAA

ARKA signs a Business Associate Agreement before any real member-level extract leaves your environment. Public CMS files and synthetic samples do not require a BAA. The extract described here is limited to the fields above; we hash member identifiers at ingest and do not use day-level dates of birth. Packet delivery to clinicians is a separate, non-PHI channel once attribution is computed.

## One-hour test

If your analyst cannot produce this extract in an hour from systems they already query, tell us which fields are hard. We will drop or substitute them rather than invent a multi-week data project. The ordering/referring NPI is the one field we will push to keep — without it, clinician-level results are incomplete and we will say so on page 1 of the report.