Part of Data System (UVP) · Home: All V2 Specs
This document defines the canonical global fields in VRM’s Unified Voter Profile (UVP). It is the authoritative field-level reference for database schema design, API contracts, and UI rendering.
Relationship to SKILL.md: The main skill file defines HOW the system works (data flow, priorities, visibility). This file defines WHAT specifically goes where (field names, types, validation).
This is a living document. New fields are added as they are promoted from custom fields (see Section 5.3 of the main spec) or defined by Politogy.
Table of Contents
- Naming Conventions
- Data Types
- Identity Core Fields
- Contact Info Fields
- Geographic Fields
- Vote History Fields
- Enrichment Fields
- Relationship Data Fields
- Campaign Data Fields
- Petition Data Fields
- Aggregate Intelligence Fields
- Custom Field Namespace
Naming Conventions
All canonical field names follow these rules:
- Prefix:
voter_for voter-level data,acct_for account-scoped data,ai_for computed/AI-generated data - Format:
snake_case, lowercase, no abbreviations (except standard ones:dob,id,reg) - Canonical name is immutable. Once a field is promoted to global, its canonical name NEVER changes. Display labels can be adjusted.
- No collisions: Canonical names must be unique across all layers.
Data Types
| Type | Description | Example |
|---|---|---|
text | Free-form string, max 500 chars | Voter name, notes |
long_text | Free-form string, max 10,000 chars | Contact log entries |
number | Integer or decimal | Age, score |
date | ISO 8601 date (YYYY-MM-DD) | DOB, registration date |
datetime | ISO 8601 datetime | Timestamp of contact |
boolean | true/false | Signed petition? |
dropdown | Single-select from defined values | Party affiliation |
multi_select | Multi-select from defined values | Issue interests |
address | Structured address object | Residential address |
phone | E.164 format phone number | +15035551234 |
email | Email address | voter@example.com |
geo_id | Reference to a geographic entity | Precinct ID, district ID |
score | 0.0–1.0 float with confidence | AI propensity scores |
computed | Read-only, system-generated | AI outputs |
Identity Core Fields
These fields are sourced from the state voter file. Read-only for customer-tier users.
| Canonical Name | Display Label | Type | Required | Notes |
|---|---|---|---|---|
voter_reg_id | Voter ID | text | Yes | Primary key. State voter registration ID. |
voter_first_name | First Name | text | Yes | Legal first name from voter file |
voter_middle_name | Middle Name | text | No | |
voter_last_name | Last Name | text | Yes | Legal last name from voter file |
voter_name_suffix | Suffix | text | No | Jr., Sr., III, etc. |
voter_dob | Date of Birth | date | Yes | |
voter_party | Party Affiliation | dropdown | Yes | Values: DEM, REP, IND, LBT, GRN, OTH, NAV |
voter_reg_status | Registration Status | dropdown | Yes | Values: ACTIVE, INACTIVE, SUSPENDED, CANCELED |
voter_reg_date | Registration Date | date | Yes | |
voter_gender | Gender | dropdown | No | Values per state voter file conventions |
Contact Info Fields
Multi-source. Subject to priority rules (user > enrichment > voter file).
| Canonical Name | Display Label | Type | Required | Default Exposure |
|---|---|---|---|---|
voter_residential_address | Residential Address | address | Yes | Always Visible |
voter_mailing_address | Mailing Address | address | No | Always Visible |
voter_phone_primary | Primary Phone | phone | No | Tier-Gated |
voter_phone_secondary | Secondary Phone | phone | No | Tier-Gated |
voter_email_primary | Primary Email | No | Tier-Gated | |
voter_email_secondary | Secondary Email | No | Tier-Gated | |
voter_preferred_name | Preferred Name | text | No | Always Visible |
Geographic Fields
Derived from voter file + geocoding. Updated on voter file refresh or address change.
| Canonical Name | Display Label | Type | Notes |
|---|---|---|---|
voter_county | County | geo_id | |
voter_precinct | Precinct | geo_id | |
voter_congressional_district | Congressional District | geo_id | |
voter_state_house_district | State House District | geo_id | |
voter_state_senate_district | State Senate District | geo_id | |
voter_city | City | text | |
voter_zip | ZIP Code | text | 5-digit or ZIP+4 |
voter_school_district | School District | geo_id | |
voter_ward | Ward | geo_id | Where applicable |
voter_lat | Latitude | number | Geocoded from address |
voter_lng | Longitude | number | Geocoded from address |
Vote History Fields
Array/collection per voter. One entry per election.
| Canonical Name | Display Label | Type | Notes |
|---|---|---|---|
voter_election_id | Election ID | text | Unique election identifier |
voter_election_date | Election Date | date | |
voter_election_type | Election Type | dropdown | PRIMARY, GENERAL, SPECIAL, RUNOFF |
voter_vote_method | Vote Method | dropdown | IN_PERSON, MAIL, DROP_OFF, EARLY, PROVISIONAL |
voter_ballot_status | Ballot Status | dropdown | ACCEPTED, REJECTED, CHALLENGED, PENDING |
Enrichment Fields
Sourced from third-party providers. Controlled per field. Always carries confidence score.
| Canonical Name | Display Label | Type | Default Exposure |
|---|---|---|---|
voter_estimated_income | Est. Household Income | dropdown | Internal Only |
voter_estimated_education | Est. Education Level | dropdown | Internal Only |
voter_estimated_ethnicity | Est. Ethnicity | dropdown | Internal Only |
voter_household_size | Household Size | number | Tier-Gated |
voter_homeowner_status | Homeowner Status | dropdown | Tier-Gated |
voter_donor_history | Donor History | long_text | Account-Specific |
voter_social_handles | Social Media | multi_select | Internal Only |
voter_consumer_interests | Consumer Interests | multi_select | Internal Only |
Relationship Data Fields
Account-scoped. Created by customer-tier users in Relationship Mode.
| Canonical Name | Display Label | Type | Notes |
|---|---|---|---|
acct_tags | Tags | multi_select | User-defined tags |
acct_notes | Notes | long_text | Free-form contact notes (append-only log) |
acct_relationship_score | Relationship Score | number | 0–100, user-assigned or computed |
acct_last_contact_date | Last Contact | datetime | Auto-set on contact log entry |
acct_assigned_to | Assigned To | text | Team member assignment |
acct_contact_log | Contact Log | long_text | Structured log of all contact attempts |
Campaign Data Fields
Account-scoped. Created in Campaign Mode.
| Canonical Name | Display Label | Type | Notes |
|---|---|---|---|
acct_turf_assignment | Turf | text | Assigned walk/call turf |
acct_canvass_result | Canvass Result | dropdown | Values: CONTACT, NOT_HOME, REFUSED, MOVED, DECEASED, INACCESSIBLE |
acct_canvass_date | Canvass Date | datetime | |
acct_survey_responses | Survey Responses | long_text | Structured survey Q&A |
acct_call_result | Call Result | dropdown | ANSWERED, VOICEMAIL, WRONG_NUMBER, NO_ANSWER, BUSY |
acct_call_date | Call Date | datetime |
Petition Data Fields
Account-scoped. Created in Petition Mode.
| Canonical Name | Display Label | Type | Notes |
|---|---|---|---|
acct_petition_id | Petition | text | Which petition |
acct_signature_status | Signature Status | dropdown | SIGNED, DECLINED, PENDING, INVALID |
acct_signature_date | Signature Date | datetime | |
acct_signature_collector | Collector | text | Who collected the signature |
acct_signature_verified | Verified | boolean | Post-collection verification |
Aggregate Intelligence Fields
Politogy-computed. Read-only for all users. Writable only by system processes. Subject to exposure controls for monetization.
| Canonical Name | Display Label | Type | Default Exposure | Refresh Cadence |
|---|---|---|---|---|
ai_sentiment_composite | Sentiment Score | score | Internal Only | Daily |
ai_propensity_vote | Propensity to Vote | score | Account-Specific | Weekly |
ai_propensity_respond | Propensity to Respond | score | Account-Specific | Weekly |
ai_propensity_switch | Propensity to Switch Party | score | Internal Only | Monthly |
ai_propensity_sign | Propensity to Sign Petition | score | Account-Specific | Weekly |
ai_persuadability | Persuadability Index | score | Internal Only | Monthly |
ai_contact_freshness | Contact Freshness | score | Tier-Gated | Daily |
ai_issue_positions | Estimated Issue Positions | long_text | Internal Only | Weekly |
ai_segment_cluster | Segment Cluster | text | Tier-Gated | Weekly |
ai_model_version | Last Model Version | text | Internal Only | On compute |
Custom Field Namespace
User-created fields follow these rules:
- Prefix:
custom_+ account ID +_+ user-defined name (e.g.,custom_acct123_timber_policy_position) - Stored against the UVP but tagged with creating account ID, creating user ID, creation timestamp
- Visible to Politogy for cross-account analysis and field promotion detection
- Invisible to other accounts
- Supported types: text, number, date, boolean, dropdown, multi_select
- No validation rules (unlike global fields) — users define freely
- Promotable: When Politogy promotes a custom field to global, existing data migrates and the custom field is retired
Provenance Metadata Schema
Every field value (global or custom) carries this metadata:
{
"field": "voter_phone_primary",
"value": "+15035551234",
"source": {
"type": "user_input", // voter_file | enrichment | user_input | ai_computed
"provider": null, // enrichment provider name, if applicable
"account_id": "acct_456", // if user_input
"user_id": "user_789", // if user_input
"model_id": null, // if ai_computed (e.g., "contact-freshness-v1.2")
"model_inputs": null // if ai_computed, array of input field references
},
"confidence": null, // 0.0–1.0, required for enrichment and ai_computed
"timestamp": "2026-05-02T14:30:00Z",
"superseded_by": null, // reference to replacing value, if overridden
"status": "active" // active | superseded | archived
}
Last updated: May 2026 Document owner: Politogy LLC