> For the complete documentation index, see [llms.txt](https://docs.teleskope.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.teleskope.ai/specifications/data-elements/entity-taxonomy-v2.md). # Entity Taxonomy v2 Entity Taxonomy v2 organizes **65 entity labels** into **10 hierarchical families** using dot notation. For example, `PERSONAL.name.given` is the v2 label for a given name. {% hint style="info" %} Teleskope environments are being migrated to Entity Taxonomy v2 in phases. Some environments may continue to return v1 labels until their migration is complete. {% endhint %} ## Label Structure | Level | Description | Example | | ----- | ----------- | --------------------- | | L1 | Family | `PERSONAL` | | L2 | Category | `PERSONAL.name` | | L3 | Subcategory | `PERSONAL.name.given` | Different categories of elements are separated into tables and optional descriptions are provided for ambiguous element names. ### Personal Information Core personal identifiers. `PERSONAL.dob` captures full and partial dates of birth. | Parent Label | Element Label | Description | | ------------------ | ------------------------- | -------------------------------------- | | `PERSONAL` | `PERSONAL.name` | Full or unspecified person name | | `PERSONAL.name` | `PERSONAL.name.given` | Given or first name | | `PERSONAL.name` | `PERSONAL.name.family` | Family or last name | | `PERSONAL` | `PERSONAL.email` | Email address | | `PERSONAL` | `PERSONAL.phone` | Phone number | | `PERSONAL` | `PERSONAL.dob` | Date of birth, including partial dates | | `PERSONAL` | `PERSONAL.username` | Username or handle | | `PERSONAL` | `PERSONAL.address` | Full or unspecified address | | `PERSONAL.address` | `PERSONAL.address.street` | Street address | | `PERSONAL.address` | `PERSONAL.address.unit` | Apartment, suite, or unit | | `PERSONAL.address` | `PERSONAL.address.po_box` | Post office box | ### Protected Information Protected class attributes relevant to Title VII and related regulations. | Parent Label | Element Label | Description | | --------------- | --------------------------- | ---------------------------------------------------------------- | | `PROTECTED` | `PROTECTED.race_ethnicity` | Race or ethnicity | | `PROTECTED` | `PROTECTED.religion` | Religious affiliation | | `PROTECTED` | `PROTECTED.sex` | Sex-related attribute when a more specific label is not returned | | `PROTECTED.sex` | `PROTECTED.sex.pregnancy` | Pregnancy status | | `PROTECTED.sex` | `PROTECTED.sex.orientation` | Sexual orientation | | `PROTECTED.sex` | `PROTECTED.sex.gender` | Gender or gender identity | | `PROTECTED` | `PROTECTED.national_origin` | National origin | | `PROTECTED` | `PROTECTED.age` | Age | | `PROTECTED` | `PROTECTED.disability` | Disability status | | `PROTECTED` | `PROTECTED.genetic_info` | Genetic information | ### Government Information Government-issued identifiers. Country-specific passport variants are consolidated into `GOVERNMENT.passport`. | Parent Label | Element Label | Description | | ------------ | ---------------------------- | ---------------------------------------------------------------- | | `GOVERNMENT` | `GOVERNMENT.ssn` | Social Security Number, including partial SSNs | | `GOVERNMENT` | `GOVERNMENT.ein` | Employer Identification Number or Taxpayer Identification Number | | `GOVERNMENT` | `GOVERNMENT.passport` | Passport number | | `GOVERNMENT` | `GOVERNMENT.drivers_license` | Driver's license number | | `GOVERNMENT` | `GOVERNMENT.license_plate` | License plate number | | `GOVERNMENT` | `GOVERNMENT.national_id` | National identity number | | `GOVERNMENT` | `GOVERNMENT.vin` | Vehicle Identification Number | ### Payments Information (PCI) Payment card and banking identifiers. Partial card numbers share the same label as full card numbers; the classifier detects partial values contextually. | Parent Label | Element Label | Description | | ------------ | -------------------------- | -------------------------------------------------- | | `FINANCIAL` | `FINANCIAL.card_number` | Credit card number, including partial card numbers | | `FINANCIAL` | `FINANCIAL.card_expiry` | Credit card expiration date | | `FINANCIAL` | `FINANCIAL.cvv` | Credit card CVV | | `FINANCIAL` | `FINANCIAL.routing_number` | Routing number | | `FINANCIAL` | `FINANCIAL.iban` | IBAN | | `FINANCIAL` | `FINANCIAL.swift` | SWIFT code | | `FINANCIAL` | `FINANCIAL.bank_account` | Bank account number | ### Health Information (PHI) Protected health information. | Parent Label | Element Label | Description | | ------------ | ---------------------- | ---------------------------------- | | `MEDICAL` | `MEDICAL.diagnosis` | Diagnosis | | `MEDICAL` | `MEDICAL.medication` | Medication | | `MEDICAL` | `MEDICAL.procedure` | Medical procedure | | `MEDICAL` | `MEDICAL.insurance_id` | Health insurance member identifier | | `MEDICAL` | `MEDICAL.mrn` | Medical record number | | `MEDICAL` | `MEDICAL.medical_code` | Medical code | | `MEDICAL` | `MEDICAL.provider_id` | Medical provider identifier | ### Secrets Authentication credentials and cryptographic material. | Parent Label | Element Label | Description | | ------------ | --------------------- | -------------------------------------- | | `SECRETS` | `SECRETS.password` | Password | | `SECRETS` | `SECRETS.api_key` | API key or service access key | | `SECRETS` | `SECRETS.private_key` | Private key or certificate-like secret | | `SECRETS` | `SECRETS.seed_phrase` | Seed phrase | | `SECRETS` | `SECRETS.token` | Authentication token | ### Technical Information System and network identifiers. | Parent Label | Element Label | Description | | ------------ | ------------------------ | -------------------------------------- | | `TECHNICAL` | `TECHNICAL.ip` | IP address | | `TECHNICAL` | `TECHNICAL.mac` | MAC address | | `TECHNICAL` | `TECHNICAL.url` | URL or website | | `TECHNICAL` | `TECHNICAL.account_id` | Account or device identifier | | `TECHNICAL` | `TECHNICAL.hostname` | Hostname | | `TECHNICAL` | `TECHNICAL.imei` | IMEI or device serial-style identifier | | `TECHNICAL` | `TECHNICAL.telemetry_id` | Telemetry identifier | ### Location Information Geographic and coordinate data. | Parent Label | Element Label | Description | | ------------ | ---------------------- | ---------------------------------------------- | | `LOCATION` | `LOCATION.country` | Country | | `LOCATION` | `LOCATION.state` | State or province | | `LOCATION` | `LOCATION.city` | City | | `LOCATION` | `LOCATION.postal_code` | Postal code or ZIP code | | `LOCATION` | `LOCATION.coordinates` | Latitude, longitude, or geographic coordinates | ### Organization Information Business and team entity identifiers. | Parent Label | Element Label | Description | | -------------- | ------------------------ | --------------------------------------- | | `ORGANIZATION` | `ORGANIZATION.org_name` | Organization, employer, or company name | | `ORGANIZATION` | `ORGANIZATION.team_name` | Team name | ### Reference Identifiers Universal reference identifiers. | Parent Label | Element Label | Description | | ------------ | ----------------------- | --------------------------------------- | | `REFERENCE` | `REFERENCE.case_id` | Case identifier | | `REFERENCE` | `REFERENCE.document_id` | Document identifier | | `REFERENCE` | `REFERENCE.locator` | Transaction or locator-style identifier | | `REFERENCE` | `REFERENCE.product_id` | Product identifier | ## V1 Mapping Reference | V1 Label | V2 Label | Change | | ------------------------------------------------------------------------------------------ | ---------------------------- | ----------------------- | | `email` | `PERSONAL.email` | Renamed | | `phone_number` | `PERSONAL.phone` | Renamed | | `first_name` | `PERSONAL.name.given` | Renamed | | `last_name` | `PERSONAL.name.family` | Renamed | | `name` | `PERSONAL.name` | Renamed | | `birthday`, `birthday_year`, `birthday_month`, `birthday_day` | `PERSONAL.dob` | Consolidated | | `street_address` | `PERSONAL.address.street` | Renamed | | `us_address` | `PERSONAL.address` | Consolidated | | `us_ssn`, `us_ssn_last_four` | `GOVERNMENT.ssn` | Consolidated | | `passport` variants | `GOVERNMENT.passport` | Consolidated | | `drivers_license` | `GOVERNMENT.drivers_license` | Exact match | | `ein`, `tin` | `GOVERNMENT.ein` | Consolidated | | `vin` | `GOVERNMENT.vin` | Exact match | | `license_plate`, `license_plate_number` | `GOVERNMENT.license_plate` | Renamed | | `credit_card`, `cc_last_four` | `FINANCIAL.card_number` | Consolidated | | `cc_expiration` | `FINANCIAL.card_expiry` | Renamed | | `cvv` | `FINANCIAL.cvv` | Exact match | | `aba_routing` | `FINANCIAL.routing_number` | Renamed | | `iban` | `FINANCIAL.iban` | Exact match | | `swift_code` | `FINANCIAL.swift` | Renamed | | `us_bank` | `FINANCIAL.bank_account` | Renamed | | `zipcode` | `LOCATION.postal_code` | Renamed | | `country` | `LOCATION.country` | Exact match | | `state` | `LOCATION.state` | Exact match | | `city` | `LOCATION.city` | Exact match | | `latitude`, `longitude`, `geo_coordinates`, `location` | `LOCATION.coordinates` | Consolidated | | `organization`, `employer` | `ORGANIZATION.org_name` | Consolidated | | `website` | `TECHNICAL.url` | Renamed | | `ip_address`, `ipv4`, `ipv6` | `TECHNICAL.ip` | Consolidated | | `mac_address` | `TECHNICAL.mac` | Renamed | | `device_id`, `account_id` | `TECHNICAL.account_id` | Consolidated | | `password` | `SECRETS.password` | Exact match | | `api_key`, `aws_access_key_id`, `aws_secret_access_key`, `gitapp_key`, `gcp_auth_cert_url` | `SECRETS.api_key` | Consolidated | | `github_auth_token`, `gitlab_key`, `jira_token`, `stripe_token`, `marqeta_token` | `SECRETS.token` | Consolidated | | `certificate` | `SECRETS.private_key` | Approximate | | `race` | `PROTECTED.race_ethnicity` | Renamed | | `gender` | `PROTECTED.sex.gender` | Renamed and moved to L3 | | `religion` | `PROTECTED.religion` | Exact match | | `age` | `PROTECTED.age` | Exact match | | `origin` | `PROTECTED.national_origin` | Renamed | | `transaction_id` | `REFERENCE.locator` | Approximate | | `prescription_number` | `MEDICAL.mrn` | Approximate | ## Labels No Longer Detected The following v1 labels do not have a v2 equivalent and are not returned by the classifier after migration: | V1 Label | Reason | | -------------------------------------------------------------------------------------- | ----------------------------------------- | | `height`, `weight` | Not PII-relevant | | `date`, `timestamp`, `calendar`, `appointment_date` | Too generic; dates are contextual | | `death_date` | Insufficient training signal | | `transaction`, `transaction_amount`, `transaction_date` | Not PII-relevant | | `transaction_vendor` | Use `ORGANIZATION.org_name` instead | | `monetary_amount`, `currency`, `salary`, `account_balance`, `loan_number`, `bank_name` | Not PII-relevant | | `cc_type` | Not PII-relevant | | `blood_type`, `diagnosis_date`, `admission_date`, `discharge_date` | Replaced by the expanded `MEDICAL` family | | `marital_status`, `language`, `occupation` | Not PII-relevant | | `middle_name`, `initials`, `title` | Covered by `PERSONAL.name` |