random_corp/financial_crime/entities/contact_address.md

Financial Crime

Entities

Contact Address

A Contact Address is the association between a Party and a physical Address, qualified by purpose, verification status, and the period during which it was in use. It is not the address itself — the canonical physical location is held in the Address entity and reused across parties. Contact Address carries only the metadata that describes how and when a Party uses a given address.

This separation supports two critical financial crime capabilities. First, deduplication: if two parties share the same physical address, a single Address record exists and both Contact Address records point to it, enabling network analysis queries such as "which other parties are associated with this address". Second, temporal accuracy: the valid time period on Contact Address allows point-in-time queries — "what address did this party use at the time of this transaction" — which is essential for regulatory audit and SAR evidence.

A Party has Contact Addresses — it owns the association. A Party Role uses Contact Addresses — a role references which of the party's addresses applies for the specific purpose of that role. For example, the same Person may have a residential address used for identification and a mailing address used by their Customer role for correspondence.

---
config:
  layout: elk
---
classDiagram
  class ContactAddress{
    * Contact Address Identifier : string
    Address Purpose : enum~AddressPurpose~
    Is Primary : boolean
    Verification Status : enum~AddressVerificationStatus~
    Verification Date : date
    Verification Method : enum~VerificationMethod~
    Valid From : date
    Valid To : date
  }

  Party "1" --> "0..*" ContactAddress : has
  PartyRole "0..*" --> "0..*" ContactAddress : uses
  ContactAddress "0..*" --> "1" Address : references

  class AddressPurpose["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/enums.md#address-purpose'>Address Purpose</a>"]{<<enumeration>>}
  class AddressVerificationStatus["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/enums.md#address-verification-status'>Address Verification Status</a>"]{<<enumeration>>}
  class VerificationMethod["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/enums.md#verification-method'>Verification Method</a>"]{<<enumeration>>}

  class Party["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/entities/party.md'>Party</a>"]
  class PartyRole["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/entities/party_role.md'>Party Role</a>"]
  class Address["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/entities/address.md'>Address</a>"]

existence: associative
mutability: slowly_changing
temporal:
  tracking: valid_time
  description: >
    Valid time is carried explicitly as Valid From and Valid To attributes rather than relying on generated temporal columns. This allows future-dated address changes (e.g. recording a new address before a customer moves) and supports point-in-time queries for regulatory audit.
attributes:
  Contact Address Identifier:
    type: string
    identifier: primary
    description: >
      Globally unique surrogate identifier for this party-address association instance.

  Address Purpose:
    type: enum:Address Purpose
    description: >
      The purpose for which this address is used by the party. Determines regulatory significance — a Residential Address is required for individual identification under the AML/CTF Act 2006; a Registered Office Address is required for legal entity verification.

  Is Primary:
    type: boolean
    default: false
    description: >
      Indicates whether this is the party's primary contact address for the given purpose. A party may have only one primary address per Address Purpose at any point in time.

  Verification Status:
    type: enum:Address Verification Status
    description: >
      The current verification status of this address association. Unverified addresses must not be used as the sole basis for satisfying AML/CTF identification obligations. Expired verification must be renewed at the next CDD review.

  Verification Date:
    type: date
    description: >
      The date on which the address was most recently verified against an acceptable document or electronic source. Used to determine whether re-verification is required at periodic CDD review.

  Verification Method:
    type: enum:Verification Method
    description: >
      The method used to verify this address. Documentary verification requires an acceptable identity or address document. Electronic verification uses a third-party data source. In-person verification is performed at a branch or by a third party.

  Valid From:
    type: date
    description: >
      The date from which the party began using this address for the stated purpose. Establishes the start of the valid time period for point-in-time queries.

  Valid To:
    type: date
    description: >
      The date on which the party ceased using this address for the stated purpose. A null value indicates the address is currently in use. Closed associations must not be deleted — Valid To must be set to preserve address history for regulatory audit.

constraints:
  One Primary Per Purpose:
    check: >
      COUNT(Contact Address WHERE Party == this.Party
        AND Address Purpose == this.Address Purpose
        AND Is Primary == true
        AND (Valid To IS NULL OR Valid To >= Today)) <= 1
    description: >
      A party may have at most one primary Contact Address per Address Purpose
      at any point in time.

  Valid To After Valid From:
    check: "Valid To IS NULL OR Valid To > Valid From"
    description: >
      The end of the address validity period must be later than the start.

  Verification Date Required When Verified:
    check: >
      Verification Status != 'Verified'
      OR Verification Date IS NOT NULL
    description: >
      A Contact Address with a status of Verified must have a Verification
      Date recorded.

  Residential Required Before Activation:
    check: >
      EXISTS (Contact Address WHERE Party == this.Party
        AND Address Purpose == 'Residential'
        AND Verification Status == 'Verified')
    lifecycle_stage: Onboarding
    description: >
      An individual party must have at least one verified Residential Address
      before any designated service is provided. Required for identification
      under the AML/CTF Act 2006 Part B individual identification program.

governance:
  pii: true
  classification: Highly Confidential
  retention: 10 years
  retention_basis: Domain default retention aligned to AML/CTF record-keeping obligations
  description: >
    Address association records must be retained for 7 years from Valid To
    date, aligned to AUSTRAC and RBNZ record-keeping obligations. Records
    must never be deleted — closure via Valid To is the only permitted
    termination mechanism.
  access_role:
    - FINANCIAL_CRIME_ANALYST
    - KYC_OFFICER
    - COMPLIANCE_OFFICER
    - RELATIONSHIP_MANAGER
  compliance_relevance:
    - AUSTRAC AML/CTF Act 2006 — Part B address identification obligations
    - AUSTRAC AML/CTF Amendment Act 2024
    - RBNZ AML/CFT Act 2009 — section 14
    - FATF Recommendation 10 — Customer Due Diligence

Relationships

Contact Address References Address

Each Contact Address references exactly one canonical Address record.

source: Contact Address
type: references
target: Address
cardinality: many-to-one
granularity: atomic
ownership: Contact Address