Skip to content

Parties Data Model

1. Executive Summary

Purpose

The parties domain provides the master identity layer for every individual and organization that participates in UTA's financial operations. All downstream entities — billing items, cash receipts, settlements, payments, tax withholding, and write-offs — reference the party tables as their single source of truth for "who." A party record can represent a client (artist, talent, creator), a buyer (studio, brand, network, platform), a contracted party or loanout company, a collection party, a deal participant (manager, lawyer, business manager, agent, accountant), or a UTA entity. A single party record can hold multiple roles simultaneously — for example, one organization might be both a buyer on one deal and a collection party on another.

Scope

Covered:

  • party — Master identity record for every person or organization
  • party_role — Tracks the functional types a party can serve (client, buyer, agent, etc.), effective-dated for historical tracking
  • party_bank_account — Links parties to bank accounts with payment method preferences and effective dating
  • party_addresses — N:M bridge linking parties to reusable address records
  • deal_party — Associates parties with specific deals, carrying commission structure (percentage or flat)
  • contact_method — Reusable contact information records (email, phone, fax, website) referenced by party and UTA entity bridge tables

Not covered (documented separately):


2. Data Model

2.1 Entity-Relationship Diagram

mermaid
erDiagram
    party ||--o{ party_role : "has roles"
    party ||--o{ party_bank_account : "has bank accounts"
    party ||--o{ party_addresses : "has addresses"
    party ||--o{ deal_party : "participates in deals"
    deal ||--o{ deal_party : "has participants"
    bank_account ||--o{ party_bank_account : "linked to parties"
    bank_account ||--o{ deal_party : "deal-level override"

    party {
        serial party_id PK
        varchar auth_party_id
        varchar first_name
        varchar last_name
        varchar company_name
        varchar full_name
        varchar display_name
        boolean active_ind
    }

    party_role {
        serial party_role_id PK
        integer party_id FK
        varchar party_role_type_cd
        date party_role_start_dt
        date party_role_end_dt
        boolean party_role_active_ind
    }

    party_bank_account {
        serial party_bank_account_id PK
        integer party_id FK
        varchar party_bank_type_cd
        integer bank_account_id FK
        date party_bank_account_start_dt
        date party_bank_account_end_dt
        boolean active_ind
        varchar preferred_payment_method
    }

    party_addresses {
        serial party_addresses_id PK
        integer party_id FK
        varchar party_addresses_type_cd
        boolean primary_ind
        varchar auth_address_id
    }

    deal_party {
        serial deal_party_id PK
        integer deal_id FK
        integer party_id FK
        varchar party_role_type_cd
        boolean deal_party_commission_flat_ind
        decimal deal_party_commission_perc
        decimal deal_party_commission_amt
        integer bank_account_id FK
    }

    deal {
        serial deal_id PK
        varchar deal_reference
        varchar deal_name
        date deal_start_dt
        date deal_end_dt
        boolean active_ind
    }

    bank_account {
        serial bank_account_id PK
        varchar bank_account_name
        varchar bank_account_routing_no
        varchar bank_account_no
        boolean active_ind
        varchar currency_cd
        varchar country_cd
        boolean is_uta_account
        varchar bank_id FK
    }

2.2 party

The master record for every individual or organization in the system. Referenced as a FK across billing items, settlements, payments, tax, write-offs, and more.

FieldTypeRequiredDefaultDescription
party_idserialYesAutoPrimary key. Referenced as FK across billing items, settlements, payments, tax, and more.
auth_party_idvarchar(36)NoExternal identity system identifier (UUID format). Used to correlate with upstream master-data systems.
first_namevarchar(500)NoIndividual's first name. Populated for person-type parties.
last_namevarchar(500)NoIndividual's last name. Populated for person-type parties.
company_namevarchar(500)NoOrganization name. Populated for company-type parties (loanouts, studios, agencies).
full_namevarchar(500)NoComputed or entered full name. Typically first_name + last_name for individuals or company_name for organizations.
display_namevarchar(500)NoThe name shown in user interfaces. May be a preferred name, stage name, or trade name.
active_indbooleanNoWhether the party is currently active. Inactive parties are excluded from new transactions but preserved for historical reference.

NOTE

The party table does not have a "type" discriminator column (e.g., individual vs. organization). The distinction is inferred from which name fields are populated (first_name/last_name for individuals, company_name for organizations) and from the party's roles in party_role.


2.3 party_role

Tracks the functional types a party can serve. A party may hold multiple roles concurrently (e.g., a party can be both a CLIENT and a LO loanout on different deals). Roles are effective-dated, enabling historical tracking.

FieldTypeRequiredDefaultDescription
party_role_idserialYesAutoPrimary key.
party_idintegerNoFK to party.party_id.
party_role_type_cdvarchar(50)NoCode master value from PARTY_ROLE_TYPE_CD. Identifies the role type. See Section 5.
party_role_start_dtdateNoDate the role became effective.
party_role_end_dtdateNoDate the role was terminated. NULL indicates the role is still active.
party_role_active_indbooleanNoWhether this role assignment is currently active.

IMPORTANT

The party_role_type_cd values come from the code_master reference table (type = PARTY_ROLE_TYPE_CD). The same code set is used in deal_party.party_role_type_cd to describe a party's role on a specific deal, but the two usages have subtly different semantics: party_role describes what a party is globally, while deal_party describes what role a party plays on a particular deal.


2.4 party_bank_account

Links a party to a bank account with payment method preferences. A party may have multiple bank accounts (e.g., checking and savings), each with its own effective period.

FieldTypeRequiredDefaultDescription
party_bank_account_idserialYesAutoPrimary key.
party_idintegerNoFK to party.party_id.
party_bank_type_cdvarchar(50)NoAccount type code from PARTY_BANK_TYPE_CD: CHECKING, SAVINGS, PRIMARY. See Section 5.
bank_account_idintegerNoFK to bank_account.bank_account_id. The actual bank account record containing routing/account numbers, currency, and country.
party_bank_account_start_dtdateNoDate this bank account link became effective.
party_bank_account_end_dtdateNoDate this bank account link was terminated. NULL indicates it is still current.
active_indbooleanNoWhether this party-bank link is currently active.
preferred_payment_methodvarchar(10)NoThe party's preferred payment delivery method for this account: WIRE or ACH. Drives the outbound payment service level selection. If no preference is set, the system defaults to ACH.

IMPORTANT

The preferred_payment_method directly controls whether the outbound payment system transmits via wire transfer or ACH. The payment processor reads this field from the beneficiary's active party_bank_account record to determine the service level for the bank request.

Referenced table: bank_account (FK target, documented inline for context)

FieldTypeRequiredDefaultDescription
bank_account_idserialYesAutoPrimary key.
bank_account_namevarchar(500)NoDescriptive name for the account (e.g., "John Smith Agency - Operating Account").
bank_account_routing_novarchar(500)NoABA routing number (US) or equivalent.
bank_account_novarchar(500)NoAccount number.
active_indbooleanNoWhether the bank account record is active.
currency_cdvarchar(50)NoCurrency of the account (e.g., USD, GBP, EUR).
country_cdvarchar(50)NoCountry code where the account is domiciled.
is_uta_accountbooleanNofalseDistinguishes UTA's own accounts from external party accounts.
uta_account_idintegerNoFK to account.account_id. Only populated when is_uta_account is true.
bank_idvarchar(20)NoFK to bank.bank_id. Identifies the banking institution. Used by the payment processor to select the correct bank adapter (CNB EASI Link, JPM/BofA ISO 20022).

2.5 party_addresses

An N:M bridge table linking parties to reusable address records. The address type and primary designation live on the bridge, not on the address itself — the same physical address can serve different purposes for different parties.

FieldTypeRequiredDefaultDescription
party_addresses_idserialYesAutoPrimary key.
party_idintegerNoFK to party.party_id.
party_addresses_type_cdvarchar(50)NoAddress purpose code from PARTY_ADDRESSES_TYPE_CD: HOME, WORK, BILLING. See Section 5.
primary_indbooleanNoWhether this is the party's primary address for the given type.
auth_address_idvarchar(36)NoExternal identity system identifier for the address record (UUID format). Used to correlate with upstream master-data systems.

NOTE

The party_addresses table does not directly FK to the address table in the current schema. The link between party_addresses and the physical address record is maintained through the external auth_address_id reference, which maps to an address in the upstream master-data system.

Referenced table: address (reusable address record, documented inline for context)

FieldTypeRequiredDefaultDescription
address_idserialYesAutoPrimary key.
address_line_1varchar(200)NoStreet address line 1.
address_line_2varchar(200)NoStreet address line 2 (suite, unit, floor).
address_line_3varchar(200)NoStreet address line 3 (additional info).
cityvarchar(100)NoCity or municipality.
state_provincevarchar(100)NoState, province, or region.
postal_codevarchar(20)NoPostal or ZIP code.
country_cdvarchar(10)NoISO country code.

2.6 deal_party

Associates parties with deals, carrying the commission structure that governs how revenue is divided. Each record represents one party's participation in one deal.

FieldTypeRequiredDefaultDescription
deal_party_idserialYesAutoPrimary key.
deal_idintegerNoFK to deal.deal_id. The deal this party participates in.
party_idintegerNoFK to party.party_id. The participating party.
party_role_type_cdvarchar(50)NoThe party's role on this specific deal (e.g., CLNT, LO, BUYER, Agent, Broker, Manager, Consultant). Values from PARTY_ROLE_TYPE_CD. See Section 5.
deal_party_commission_flat_indbooleanNotrue if commission is a flat dollar amount; false if percentage-based.
deal_party_commission_percdecimal(7,4)NoCommission percentage (when percentage-based). Example: 10.0000 = 10%. Populated instead of deal_party_commission_amt when deal_party_commission_flat_ind is false.
deal_party_commission_amtdecimal(15,2)NoCommission amount in dollars (when flat). Populated instead of deal_party_commission_perc when deal_party_commission_flat_ind is true.
bank_account_idintegerNoFK to bank_account.bank_account_id. The bank account to use for payments on this deal. Overrides the party's default bank account from party_bank_account.

IMPORTANT

Commission can be either percentage-based or flat, controlled by deal_party_commission_flat_ind:

  • Percentage-based (false): Use deal_party_commission_perc. The percentage is applied against the net amount.
  • Flat (true): Use deal_party_commission_amt. A fixed dollar amount regardless of deal value.

Only one of deal_party_commission_perc or deal_party_commission_amt should be populated, depending on the flag.

NOTE

The deal_party.bank_account_id is a direct FK to bank_account, not routed through party_bank_account. This allows deal-level bank account overrides without modifying the party's master bank account configuration.


2.7 contact_method

Reusable contact information records (email, phone, fax, website, etc.). Entity-specific bridge tables link owning entities to these rows, allowing multiple contact methods per entity. For UTA entities, the bridge table is uta_entity_contact_method. The purpose or label (e.g., "work", "personal", "billing") is stored on the bridge, not on contact_method itself.

FieldTypeRequiredDefaultDescription
contact_method_idserialYesAutoPrimary key. Referenced by bridge tables such as uta_entity_contact_method.
contact_method_type_cdvarchar(50)YesType discriminator from CONTACT_METHOD_TYPE_CD: EMAIL, PHONE, MOBILE, FAX, WEBSITE, OTHER. See Section 5.
contact_valuevarchar(500)YesThe actual contact information (e.g., an email address, phone number, or URL).

NOTE

Pure audit columns (created_by, created_dt, updated_by, updated_dt) and auto-generated primary keys are omitted from the field tables above unless they carry business meaning.


3. Status Lifecycle

3.1 Party Active/Inactive Status

The party.active_ind boolean controls whether a party can participate in new transactions.

StatusCodeDescriptionAllowed Transitions
ActivetrueParty is usable in new billing items, deal associations, settlements, and payments.→ Inactive (false)
InactivefalseParty is excluded from new transaction creation but preserved for historical reference. Existing records are unaffected.→ Active (true)
mermaid
stateDiagram-v2
    [*] --> Active : Party created
    Active --> Inactive : Deactivate
    Inactive --> Active : Reactivate

Transition: Active → Inactive

  • Trigger: User or system deactivates the party record.
  • Preconditions: None — deactivation is always permitted; existing records are not affected.
  • Side-effects: Party is excluded from new transaction lookups. Existing deal_party, party_role, and party_bank_account records remain in place. No cascade to downstream records.

Transition: Inactive → Active

  • Trigger: User or system reactivates the party record.
  • Preconditions: None.
  • Side-effects: Party becomes available again in new transaction creation.

3.2 Party Role Active/Inactive Status

The party_role.party_role_active_ind flag combined with effective dating (party_role_start_dt / party_role_end_dt) controls role validity.

StatusCodeDescriptionAllowed Transitions
Activetrue (end date NULL)Role is currently valid. Party holds this functional type.→ Ended (false, end date set)
Endedfalse (end date set)Role has been terminated. Historical record remains.
mermaid
stateDiagram-v2
    [*] --> Active : Role created
    Active --> Ended : End role (set end_dt)

Transition: Active → Ended

  • Trigger: User terminates the party's role assignment.
  • Preconditions: None.
  • Side-effects: party_role.party_role_end_dt set to the termination date; party_role.party_role_active_ind set to false. The party's other roles and master party.active_ind are not affected.

3.3 Party Bank Account Active/Inactive Status

The party_bank_account.active_ind flag combined with effective dating controls which bank account links are valid for payment processing.

StatusCodeDescriptionAllowed Transitions
Activetrue (end date NULL)Bank account link is current and eligible for payment processing.→ Inactive (false, end date set)
Inactivefalse (end date set)Bank account link has been terminated. Not eligible for new payments.
mermaid
stateDiagram-v2
    [*] --> Active : Bank account link created
    Active --> Inactive : Deactivate (set end_dt)

Transition: Active → Inactive

  • Trigger: User deactivates the bank account link (e.g., account closed or replaced).
  • Preconditions: None.
  • Side-effects: party_bank_account.party_bank_account_end_dt set to the deactivation date; party_bank_account.active_ind set to false. The preferred_payment_method on the active link drives the outbound payment service level — when the link is inactive, the payment processor must use another active link.

4. Validation & Database Constraints

Unique Constraints

TableConstraintColumnsBusiness Rule
party(none — no DB unique constraint)auth_party_idExpected to be unique when populated but not enforced at the database level. Application layer checks for existing auth_party_id before inserting.

Business Validation

  • Party name completeness: At minimum, display_name should be populated for UI rendering. For individuals, first_name and last_name are expected. For organizations, company_name is expected.
  • Duplicate role prevention: A party should not hold duplicate active roles of the same type. Application logic checks for an existing role before inserting: queries party_role filtered by party_id and party_role_type_cd to detect conflicts.
  • Role code validation: party_role.party_role_type_cd values are validated against the code_master table (type = PARTY_ROLE_TYPE_CD).
  • Duplicate bank account link prevention: Application logic prevents duplicate active links between the same party and bank account: queries party_bank_account filtered by party_id and bank_account_id to detect conflicts.
  • Payment method constraint: party_bank_account.preferred_payment_method must be WIRE or ACH when populated.
  • Primary address uniqueness: Only one address per party per type should have primary_ind = true. Enforced at the application level.
  • Address type validation: party_addresses.party_addresses_type_cd values are validated against the code_master table (type = PARTY_ADDRESSES_TYPE_CD).
  • Commission exclusivity: Either deal_party.deal_party_commission_perc or deal_party.deal_party_commission_amt should be populated, not both. Controlled by deal_party_commission_flat_ind.
  • Duplicate deal-party prevention: Application logic prevents the same party from holding the same role on the same deal: queries deal_party filtered by deal_id, party_id, and party_role_type_cd to detect conflicts.
  • Decimal precision: deal_party_commission_perc uses decimal(7,4). deal_party_commission_amt uses decimal(15,2).

5. Code Master Values

5.1 PARTY_ROLE_TYPE_CD

Used in party_role.party_role_type_cd and deal_party.party_role_type_cd.

CodeDescriptionBehavior / When Used
CLIENTClientThe represented talent/artist (global role in party_role).
CLNTClientClient role in deal-party context. Used in deal_party.party_role_type_cd.
BUYERBuyerStudio, brand, network, or platform purchasing services (global role).
BUYBuyerAlternate buyer code in deal-party context.
BUYRBuyerAlternate buyer code used in data import context.
AGENTAgentUTA agent responsible for the deal.
AGTAgentAlternate agent code.
LOLoanoutClient's loanout company (contracted party entity).
MGRManagerTalent manager.
PMPersonal ManagerPersonal manager.
MCManagement CompanyManagement company (personal manager entity).
ATTAttorneyLegal representative.
BMBusiness ManagerBusiness/financial manager.
ABMAccountant/Business ManagerCombined accountant and business manager.
ACCAccountantAccountant.
BABusiness AffairsBusiness affairs representative.
BPBusiness PartnerBusiness partner.
PRODProducerProducer.
PCProduction CompanyProduction company.
STUStudioStudio entity.
NETNetworkNetwork entity.
RECRecord CompanyRecord label.
PUBPublicistPublicist.
PRMPR/MediaPR and media representative.
AGCYAgencyAgency entity.
UTAUTAUTA internal entity.
UTAPUTA PackageUTA package deal marker.
UKFUK FEUUK Foreign Entertainers Unit marker.
OTHOtherCatch-all for roles not covered above.
PParticipantGeneral deal participant.

Default on creation: No default — role type must be specified.

NOTE

Some role codes overlap in meaning (e.g., CLIENT/CLNT, BUYER/BUY/BUYR, AGENT/AGT). This reflects data arriving from different source systems and import processes. The code_master table provides human-readable descriptions that resolve these to consistent labels in the UI.


5.2 PARTY_BANK_TYPE_CD

Used in party_bank_account.party_bank_type_cd.

CodeDescriptionBehavior / When Used
CHECKINGChecking AccountStandard checking account. Most common for outbound payments.
SAVINGSSavings AccountSavings account. Used when party's payment account is a savings account.
PRIMARYPrimary AccountGeneral-purpose primary account designation. Used when account type is not specified.

Default on creation: No default — bank type must be specified when creating the link.


5.3 PARTY_ADDRESSES_TYPE_CD

Used in party_addresses.party_addresses_type_cd.

CodeDescriptionBehavior / When Used
HOMEHome AddressPersonal residence for individual parties.
WORKWork AddressBusiness/office address.
BILLINGBilling AddressAddress used for billing and invoicing purposes.

Default on creation: No default — address type must be specified.


5.4 Preferred Payment Method

Used in party_bank_account.preferred_payment_method. Not stored in code_master; constrained to two values in the application layer.

CodeDescriptionBehavior / When Used
WIREWire TransferFunds transmitted via wire. Typically used for large or international payments. Selected by the outbound payment processor when this value is set.
ACHAutomated Clearing HouseElectronic bank transfer. Lower cost than wire; used for domestic payments. System default when preferred_payment_method is not set.

Default on creation: Defaults to ACH when not specified.


5.5 CONTACT_METHOD_TYPE_CD

Used in contact_method.contact_method_type_cd.

CodeDescriptionBehavior / When Used
EMAILEmail AddressElectronic mail address.
PHONEPhone NumberLandline or general phone number.
MOBILEMobile PhoneMobile/cell phone number.
FAXFax NumberFacsimile number.
WEBSITEWebsite URLWeb address.
OTHEROtherContact type not covered by the values above.

Default on creation: No default — contact method type must be specified.


6. Cross-References

DocumentRelationship
Billing Items Data Modelbilling_item.client_id, billing_item.contracted_party_id, billing_item.buyer_id, billing_item.collection_party_idparty.party_id. Four party roles on every billing item.
Settlements Data Modelparticipant_settlement_item.payment_party_idparty.party_id. Identifies the payee for each settlement payout. payment_item.client_id, payment_item.payment_party_id, payment_item.buyer_idparty.party_id.
Cash Receipts Data Modelbank_account identifies which UTA account received the funds. cash_receipt_client_ledger.client_id, client_ledger.client_idparty.party_id.
Tax Withholding Data Modelparty_tax_info.party_idparty.party_id. Tax profile is maintained per party. tax_form.party_idparty.party_id.
Write-Offs Data Modelwrite_off_packet.client_idparty.party_id. Identifies the client whose receivable is being written off.
Deals, Sales Items & Payment Terms Data Modeldeal_party.deal_iddeal.deal_id. Deal party commission and participation structure.
Assignments Data ModelResponsibility assignments use party hierarchy resolution (Deal → Client → Department) to find the responsible person.

Confidential. For internal use only.