Senzing Entity Specification

This document defines the Senzing Entity Specification — a detailed guide for mapping source data into Senzing’s entity resolution engine.

The process of mapping is taking a source field name, like CustomerName, and transforming it into a target field name, by applying specific rules, such as renaming, reformatting, or combining fields based on predefined logic or conditions. It’s like creating a bridge where data from one system is reshaped to fit the structure of another system, guided by those rules.

Key Terms

Entities, Features and Attributes:

• Entity — A real-world subject, primarily a PERSON or an ORGANIZATION, described by one record.
• Feature — A set of related attributes about the entity (e.g., NAME, ADDRESS, PHONE).
• Attribute — A single field within a feature (e.g., NAME_FIRST and NAME_LAST in NAME; ADDR_LINE1 in ADDRESS).

Usage types and payload (optional attributes)

• Usage Type — A short label that distinguishes multiple instances of the same feature on one entity (e.g., HOME vs MAILING address, MOBILE vs HOME phone, PRIMARY vs ALIAS name). It helps explain “which one it is” when there are several.
• Payload Attributes — These are attributes that are not used for matching, but can be helpful in understanding matches or making quick decisions. (e.g., STATUS: Active|Inactive, RISK_CATEGORY, INDUSTRY_CODE)

What Features to Map

Entity resolution works best when you have a name and as many other features as you can find. The more features on each record, the better the entity resolution! Below are feature lists to look for in your sources. Rank indicates typical importance to entity resolution.

Payload Attributes (Optional)

The full details about a record should exist in your source systems. Senzing holds the features needed for entity resolution and acts as a pointer system to where the full details of their record can be found.

Payload attributes are optional because they are not used in matching. However, they can help a human reviewer quickly triage a match and decide whether looking up the full record is warranted.

Here are some examples of useful payload attributes:

• STATUS: Active/Inactive helps triage quickly (e.g., ignore inactive duplicates; focus on active customers).
• CREATE_DATE (or FIRST_SEEN): Helps sort duplicates and spot fraud risk (e.g., a new record with conflicting identifiers vs. an older established one).
• INDUSTRY_CODE/INDUSTRY: Codes and labels from data providers that describe the business (e.g., NAICS/SIC).
• JOB_TITLE: Role/title from HR or data providers; can inform risk, especially when matched to a watchlist entry.
• RISK_CATEGORY/RISK_SCORE: Watchlist-derived codes/scores that explain the type and severity of risk.

Performance note:

• Payload increases storage and I/O. Include only when it materially improves downstream understanding. On very large systems, evaluate impact before enabling broadly.
• If you do decide to include them, keep them minimal and only include what helps a human understand matches or an algorithm to triage them.
• You may decide to map a few during a proof of concept while you are analyzing matches and then remove them when you go to production.

Recommended JSON Schema

In prior versions we allowed a flat JSON structure with a separate sub-list for each feature that had multiple values. While we still support that, we now recommend the following JSON schema that has just one list for all features. It is much cleaner, and if you standardize on it, you can write a single parser to extract values for downstream processes if needed.

Example (person)

{
    "DATA_SOURCE": "CUSTOMERS",
    "RECORD_ID": "1001",
    "FEATURES":
    [
        {
            "RECORD_TYPE": "PERSON"
        },
        {
            "NAME_TYPE": "PRIMARY",
            "NAME_LAST": "Smith",
            "NAME_FIRST": "Robert"
        },
        {
            "NAME_TYPE": "NICKNAME",
            "NAME_FULL": "Bobby Smith"
        },
        {
            "DATE_OF_BIRTH": "1978-12-11"
        },
        {
            "ADDR_TYPE": "HOME",
            "ADDR_LINE1": "123 Main Street",
            "ADDR_CITY": "Las Vegas",
            "ADDR_STATE": "NV",
            "ADDR_POSTAL_CODE": "89132"
        },
        {
            "ADDR_TYPE": "MAILING",
            "ADDR_FULL": "PO Box 19675, Las Vegas, NV 89111"
        },
        {
            "PHONE_TYPE": "HOME",
            "PHONE_NUMBER": "702-919-3211"
        },
        {
            "PHONE_TYPE": "MOBILE",
            "PHONE_NUMBER": "702-919-1300"
        },
        {
            "DRIVERS_LICENSE_NUMBER": "112233",
            "DRIVERS_LICENSE_STATE": "NV"
        },
        {
            "EMAIL_ADDRESS": "bsmith@work.com"
        },
        {
            "REL_ANCHOR_DOMAIN": "CUSTOMERS",
            "REL_ANCHOR_KEY": "1001"
        },
        {
            "REL_POINTER_DOMAIN": "CUSTOMERS",
            "REL_POINTER_KEY": "ORG1001",
            "REL_POINTER_ROLE": "EMPLOYED_BY"
        }
    ],
    "CREATE_DATE": "2020-06-15",
    "STATUS": "Active"
}

Example (organization)

{
    "DATA_SOURCE": "CUSTOMERS",
    "RECORD_ID": "ORG1001",
    "FEATURES":
    [
        {
            "RECORD_TYPE": "ORGANIZATION"
        },
        {
            "NAME_ORG": "Acme Corporation"
        },
        {
            "ADDR_TYPE": "BUSINESS",
            "ADDR_FULL": "500 Industrial Way, Austin, TX 78701, US"
        },
        {
            "PHONE_NUMBER": "+1-512-555-2000"
        },
        {
            "EMAIL_ADDRESS": "info@acme.example"
        },
        {
            "LEI_NUMBER": "5493001KJTIIGC8Y1R12"
        },
        {
            "TAX_ID_TYPE": "EIN",
            "TAX_ID_NUMBER": "12-3456789",
            "TAX_ID_COUNTRY": "US"
        },
        {
            "WEBSITE_ADDRESS": "https://www.acme.example"
        },
        {
            "REL_ANCHOR_DOMAIN": "CUSTOMERS",
            "REL_ANCHOR_KEY": "ORG1001"
        }
    ],
    "NAICS_CODE": "541511",
    "COMPANY_TYPE": "Corporation"
}

Schema Validation Rules

• Root keys
  • DATA_SOURCE (required, string): short, stable code naming the source system.
  • RECORD_ID (recommended, string): unique within the DATA_SOURCE; used for add/replace.
  • FEATURES (required, array): the only array allowed at root.
    • Contains only feature objects. Each object represents one instance of a feature’s attributes
    • All attributes in a feature object must belong to the same feature
  • Optional root level attributes (Payload Attributes)
    • Must not be a registered feature attribute
    • Must be a scalar object (string, number, boolean), Not an array or nested object
  • Only registered feature attributes may appear inside feature objects. See “Registered Feature Attributes” below for the complete list and guidance.

Note: If exporting Senzing JSON records to a file its best to flatten them to create an easy to consume JSONL file.

Source Schema Types

Sources vary — CSV/TSV and relational tables, JSON/JSONL, XML, Parquet, and graph exports.

Unified terms (applies to all sources)

• Master entity: the master person or organization record (a master table row, a graph node, or a top‑level JSON/XML object). One master → one Senzing entity document.
• Identifying attributes: the attributes that identify/describe the entity (names, addresses, phones, emails, identifiers, websites, etc.). These may appear on the master itself or inside child lists/structures.
• Child lists: one‑to‑many data linked to the master. Depending on source, these appear as separate tables, JSON arrays under the master object, repeated XML elements, Parquet list columns, or graph attribute nodes. Usually each child record represents one (name, address, phone, identifier, etc.) and contains a type such as alias or dba for a name, home, mailing etc for an address, drivers license, passport, tax_id, etc for an identifier.
• Disclosed relationships: links between source records (masters) (person↔org, person↔person, org↔org). Depending on source, these appear as link/bridge tables, foreign keys to other master IDs, JSON pointers, XML references, Parquet join keys, or graph edges.

Format notes (how to spot masters, children, and disclosed relationships)

• CSV/TSV/Relational: master tables for persons/organizations; child tables for names, addresses, phones, identifiers; link tables for relationships. Join on primary/foreign keys; each child row → one feature object.
• JSON/JSONL: master object per entity; child lists are arrays on the master (e.g., names, addresses, phones, ids). Flatten each array element into a separate feature object. Nested objects representing a single value map to a single feature; arrays map to multiple features.
• XML: master element per entity; child lists are repeated child elements; attributes may be XML attributes or elements. Treat repeated elements like JSON arrays: one repeated element → one feature object. Extract scalar values only inside a feature.
• Parquet: when normalized across files, treat like relational; when a single file contains list/struct columns on the master row, treat list as child lists (one struct → one feature) and struct as a single feature’s values. Join across Parquet datasets on keys where needed.
• Graph: nodes representing persons or organizations are master entities; edges from a master to attribute nodes (e.g., address, phone, email, identifiers) represent features; edges between master nodes represent disclosed relationships.

How to Map Them

• Master entity: each person/org row, node, or top‑level object → one Senzing record; include RECORD_TYPE (PERSON/ORGANIZATION) when known.
• Features: collect identifying attributes from the master and child lists/structures (tables, arrays/repeated elements, list, property nodes) and group them into features — NAME_*, ADDR_*, PHONE_*, PASSPORT_*, etc.
• Disclosed relationships: map links/edges/foreign keys between source records (masters) using REL_* features.
• Output: emit one JSON record per master entity with all FEATURES (attributes and disclosed relationships) included.
• For records that reference entities without unique keys (e.g., sender and receiver on transactions), extract identifying attributes and compute a deterministic RECORD_ID as a hash of normalized values. Stamp this ID on the source record before mapping to Senzing, and track these IDs on the source side as well.
• For records that have features that clearly do not belong to the primary entity (e.g., employer name and address on a contact list, reference name and phone number on a job application), consider creating a second entity related to the primary entity.
• Use a stable normalization recipe (fixed fields and order; trim/collapse whitespace; case‑fold; normalize punctuation/diacritics) before hashing.

General mapping guidance

The following sections cover how Senzing treats record updates versus replacements, usage types, and identifier mapping.

Important: Decisions in this section affect matching behavior and whether records break or reinforce matches. Coordinate changes carefully and validate with sample runs.

• Updating vs Replacing determines which features are present at match time (no hidden history in Senzing).
• Usage types with special meaning (PRIMARY/BUSINESS/MOBILE) influence display/weighting.
• Identifier choices (specific vs NATIONAL_ID/TAX_ID/OTHER_ID) control break/no‑break behavior.

Updating vs Replacing Records

Senzing always replaces records. It keeps governance and interpretation clear, avoids storing stale or unknown history in Senzing, and respects data‑provider and watchlist contracts that often forbid retaining prior values. It is also impossible for Senzing alone to know whether a prior address was corrected vs. a move, or whether a missing phone was removed on purpose.

Guidance

• Present all features you wish to retain (including historical values) in a single JSON record at update time.
• If the source keeps feature history, map that history as additional FEATURES.
• If the source lacks history, you may maintain your own small history table (DATA_SOURCE, RECORD_ID, FEATURE type, feature JSON) and merge as needed when producing the new record.

Mapping Usage Types

Senzing matches across usage types because they are not well standardized and are often mislabeled across systems. Therefore, map usage types primarily for reference. However, three usage types do have special meaning that influences display or weighting.

Guidance

• Only include usage types when the source clearly provides them.
• Special meanings that influence resolution/display:
  • NAME_TYPE PRIMARY: Used to choose the best display name when multiple names exist.
  • ADDR_TYPE BUSINESS (organizations): Adds weight to an organization’s physical location.
  • PHONE_TYPE MOBILE: Adds weight to personal mobile numbers.

Mapping Identifiers

How identifiers arrive

• Direct fields: single columns like SSN, LICENSE_NO, TIN, EIN, LEI, etc.
• Child/type table: rows with id_type, id_number, and sometimes id_country or issuer (e.g., codes such as SSN, DRIVERS LICENSE, TIN).

Classification workflow (stop at first match)

1. Specific identifier

   • SSN → SSN
   • Passport → PASSPORT + PASSPORT_COUNTRY
   • Driver’s License → DRLIC + DRIVERS_LICENSE_STATE
   • LEI → LEI_NUMBER
   • DUNS → DUNS_NUMBER
   • NPI → NPI_NUMBER

2. Tax-related identifier

   • VAT, TIN, INN, EIN/FEIN, other tax codes
   • Map to TAX_ID + TAX_ID_TYPE + TAX_ID_COUNTRY

3. Country-issued national identifier

   • Unique per person/org within a country (e.g., CEDULA, SIREN, OGRN)
   • Map to NATIONAL_ID + NATIONAL_ID_TYPE + NATIONAL_ID_COUNTRY

4. Unknown code? Research first

   • Look up the token; confirm whether it is tax, national, or organization-issued (e.g., LEI).
   • Maintain and consult a local crosswalk. Add aliases and verified findings to keep decisions consistent.

5. Everything else (last resort)

   • Only if it is truly an identifier and not covered above: OTHER_ID + OTHER_ID_TYPE [+ OTHER_ID_COUNTRY when relevant].
   • Do not default to OTHER_ID without research (see “dumping-ground” warning below).

Required context

• Always include issuer to scope uniqueness (e.g., PASSPORT_COUNTRY, DRIVERS_LICENSE_STATE, TAX_ID_COUNTRY). See “Identifiers → Principles” for uniqueness and issuer guidance.

Beware “dumping‑ground” identifier tables

• Some sources use code-driven “identifier” tables for anything lacking a dedicated field. You may encounter document dates (e.g., birth-certificate dates), risk categories/statuses, or free-text notes. Do not map these as identifiers (including OTHER_ID). Route to a registered feature when appropriate; otherwise use payload attributes or omit when no meaningful, spec-compliant placement exists.

Common identifier mappings reference

Mapping Group Associations (small groups only)

Purpose

• Use Group Associations only when the group is small and specific, materially narrowing the population.
• Intended for sparse data scenarios — when a person/organization is known primarily by a small group affiliation.

Use when the group is small/specific

• Examples: OWNER_EXEC of a company; BOARD_MEMBER of “ACME Corp”; CHAPTER_OFFICERS for “Local Chapter 42”; PROJECT_TEAM “AML 2024”; ALUMNI_COHORT “CS 2008”.
• Provide both a precise type and a specific group/organization name.

Do not use for large/generic populations

• Not acceptable: political parties (e.g., REPUBLICAN, DEMOCRAT), religions, national populations, country/state “residents”, mega social networks, extremely large unions or programs.
• Do not encode broad categories like “EMPLOYEE” as a group association unless the subgroup is small and well‑bounded.

Examples

• Good: GROUP_ASSOCIATION_TYPE=OWNER_EXEC; GROUP_ASSOCIATION_ORG_NAME=“ACME Corp”
• Bad: GROUP_ASSOCIATION_TYPE=POLITICAL_PARTY; GROUP_ASSOCIATION_ORG_NAME=“Democratic Party”
• Bad: GROUP_ASSOCIATION_TYPE=RESIDENTS; GROUP_ASSOCIATION_ORG_NAME=“United States”

Notes

• Group Associations are optional and have limited utility; prefer them only when they add discriminative power in sparse contexts.

Disclosed Relationship Mapping Guidance

What it is

• Disclosed relationships connect source records (masters), not features.
• Common pairs and examples:
  • Person ↔ Person: familial (e.g., SPOUSE_OF, SON_OF, FATHER_OF)
  • Person ↔ Organization: employment/ownership (e.g., EMPLOYED_BY, PRINCIPAL_OF, OWNER_OF)
  • Organization ↔ Organization: corporate hierarchy (e.g., BRANCH_OF, DIRECT_PARENT, ULTIMATE_PARENT)
• Extensible: if you add new RECORD_TYPEs (e.g., VEHICLE, VESSEL), apply the same pattern (e.g., OWNS_VESSEL, OPERATES_VEHICLE).

Direction and roles (how to assign anchor vs pointer)

• Single rule: the record doing the pointing holds REL_POINTER_*; the record being pointed to holds REL_ANCHOR_*.
• Role-driven direction examples:
  • EMPLOYED_BY: Person → Organization (person has REL_POINTER; organization has REL_ANCHOR)
  • BRANCH_OF: Branch org → Parent org (branch has REL_POINTER; parent has REL_ANCHOR)
  • PRINCIPAL_OF: Person → Organization (person has REL_POINTER; organization has REL_ANCHOR)
  • OWNER_OF: Person → Organization (person has REL_POINTER; organization has REL_ANCHOR)
  • DIRECT_PARENT: Parent org → Child org (parent has REL_POINTER; child has REL_ANCHOR)
  • ULTIMATE_PARENT: Top-level parent → Subsidiary (top-level has REL_POINTER; subsidiary has REL_ANCHOR)
  • SPOUSE_OF`: Often symmetric; emitting a single direction is acceptable if that’s what your source provides.
  • SON_OF / FATHER_OF (directional verbs): Follow the verb — SON_OF means child → parent; FATHER_OF means parent → child.

Anchors: avoid second passes

• Place at most one REL_ANCHOR on any record that could be a target of relationships.
• It’s safe and recommended to add REL_ANCHOR proactively (even if pointers aren’t known yet) so no second pass is required.

Model (anchor ↔ pointer)

• Anchor (target): add one REL_ANCHOR feature object; never more than one per record.
• Pointer (source): for each disclosed relationship leaving this record, add one REL_POINTER feature object with a role.
• Do not mix REL_ANCHOR_* and REL_POINTER_* keys in the same feature object.

Required fields

• Anchor: REL_ANCHOR_DOMAIN, REL_ANCHOR_KEY (uniquely identifies the target record).
• Pointer: REL_POINTER_DOMAIN, REL_POINTER_KEY, REL_POINTER_ROLE (e.g., SPOUSE_OF, SON_OF, FATHER_OF, EMPLOYED_BY, PRINCIPAL_OF, OWNER_OF, BRANCH_OF, DIRECT_PARENT, ULTIMATE_PARENT; standardize roles for filtering and display).

Map from common source shapes

• Link/bridge table: each link row → one REL_POINTER on the source record; ensure the target record has one REL_ANCHOR.
• Foreign key on a master: the record with the FK gets a REL_POINTER; the referenced record gets a REL_ANCHOR.
• JSON/XML references: treat object references as links; emit REL_POINTER on the referencing record and REL_ANCHOR on the referenced record.

Domain and key

• Prefer REL_*_DOMAIN = DATA_SOURCE and REL_*_KEY = RECORD_ID of the target record (or a stable link‑registry domain/key if you use one).
• Keys must be unique within the domain; keep formats stable and deterministic.

Cardinality and integrity

• One anchor per record (max). Zero or more pointers per record.
• One relationship → one REL_POINTER object (multiple relationships → multiple objects).
• Validate that every REL_POINTER object matches a REL_ANCHOR object on another record.

Examples

• EMPLOYED_BY (Person → Organization)

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "P1001",
  "FEATURES": [
    { "REL_POINTER_DOMAIN": "CUSTOMERS", "REL_POINTER_KEY": "ORG1001", "REL_POINTER_ROLE": "EMPLOYED_BY" }
  ]
}

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "ORG1001",
  "FEATURES": [
    { "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "ORG1001" }
  ]
}

• BRANCH_OF (Branch Org → Parent Org)

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "ORG2001",
  "FEATURES": [
    { "REL_POINTER_DOMAIN": "CUSTOMERS", "REL_POINTER_KEY": "ORG1001", "REL_POINTER_ROLE": "BRANCH_OF" }
  ]
}

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "ORG1001",
  "FEATURES": [
    { "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "ORG1001" }
  ]
}

• SON_OF / FATHER_OF (reciprocal pointers when provided)

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "PER1001",
  "FEATURES": [
    { "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "PER1001" },
    { "REL_POINTER_DOMAIN": "CUSTOMERS", "REL_POINTER_KEY": "PER1002", "REL_POINTER_ROLE": "SON_OF" }
  ]
}

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "PER1002",
  "FEATURES": [
    { "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "PER1002" },
    { "REL_POINTER_DOMAIN": "CUSTOMERS", "REL_POINTER_KEY": "PER1001", "REL_POINTER_ROLE": "FATHER_OF" }
  ]
}

Note: Each target record should also carry a single REL_ANCHOR (see pattern above).

See also

• Full field definitions and examples: Feature: REL_ANCHOR and Feature: REL_POINTER later in this spec.

Registered Feature Attributes

Attributes for the Record Key

These attributes tie records in Senzing back to your source system. Place them at the root of each JSON record.

Example

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "1001",
}

Feature: RECORD_TYPE

Importance: High

Example

{
  "FEATURES": [
    { "RECORD_TYPE": "PERSON" }
  ]
}

Tips for adding RECORD_TYPEs

• If you choose to add RECORD_TYPE, pick values that make sense for visualization too (e.g., a value that can map to a graph icon/shape).
• Avoid role labels as RECORD_TYPE (EMPLOYEE, VENDOR, CUSTOMER). Use intrinsic types (PERSON, ORGANIZATION) to preserve cross‑type resolution.
• Many watchlists have standardized on values such as VESSEL and AIRCRAFT. You do not need to register these in Senzing to use them as RECORD_TYPE.
• If you add such types, also include their appropriate identifiers as FEATURES so matching remains effective (e.g., IMO_NUMBER, CALL_SIGN for vessels; AIRCRAFT_TAIL_NUMBER for aircraft).

Name

Feature: NAME

Importance: High

Rules

• Prefer parsed person names (NAME_FIRST/NAME_LAST/…) when available; use NAME_ORG for organizations; use NAME_FULL only when the type is unknown or only a single field exists.
• Keep each NAME feature object internally consistent: do not mix NAME_FULL with parsed name fields in the same object; do not mix NAME_ORG with parsed person fields in the same object.
• Use NAME_TYPE only when provided by the source (e.g., PRIMARY, AKA, DBA).
• When multiple names exist, NAME_TYPE=PRIMARY is special: it determines the best display name for the resolved entity (prefer PRIMARY over AKA).

Examples

• ✅ Person (parsed)

{
  "FEATURES": [
    { "NAME_FIRST": "Robert", "NAME_LAST": "Smith", "NAME_MIDDLE": "A" }
  ]
}

• ✅ Organization

{
  "FEATURES": [
    { "NAME_ORG": "Acme Tire Inc.", "NAME_TYPE": "PRIMARY" }
  ]
}

• ✅ Unknown type

{
  "FEATURES": [
    { "NAME_FULL": "Robert J Smith, Trust" }
  ]
}

• ❌ Incorrect (split across multiple NAME objects)

{
  "FEATURES": [
    { "NAME_LAST": "Smith" },
    { "NAME_FIRST": "Robert" }
  ]
}

• ❌ Incorrect (mixing NAME_ORG with parsed person fields)

{
  "FEATURES": [
    { "NAME_ORG": "Acme Tire Inc.", "NAME_FIRST": "Robert" }
  ]
}

Contact methods

Feature: ADDRESS

Importance: High

Rules

• Prefer parsed address fields when available (ADDR_LINE1..ADDR_LINE6, ADDR_CITY, ADDR_STATE, ADDR_POSTAL_CODE, ADDR_COUNTRY).
• Use ADDR_FULL only when parsed components are unavailable.
• Do not mix ADDR_FULL with parsed address fields in the same object.
• For organizations, assign ADDR_TYPE=BUSINESS to at least one address when known (adds weight to the physical location).

Examples

• ✅ Parsed address

{
  "FEATURES": [
    { "ADDR_TYPE": "HOME", "ADDR_LINE1": "111 First St", "ADDR_CITY": "Las Vegas", "ADDR_STATE": "NV", "ADDR_POSTAL_CODE": "89111" }
  ]
}

• ✅ Single-field address

{
  "FEATURES": [
    { "ADDR_TYPE": "MAILING", "ADDR_FULL": "3 Underhill Way, Las Vegas, NV 89101, US" }
  ]
}

• ❌ Incorrect (mixing ADDR_FULL with parsed fields)

{
  "FEATURES": [
    { "ADDR_FULL": "123 Main St, Las Vegas, NV 89132", "ADDR_CITY": "Las Vegas" }
  ]
}

Feature: PHONE

Importance: Medium

Rules

• Include PHONE_TYPE only when the source provides it (MOBILE carries extra weight).
• One PHONE object per number; represent multiple numbers as multiple PHONE objects.
• Do not put a list of numbers inside a single PHONE object.
• When a source uses clear prefixes (e.g., HOME_PHONE), you may derive PHONE_TYPE from the prefix.

Examples

{
  "FEATURES": [
    { "PHONE_TYPE": "MOBILE", "PHONE_NUMBER": "702-555-1212" },
    { "PHONE_NUMBER": "702-555-3434" }
  ]
}

Feature: EMAIL

Importance: Medium

Example

{
  "FEATURES": [
    { "EMAIL_ADDRESS": "alex@example.com" }
  ]
}

Physical and other characteristics

Feature: GENDER

Importance: Low-Medium

Example

{
  "FEATURES": [
    { "GENDER": "F" }
  ]
}

Feature: DOB (Date of Birth)

Importance: High

Examples

{
  "FEATURES": [
    { "DATE_OF_BIRTH": "1980-05-14" }
  ]
}

Feature: DOD (Date of Death)

Importance: Low-Medium

Example

{
  "FEATURES": [
    { "DATE_OF_DEATH": "2010-05-14" }
  ]
}

Feature: NATIONALITY

Importance: Low

Example

{
  "FEATURES": [
    { "NATIONALITY": "US" }
  ]
}

Feature: CITIZENSHIP

Importance: Low

Example

{
  "FEATURES": [
    { "CITIZENSHIP": "US" }
  ]
}

Feature: POB (Place of Birth)

Importance: Low

Example

{
  "FEATURES": [
    { "PLACE_OF_BIRTH": "Chicago, IL" }
  ]
}

Feature: REGISTRATION_DATE (Organizations)

Importance: Low-Medium

Example

{
  "FEATURES": [
    { "REGISTRATION_DATE": "2010-05-14" }
  ]
}

Feature: REGISTRATION_COUNTRY (Organizations)

Importance: Low

Example

{
  "FEATURES": [
    { "REGISTRATION_COUNTRY": "US" }
  ]
}

Identifiers

Feature: PASSPORT

Importance: High

Example

{
  "FEATURES": [
    { "PASSPORT_NUMBER": "123456789", "PASSPORT_COUNTRY": "US" }
  ]
}

Feature: DRLIC (Driver’s License)

Importance: High

Example

{
  "FEATURES": [
    { "DRIVERS_LICENSE_NUMBER": "112233", "DRIVERS_LICENSE_STATE": "NV" }
  ]
}

Feature: SSN (US Social Security Number)

Importance: High

Example

{
  "FEATURES": [
    { "SSN_NUMBER": "123-12-1234" }
  ]
}

Feature: NATIONAL_ID

Importance: High

Rules

• If the source type cannot be standardized and NATIONAL_ID_COUNTRY is present, leave NATIONAL_ID_TYPE blank.

Good/Bad

• ✅ Good

{
  "FEATURES": [
    { "NATIONAL_ID_TYPE": "SIREN", "NATIONAL_ID_NUMBER": "552081317", "NATIONAL_ID_COUNTRY": "FR" }
  ]
}

• ❌ Bad (SSN mapped as NATIONAL_ID)

{
  "FEATURES": [
    { "NATIONAL_ID_TYPE": "SSN", "NATIONAL_ID_NUMBER": "123-12-1234" }
  ]
}

Feature: TAX_ID

Importance: High

Rules

• If the source type cannot be standardized and TAX_ID_COUNTRY is present, leave TAX_ID_TYPE blank.

Good/Bad

• ✅ Good

{
  "FEATURES": [
    { "TAX_ID_TYPE": "EIN", "TAX_ID_NUMBER": "12-3456789", "TAX_ID_COUNTRY": "US" }
  ]
}

• ❌ Bad (EIN as NATIONAL_ID)

{
  "FEATURES": [
    { "NATIONAL_ID_TYPE": "EIN", "NATIONAL_ID_NUMBER": "12-3456789", "NATIONAL_ID_COUNTRY": "US" }
  ]
}

Feature: OTHER_ID

Importance: Medium

• Use OTHER_ID sparingly; Prefer adding a specific feature for frequently used non‑country identifiers so matching behavior can be adjusted.
• Do NOT use OTHER_ID for values that are not unique to an entity within the domain.

Good/Bad

• ✅ Good

{
  "FEATURES": [
    { "OTHER_ID_TYPE": "ISIN", "OTHER_ID_NUMBER": "123121234" }
  ]
}

• ❌ Bad (Category as an Identifier)

{
  "FEATURES": [
    { "OTHER_ID_TYPE": "SDN Type", "OTHER_ID_NUMBER": "Sanctions List" }
  ]
}

• ❌ Bad (Date as an Identifier)

{
  "FEATURES": [
    { "OTHER_ID_TYPE": "Certificate date", "OTHER_ID_NUMBER": "12/11/1980" }
  ]
}

Feature: ACCOUNT

Importance: Medium

Example

{
  "FEATURES": [
    { "ACCOUNT_NUMBER": "1234-1234-1234-1234", "ACCOUNT_DOMAIN": "VISA" }
  ]
}

Feature: DUNS_NUMBER

Importance: Medium

Example

{
  "FEATURES": [
    { "DUNS_NUMBER": "123123" }
  ]
}

Feature: NPI_NUMBER

Importance: Medium

Example

{
  "FEATURES": [
    { "NPI_NUMBER": "123123" }
  ]
}

Feature: LEI_NUMBER

Importance: Medium

Example

{
  "FEATURES": [
    { "LEI_NUMBER": "123123" }
  ]
}

Website and social media attributes

Feature: WEBSITE

Importance: Low

Example

{
  "FEATURES": [
    { "WEBSITE_ADDRESS": "acmetire.com" }
  ]
}

Features for Social Media Handles

Importance: Medium

Social handle features use the feature name as the attribute name.

Rules

• Normalize values: store the canonical handle/ID, not a full URL. Strip http(s)://, www., trailing slashes, query params, and a leading @.

• One handle per object: add one FEATURES object per platform handle; do not concatenate multiple handles.

• Prefer handle/ID over URL: if only a profile URL is provided, extract the handle/ID.

• Don’t use content links: skip post/status URLs; only capture profile-level handles/IDs.

• Case handling: store handles lowercased for case‑insensitive platforms; preserve exact case if a platform is case‑sensitive.

• Phone‑based apps: when a handle is a phone number (e.g., WhatsApp, Signal, Viber), also map the number to PHONE in addition to the app‑specific feature.

• Persons vs organizations: map personal handles on person records and brand handles on organization records when known; avoid crossing them.

• Stability: handles can change; use alongside stronger identifiers (email, phone, gov IDs).

• Platform specifics

  • TWITTER (X): letters, numbers, underscores; length 1–15; case‑insensitive.
  • INSTAGRAM: letters, numbers, periods, underscores; length 1–30; case‑insensitive.
  • TELEGRAM: letters, numbers, underscores; 5–32; case‑insensitive; strip t.me/.
  • LINKEDIN: prefer the public slug (e.g., in/jane-doe or company/acme); if only a URL is provided, extract the slug.

Example

{
  "FEATURES": [
    { "LINKEDIN": "in/john-smith" },
    { "TWITTER": "janedoe" }
  ]
}

Group Associations

See ‘Mapping Group Associations (small groups only)’ for guidance and examples.

Feature: EMPLOYER

Importance: Low-Medium

Rules

• When the source provides explicit employment relationships between person and organization records, prefer REL_POINTER/REL_ANCHOR to model the relationship; EMPLOYER can still be included for resolution.

Example

{
  "FEATURES": [
    { "EMPLOYER": "ABC Company" }
  ]
}

Feature: GROUP_ASSOCIATION

Importance: Low-Medium

Rules

• Provide GROUP_ASSOCIATION_TYPE to keep the group specific. Specific roles/groups (e.g., owners/executives of a company) are much smaller than the general population and therefore more discriminative.
• Only use when the group is small and specific; primarily useful in sparse data contexts.
• Do not set GROUP_ASSOCIATION for broad populations (e.g., political parties, religions, national populations, country/state residents, mega social networks).
• Provide a precise GROUP_ASSOCIATION_TYPE and a specific GROUP_ASSOCIATION_ORG_NAME.
• Example of discriminative power: the combination of a name with a small group (e.g., “George Washington” + “US President”) is far rarer than the name alone.

Example

{
  "FEATURES": [
    { "GROUP_ASSOCIATION_TYPE": "OWNER_EXEC", "GROUP_ASSOCIATION_ORG_NAME": "ABC Company" }
  ]
}

Feature: GROUP_ASSN_ID

Importance: Low-Medium

Rules

• Use when the group/organization has a registered identifier (e.g., DUNS). Include both type and number when available.

Example

{
  "FEATURES": [
    { "GROUP_ASSN_ID_TYPE": "COMPANY_ID", "GROUP_ASSN_ID_NUMBER": "12345" }
  ]
}

Disclosed relationships

See Disclosed Relationship Mapping Guidance above for model, direction, cardinality, and field‑population patterns.

Feature: REL_ANCHOR

Category: Relationship

Rules

• Include at most one REL_ANCHOR per record, only when other records will point to it.
• REL_ANCHOR identifies the target record for relationships using REL_ANCHOR_DOMAIN and REL_ANCHOR_KEY.
• Do not mix REL_ANCHOR and REL_POINTER attributes in the same feature object (separate objects in FEATURES are fine).
• Use a domain code without dashes to avoid confusion in downstream match key parsing.

Examples

{
  "FEATURES": [
    { "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "ACME-1001" }
  ]
}

• ❌ Incorrect (multiple REL_ANCHOR objects — only one allowed per record)

{
  "FEATURES": [
    { "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "ACME-1001" },
    { "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "ACME-2002" }
  ]
}

Feature: REL_POINTER

Category: Relationship

Rules

• Place REL_POINTER on the source record for each disclosed relationship to a target record.
• Provide REL_POINTER_DOMAIN and REL_POINTER_KEY to point to the target’s REL_ANCHOR; include a clear REL_POINTER_ROLE.
• Represent multiple relationships by adding multiple REL_POINTER objects in FEATURES (one per relationship).
• Do not mix REL_POINTER and REL_ANCHOR attributes in the same feature object.

Examples

{
  "FEATURES": [
    { "REL_POINTER_DOMAIN": "CUSTOMERS", "REL_POINTER_KEY": "ACME-1001", "REL_POINTER_ROLE": "EMPLOYED_BY" }
  ]
}

• ❌ Incorrect (mixing REL_ANCHOR and REL_POINTER attributes in the same object)

{
  "FEATURES": [
    { "REL_POINTER_DOMAIN": "CUSTOMERS", "REL_POINTER_KEY": "ACME-1001", "REL_POINTER_ROLE": "EMPLOYED_BY", "REL_ANCHOR_DOMAIN": "CUSTOMERS", "REL_ANCHOR_KEY": "ACME-1001" }
  ]
}

Feature: TRUSTED_ID

Category: Control

Two records with the same TRUSTED_ID type and number will absolutely force records together even if all their other features are different. Conversely, two records with a different TRUSTED_ID number of the same type will be forced apart even if all their other features are the same.

This feature can be used by data stewards to manually force records together or apart. It can also be used for a source system identifier that is so trusted you want it to never be overruled by Senzing.

Example

{
  "FEATURES": [
    { "TRUSTED_ID_TYPE": "STEWARD", "TRUSTED_ID_NUMBER": "1234-12345" }
  ]
}

Additional configuration

Senzing comes pre-configured with all the features, attributes, and settings you will likely need to begin resolving persons and organizations immediately. The only configuration that really needs to be added is what you named your data sources.

How to add a data source

In your Senzing project’s bin directory is an application called sz_configtool. Adding a new data source is as simple as registering the code you want to use for it.

sz_configtool.py  

Welcome to the Senzing configuration tool! Type help or ? to list commands

(szcfg) addDataSource `CUSTOMERS`

Data source successfully added!

(szcfg) save

Are you certain you wish to proceed and save changes? (y/n) y

Configuration changes saved!