> 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`                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.teleskope.ai/specifications/data-elements/entity-taxonomy-v2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.