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 organizationparty_role— Tracks the functional types a party can serve (client, buyer, agent, etc.), effective-dated for historical trackingparty_bank_account— Links parties to bank accounts with payment method preferences and effective datingparty_addresses— N:M bridge linking parties to reusable address recordsdeal_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):
- Worksheets, applications, payouts — see Worksheets Data Model
- Billing item party references (
client_id,buyer_id,contracted_party_id) — see Billing Items Data Model - Settlement payee references — see Settlements Data Model
- Tax profile per party (
party_tax_info) — see Tax Withholding Data Model - Deals and deal structure — see Deals, Sales Items & Payment Terms Data Model
2. Data Model
2.1 Entity-Relationship Diagram
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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
party_id | serial | Yes | Auto | Primary key. Referenced as FK across billing items, settlements, payments, tax, and more. |
auth_party_id | varchar(36) | No | — | External identity system identifier (UUID format). Used to correlate with upstream master-data systems. |
first_name | varchar(500) | No | — | Individual's first name. Populated for person-type parties. |
last_name | varchar(500) | No | — | Individual's last name. Populated for person-type parties. |
company_name | varchar(500) | No | — | Organization name. Populated for company-type parties (loanouts, studios, agencies). |
full_name | varchar(500) | No | — | Computed or entered full name. Typically first_name + last_name for individuals or company_name for organizations. |
display_name | varchar(500) | No | — | The name shown in user interfaces. May be a preferred name, stage name, or trade name. |
active_ind | boolean | No | — | Whether 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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
party_role_id | serial | Yes | Auto | Primary key. |
party_id | integer | No | — | FK to party.party_id. |
party_role_type_cd | varchar(50) | No | — | Code master value from PARTY_ROLE_TYPE_CD. Identifies the role type. See Section 5. |
party_role_start_dt | date | No | — | Date the role became effective. |
party_role_end_dt | date | No | — | Date the role was terminated. NULL indicates the role is still active. |
party_role_active_ind | boolean | No | — | Whether 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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
party_bank_account_id | serial | Yes | Auto | Primary key. |
party_id | integer | No | — | FK to party.party_id. |
party_bank_type_cd | varchar(50) | No | — | Account type code from PARTY_BANK_TYPE_CD: CHECKING, SAVINGS, PRIMARY. See Section 5. |
bank_account_id | integer | No | — | FK to bank_account.bank_account_id. The actual bank account record containing routing/account numbers, currency, and country. |
party_bank_account_start_dt | date | No | — | Date this bank account link became effective. |
party_bank_account_end_dt | date | No | — | Date this bank account link was terminated. NULL indicates it is still current. |
active_ind | boolean | No | — | Whether this party-bank link is currently active. |
preferred_payment_method | varchar(10) | No | — | The 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)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
bank_account_id | serial | Yes | Auto | Primary key. |
bank_account_name | varchar(500) | No | — | Descriptive name for the account (e.g., "John Smith Agency - Operating Account"). |
bank_account_routing_no | varchar(500) | No | — | ABA routing number (US) or equivalent. |
bank_account_no | varchar(500) | No | — | Account number. |
active_ind | boolean | No | — | Whether the bank account record is active. |
currency_cd | varchar(50) | No | — | Currency of the account (e.g., USD, GBP, EUR). |
country_cd | varchar(50) | No | — | Country code where the account is domiciled. |
is_uta_account | boolean | No | false | Distinguishes UTA's own accounts from external party accounts. |
uta_account_id | integer | No | — | FK to account.account_id. Only populated when is_uta_account is true. |
bank_id | varchar(20) | No | — | FK 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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
party_addresses_id | serial | Yes | Auto | Primary key. |
party_id | integer | No | — | FK to party.party_id. |
party_addresses_type_cd | varchar(50) | No | — | Address purpose code from PARTY_ADDRESSES_TYPE_CD: HOME, WORK, BILLING. See Section 5. |
primary_ind | boolean | No | — | Whether this is the party's primary address for the given type. |
auth_address_id | varchar(36) | No | — | External 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)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
address_id | serial | Yes | Auto | Primary key. |
address_line_1 | varchar(200) | No | — | Street address line 1. |
address_line_2 | varchar(200) | No | — | Street address line 2 (suite, unit, floor). |
address_line_3 | varchar(200) | No | — | Street address line 3 (additional info). |
city | varchar(100) | No | — | City or municipality. |
state_province | varchar(100) | No | — | State, province, or region. |
postal_code | varchar(20) | No | — | Postal or ZIP code. |
country_cd | varchar(10) | No | — | ISO 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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
deal_party_id | serial | Yes | Auto | Primary key. |
deal_id | integer | No | — | FK to deal.deal_id. The deal this party participates in. |
party_id | integer | No | — | FK to party.party_id. The participating party. |
party_role_type_cd | varchar(50) | No | — | The 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_ind | boolean | No | — | true if commission is a flat dollar amount; false if percentage-based. |
deal_party_commission_perc | decimal(7,4) | No | — | Commission 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_amt | decimal(15,2) | No | — | Commission amount in dollars (when flat). Populated instead of deal_party_commission_perc when deal_party_commission_flat_ind is true. |
bank_account_id | integer | No | — | FK 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): Usedeal_party_commission_perc. The percentage is applied against the net amount. - Flat (
true): Usedeal_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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
contact_method_id | serial | Yes | Auto | Primary key. Referenced by bridge tables such as uta_entity_contact_method. |
contact_method_type_cd | varchar(50) | Yes | — | Type discriminator from CONTACT_METHOD_TYPE_CD: EMAIL, PHONE, MOBILE, FAX, WEBSITE, OTHER. See Section 5. |
contact_value | varchar(500) | Yes | — | The 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.
| Status | Code | Description | Allowed Transitions |
|---|---|---|---|
| Active | true | Party is usable in new billing items, deal associations, settlements, and payments. | → Inactive (false) |
| Inactive | false | Party is excluded from new transaction creation but preserved for historical reference. Existing records are unaffected. | → Active (true) |
stateDiagram-v2
[*] --> Active : Party created
Active --> Inactive : Deactivate
Inactive --> Active : ReactivateTransition: 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, andparty_bank_accountrecords 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.
| Status | Code | Description | Allowed Transitions |
|---|---|---|---|
| Active | true (end date NULL) | Role is currently valid. Party holds this functional type. | → Ended (false, end date set) |
| Ended | false (end date set) | Role has been terminated. Historical record remains. | — |
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_dtset to the termination date;party_role.party_role_active_indset tofalse. The party's other roles and masterparty.active_indare 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.
| Status | Code | Description | Allowed Transitions |
|---|---|---|---|
| Active | true (end date NULL) | Bank account link is current and eligible for payment processing. | → Inactive (false, end date set) |
| Inactive | false (end date set) | Bank account link has been terminated. Not eligible for new payments. | — |
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_dtset to the deactivation date;party_bank_account.active_indset tofalse. Thepreferred_payment_methodon 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
| Table | Constraint | Columns | Business Rule |
|---|---|---|---|
party | (none — no DB unique constraint) | auth_party_id | Expected 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_nameshould be populated for UI rendering. For individuals,first_nameandlast_nameare expected. For organizations,company_nameis 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_rolefiltered byparty_idandparty_role_type_cdto detect conflicts. - Role code validation:
party_role.party_role_type_cdvalues are validated against thecode_mastertable (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_accountfiltered byparty_idandbank_account_idto detect conflicts. - Payment method constraint:
party_bank_account.preferred_payment_methodmust beWIREorACHwhen 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_cdvalues are validated against thecode_mastertable (type =PARTY_ADDRESSES_TYPE_CD). - Commission exclusivity: Either
deal_party.deal_party_commission_percordeal_party.deal_party_commission_amtshould be populated, not both. Controlled bydeal_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_partyfiltered bydeal_id,party_id, andparty_role_type_cdto detect conflicts. - Decimal precision:
deal_party_commission_percusesdecimal(7,4).deal_party_commission_amtusesdecimal(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.
| Code | Description | Behavior / When Used |
|---|---|---|
CLIENT | Client | The represented talent/artist (global role in party_role). |
CLNT | Client | Client role in deal-party context. Used in deal_party.party_role_type_cd. |
BUYER | Buyer | Studio, brand, network, or platform purchasing services (global role). |
BUY | Buyer | Alternate buyer code in deal-party context. |
BUYR | Buyer | Alternate buyer code used in data import context. |
AGENT | Agent | UTA agent responsible for the deal. |
AGT | Agent | Alternate agent code. |
LO | Loanout | Client's loanout company (contracted party entity). |
MGR | Manager | Talent manager. |
PM | Personal Manager | Personal manager. |
MC | Management Company | Management company (personal manager entity). |
ATT | Attorney | Legal representative. |
BM | Business Manager | Business/financial manager. |
ABM | Accountant/Business Manager | Combined accountant and business manager. |
ACC | Accountant | Accountant. |
BA | Business Affairs | Business affairs representative. |
BP | Business Partner | Business partner. |
PROD | Producer | Producer. |
PC | Production Company | Production company. |
STU | Studio | Studio entity. |
NET | Network | Network entity. |
REC | Record Company | Record label. |
PUB | Publicist | Publicist. |
PRM | PR/Media | PR and media representative. |
AGCY | Agency | Agency entity. |
UTA | UTA | UTA internal entity. |
UTAP | UTA Package | UTA package deal marker. |
UKF | UK FEU | UK Foreign Entertainers Unit marker. |
OTH | Other | Catch-all for roles not covered above. |
P | Participant | General 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.
| Code | Description | Behavior / When Used |
|---|---|---|
CHECKING | Checking Account | Standard checking account. Most common for outbound payments. |
SAVINGS | Savings Account | Savings account. Used when party's payment account is a savings account. |
PRIMARY | Primary Account | General-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.
| Code | Description | Behavior / When Used |
|---|---|---|
HOME | Home Address | Personal residence for individual parties. |
WORK | Work Address | Business/office address. |
BILLING | Billing Address | Address 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.
| Code | Description | Behavior / When Used |
|---|---|---|
WIRE | Wire Transfer | Funds transmitted via wire. Typically used for large or international payments. Selected by the outbound payment processor when this value is set. |
ACH | Automated Clearing House | Electronic 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.
| Code | Description | Behavior / When Used |
|---|---|---|
EMAIL | Email Address | Electronic mail address. |
PHONE | Phone Number | Landline or general phone number. |
MOBILE | Mobile Phone | Mobile/cell phone number. |
FAX | Fax Number | Facsimile number. |
WEBSITE | Website URL | Web address. |
OTHER | Other | Contact type not covered by the values above. |
Default on creation: No default — contact method type must be specified.
6. Cross-References
| Document | Relationship |
|---|---|
| Billing Items Data Model | billing_item.client_id, billing_item.contracted_party_id, billing_item.buyer_id, billing_item.collection_party_id → party.party_id. Four party roles on every billing item. |
| Settlements Data Model | participant_settlement_item.payment_party_id → party.party_id. Identifies the payee for each settlement payout. payment_item.client_id, payment_item.payment_party_id, payment_item.buyer_id → party.party_id. |
| Cash Receipts Data Model | bank_account identifies which UTA account received the funds. cash_receipt_client_ledger.client_id, client_ledger.client_id → party.party_id. |
| Tax Withholding Data Model | party_tax_info.party_id → party.party_id. Tax profile is maintained per party. tax_form.party_id → party.party_id. |
| Write-Offs Data Model | write_off_packet.client_id → party.party_id. Identifies the client whose receivable is being written off. |
| Deals, Sales Items & Payment Terms Data Model | deal_party.deal_id → deal.deal_id. Deal party commission and participation structure. |
| Assignments Data Model | Responsibility assignments use party hierarchy resolution (Deal → Client → Department) to find the responsible person. |