# Local referral review: method and field dictionary

The kit uses invented records. The Python 3 checker reads a local CSV and writes a review CSV to standard output. It makes no network request, changes no ATS record, sends no message and approves no award. The editable worksheet and CSVs can be used without Python or a Metix account.

Run the supplied example:

```sh
python3 employee-referral-review.py employee-referral-example.csv --as-of 2026-11-02 > review.csv
```

Compare review.csv with employee-referral-expected.csv. Start your own data with employee-referral-log-template.csv. Do not relabel the fictional rows as real submissions. Use employee-referral-decisions.csv for unresolved company decisions.

## Record unit and input

One row is one referral submission for one role. Keep repeated submissions as separate records with distinct submission IDs. A person referred for two roles has two different person/role pairs. The checker groups exact person_key + role_id matches across all supplied rows, including different policy versions. It does not decide whether either submission is valid or which version wins.

| Field | Meaning |
|---|---|
| submission_id | Unique stable ID for this submission. Repeated IDs are an export error, not another referral. |
| person_key | Opaque ID reconciled in the employer's authorized records. Do not infer identity from matching names. |
| role_id | One approved role ID; retain the relevant brief in the employer's own records. |
| referrer_key | Opaque employee/source ID, not a name or email. |
| policy_version | Version applicable to this submission, subject to company review. |
| submitted_on | Actual submission date, no later than the reporting cutoff. |
| acknowledged_on | Actual receipt acknowledgement date, or blank if not recorded. It must fall between submission and cutoff. |
| followup_on | The next check date chosen by the team, or blank if unknown. It cannot precede submission. |
| owner_id | Current responsible owner ID, or blank when unassigned. |
| contact_permission | yes, no or unknown according to the company's actual verification process. A yes in a CSV does not prove permission. |
| prior_record | yes, no or unknown after checking the company's authorized records. It does not itself establish program eligibility. |

ID fields accept 1-64 letters, digits, underscores or hyphens, starting with a letter or digit. Keep the supplied header order. Dates use YYYY-MM-DD in one documented company timezone. The script operates on calendar dates, not hours, business-day calendars or SLA durations.

Opaque IDs are pseudonymous references, not a guarantee of anonymity. Keep the identity map, contact details, permission evidence, policy approvals and assessment records in the employer's authorized system. The script cannot find the same person under two IDs or distinguish two people incorrectly assigned the same ID. Correct identity mapping before interpreting a duplicate flag.

## Output and interpretation

The original columns are retained. same_role_submissions counts exact matching person/role pairs. review_flags lists independent questions: duplicate_same_role, permission_hold, prior_record_review, record_check, owner_missing, acknowledgement_missing or followup_missing. none means no listed flag was found in the supplied fields; it is not approval to contact, interview, hire or pay.

followup_status is overdue when the chosen date is before as-of, due_today on that date, scheduled after it and unknown when blank. It does not establish whether a task is complete. Advance a next-check date only after recording what actually happened. Every supplied row remains visible, including held rows; the checker selects no winner and produces no payout or hiring rank.

DEMO01 and DEMO02 share person P01 and role ROLE-A. Both get duplicate_same_role with count 2 even though DEMO01 was submitted first. DEMO03 uses P01 and ROLE-B, so its count is 1. At November 2, DEMO04 has permission unknown, a missing receipt and an overdue check. DEMO05 has permission no; it remains on hold. DEMO06 has a prior record; DEMO07's record status is unknown. DEMO08 has no owner, receipt or follow-up date. DEMO09 is overdue despite having an acknowledgement, while DEMO10 is due today. These are fictional process checks, not candidate quality scores.

The script validates all rows before emitting any report. Invalid dates, future submissions/acknowledgements, duplicate submission IDs, malformed columns or unsafe identifiers reject the whole file. Unknown permission or prior-record information is an explicit input value and remains visible.

Use the manual decision log to name a policy version, a decision owner, an actual reason and a review date. Keep the linked original submission IDs. The checker cannot establish compliance, resolve referral ownership, enforce access controls, validate permission or administer bonuses.