Party

Overview

Party Groups represent organizations or individuals that your company does business with. They capture customer, supplier, carrier, and tax authority information in a flexible structure that allows a single entity to play multiple roles. This eliminates data duplication when the same company is both a customer and a supplier.

Customers are parties who buy from you. Their records include contact information, shipping and billing addresses, pricing level assignments, payment terms, and credit limits. When sales orders and invoices are created, they reference the customer party, linking all sales activity back to the customer record. This provides a complete view of the customer relationship including order history, payment status, and total revenue.

Suppliers are parties who sell to you. Their records capture similar contact details plus supplier-specific information like default lead times and ordering preferences. Purchase orders and bills reference the supplier party, letting you track your purchasing relationship including open orders, payment obligations, and purchase history. This supports supplier management and accounts payable operations.

Carriers are parties who transport shipments. When you ship products, you specify which carrier is handling the shipment. Carrier records can include license information, hazmat contact details, and service preferences. This supports shipping operations and carrier performance analysis.

The multi-role capability is powerful. A company might be a customer for your finished products and also a supplier of raw materials. Rather than maintaining separate records and losing sight of the full relationship, one party record can have both customer and supplier roles. This provides a complete view of your interaction with that business partner.

Contact information is richly structured. A party can have multiple email addresses (billing, work, payment), multiple phone numbers (direct, mobile, fax), and multiple addresses (billing, shipping, payment). This supports complex organizational structures and ensures communications reach the right people. Addresses are stored as separate but related records, allowing historical tracking and multiple active addresses.

The primary party group is special - it represents your own company. This appears on invoices as the seller, on bills as the buyer, and in reports as the entity name. There's exactly one primary party group, and its information is used throughout the system to represent your business in transactions and documents.

GraphQL API

The party collection provides access to party data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

Query Name: partyViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
9 filter options
5 sortable fields
4 relations to other collections

Query Examples

Basic Query

The party collection is accessed via the partyViewConnection query, which returns a Relay-style connection with pagination support.

query {
  partyViewConnection(first: 10) {
    edges {
      node {
        contactName
        defaultSource
        defaultTerms
        emailAddressBilling
        emailAddresses
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

# First page
query {
  partyViewConnection(first: 50) {
    edges {
      node { partyId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  partyViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { partyId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Filtering

Apply filters to narrow results (see Filters section for all available options):

query {
  partyViewConnection(
    first: 10
    connectionRelationErrorDates: { begin: "2024-01-01", end: "2024-12-31" }
  ) {
    edges {
      node { partyId }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  partyViewConnection(
    first: 10
    sort: [{ field: "contactName", mode: "desc" }]
  ) {
    edges {
      node {
        partyId
        contactName
      }
    }
  }
}

Relations

Query related data (see Relations section for all available relations):

query {
  partyViewConnection(first: 10) {
    edges {
      node {
        partyId
        addressBilling {
          name
          formatted
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports metrics aggregation through the summary field. You can calculate totals, averages, counts, and other aggregate values across filtered data.

Note: This collection does not support groupBy dimensions. For dimensional analysis, use collections like product, order, or invoice.

For a comprehensive guide to using aggregations, see the Aggregation Concept Guide.

Query Structure

partyViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 1 metric that can be aggregated:

Metric	Parameters	Description
`count`	None	Count of items in the result set

Common Parameters:

operator - Aggregation function: sum, mean, min, max
transform - Mathematical transformation: abs
dateRange - Filter to specific date range
facilityUrlList - Filter to specific facilities

Examples

Example 1: Total party Metrics

Calculate aggregate metrics across all party records:

query {
  partyViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      metrics {
        totalCount: count
      }
    }
  }
}

Expected result structure:

{
  "data": {
    "partyViewConnection": {
      "summary": {
        "errorCode": null,
        "errorMessage": null,
        "metrics": {
          "totalCount": [1523]
        }
      }
    }
  }
}

Fields

This collection has 37 fields:

34 simple fields
2 enum fields (with predefined values)
1 parameterized fields (accept query options)

Note on Field Formatting: All scalar fields support the formatter argument to control output format. Available options: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with ⚠️ not sortable).

Simple Fields

These fields return values directly without additional options.

`contactName`

The primary contact name for the party. This is used for display purposes in party listings and represents the main point of contact or organization name.

Label: Contact name
Sortable: Yes

`defaultSource`

The default source party reference for purchasing relationships. This identifies the preferred supplier or source when this party is used in procurement transactions.

Label: Default source
Sortable: No

`defaultTerms`

The default payment terms applied to transactions with this party. This defines the standard billing and payment conditions, such as net 30 or due on receipt, used when creating orders or invoices.

Label: Default terms
Sortable: No

`emailAddressBilling`

The email address designated for billing-related communications. This is where invoices, payment reminders, and other accounting correspondence should be sent for this party.

Label: Email address billing
Sortable: No

`emailAddresses`

A list of all email addresses associated with the party. This aggregates multiple contact methods from the party's contact mechanisms, providing a comprehensive view of available email channels for communication.

Label: Email addresses
Sortable: No
Default Formatter: html

Example Query:

{
  party(partyUrl: "example-url") {
    emailAddresses    # Uses default formatter: html
    emailAddressesRaw: emailAddresses(formatter: "none")  # Get raw value
  }
}

`emailAddressHome`

The personal or home email address for the party contact. This is typically used for informal communications or when a personal contact method is preferred over business channels.

Label: Email address home
Sortable: No

`emailAddressPayment`

The email address designated for payment-related notifications. This is where payment confirmations, receipts, and transaction updates should be sent for this party.

Label: Email address payment
Sortable: No

`emailAddressWork`

The business or work email address for the party contact. This is typically used for formal business communications and operational correspondence.

Label: Email address work
Sortable: No

`hazmatContactPhoneNumber`

Label: Hazmat contact phone number
Sortable: No

`hazmatContractNumber`

Label: Hazmat contract number
Sortable: No

`leadTime`

Label: Default lead days
Sortable: Yes

`licenseExpiration`

Label: License expiration
Sortable: No

`licenseNumber`

Label: License number
Sortable: No

`logisticsBillingPricePerProduct`

Label: Logistics billing price per product
Sortable: No

`logisticsBillingPricePerProductFormula`

Label: Logistics billing price per product formula
Sortable: No

`logisticsBillingPricePerShipment`

Label: Logistics billing price per shipment
Sortable: No

`logisticsBillingPricePerUnit`

Label: Logistics billing price per unit
Sortable: No

`name`

Label: Name
Sortable: Yes
Default Formatter: html

Example Query:

{
  party(partyUrl: "example-url") {
    name    # Uses default formatter: html
    nameRaw: name(formatter: "none")  # Get raw value
  }
}

`notes`

Label: Notes
Sortable: No

`partyId`

Label: Party ID
Sortable: No
Default Formatter: html

Example Query:

{
  party(partyUrl: "example-url") {
    partyId    # Uses default formatter: html
    partyIdRaw: partyId(formatter: "none")  # Get raw value
  }
}

`partyUrl`

Label: Party Url
Sortable: No

`phoneNumberDirect`

Label: Phone number direct
Sortable: No

`phoneNumberFax`

Label: Phone number fax
Sortable: No

`phoneNumberHome`

Label: Phone number home
Sortable: No

`phoneNumberMobile`

Label: Phone number mobile
Sortable: No

`phoneNumbers`

Label: Phone numbers
Sortable: No
Default Formatter: html

Example Query:

{
  party(partyUrl: "example-url") {
    phoneNumbers    # Uses default formatter: html
    phoneNumbersRaw: phoneNumbers(formatter: "none")  # Get raw value
  }
}

`phoneNumberWork`

Label: Phone number work
Sortable: No

`priceLevel`

Label: Price level
Sortable: No

`primaryAddress`

Label: Primary address
Sortable: No

`primaryEmailAddress`

Label: Primary email address
Sortable: No
Default Formatter: html

Example Query:

{
  party(partyUrl: "example-url") {
    primaryEmailAddress    # Uses default formatter: html
    primaryEmailAddressRaw: primaryEmailAddress(formatter: "none")  # Get raw value
  }
}

`primaryPhoneNumber`

Label: Primary phone number
Sortable: No
Default Formatter: html

Example Query:

{
  party(partyUrl: "example-url") {
    primaryPhoneNumber    # Uses default formatter: html
    primaryPhoneNumberRaw: primaryPhoneNumber(formatter: "none")  # Get raw value
  }
}

`primaryWebAddress`

Label: Primary web address
Sortable: No
Default Formatter: html

Example Query:

{
  party(partyUrl: "example-url") {
    primaryWebAddress    # Uses default formatter: html
    primaryWebAddressRaw: primaryWebAddress(formatter: "none")  # Get raw value
  }
}

`recordCreated`

Label: Record created
Sortable: Yes

`recordLastUpdated`

Label: Record last updated
Sortable: Yes

Enum Fields

These fields return one of a predefined set of values.

`role`

Label: Role
Sortable: No

Possible Values:

CUSTOMER - Customer
SUPPLIER - Supplier
CARRIER - Carrier
TAX_AUTHORITY - Tax authority

`status`

Label: Status
Sortable: No

Possible Values:

PARTY_ENABLED - Active
PARTY_DISABLED - Inactive

Parameterized Fields

These fields accept parameters to customize the returned data. Parameters allow filtering by location, date ranges, aggregation methods, and more.

`portalScreenView`

Label: Portal screen view
Sortable: No

Parameters:

screenViewPurpose (String) Screen View Purpose

Example Query:

{
  party(partyUrl: "example-url") {
    portalScreenView(
      screenViewPurpose: "example-value"
    )
  }
}

Relations

addressBilling

Related Collection: address
Label: Billing address

TODO: Add relation description

connectionRelation

Related Collection: connectionRelation
Label: Integration

TODO: Add relation description

addressPayment

Related Collection: address
Label: Payment address

TODO: Add relation description

addressShipping

Related Collection: address
Label: Shipping address

TODO: Add relation description

Filters

connectionRelationErrorDates

Label: Latest error date
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  partyViewConnection(
    first: 10
    connectionRelationErrorDates: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        name
        connectionRelationErrorDates
      }
    }
  }
}

connectionRelationSyncStatuses

Label: Sync status
Type: List|String
Enabled: Yes
Options:
- Excluded from syncing (##crStatusSkipped)
- Has error (##crStatusError)
- Not synced (##crStatusNotPushed)
- Partially synced (##crStatusPartiallySynced)
- Synced (##crStatusPushed)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiCustomerOrganization") {
    dataSets(name: "party") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  partyViewConnection(
    first: 10
    connectionRelationSyncStatuses: ["##crStatusNotPushed", "##crStatusPushed"]
  ) {
    edges {
      node {
        name
        connectionRelationSyncStatuses
      }
    }
  }
}

partyUrl

Label: Party
Type: List|PartyUrlString
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  partyViewConnection(
    first: 10
    partyUrl: "/finaleengineer/api/partygroup/100000"
  ) {
    edges {
      node {
        name
        partyUrl
      }
    }
  }
}

recordCreated

Label: Created date
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  partyViewConnection(
    first: 10
    recordCreated: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        name
        recordCreated
      }
    }
  }
}

recordLastUpdated

Label: Last updated date
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  partyViewConnection(
    first: 10
    recordLastUpdated: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        name
        recordLastUpdated
      }
    }
  }
}

role

Label: Role
Type: List|String
Enabled: Yes
Options:
- Carrier (CARRIER)
- Customer (CUSTOMER)
- Supplier (SUPPLIER)
- Tax authority (TAX_AUTHORITY)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiCustomerOrganization") {
    dataSets(name: "party") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  partyViewConnection(
    first: 10
    role: ["CUSTOMER", "SUPPLIER"]
  ) {
    edges {
      node {
        name
        role
      }
    }
  }
}

search

Label: Not specified
Type: SearchString
Enabled: Yes

Filter Type: Search text

This filter performs a text search across multiple fields.

Usage Example:

query {
  partyViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        name
      }
    }
  }
}

searchCustom

Label: Not specified
Type: searchCustomFilter
Enabled: Yes

Filter Type: Advanced search with result expansion

See the Advanced Search guide for complete documentation on how this filter works.

Collection-Specific Examples:

Example 1: Basic search:

query {
  partyViewConnection(
    first: 10
    searchCustom: {
      terms: "red widget"
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}

Example 2: Include additional fields in search:

# Searches defaults PLUS company and contact name fields
query {
  partyViewConnection(
    first: 10
    searchCustom: {
      terms: "acme"
      include: ["partyCompanyName", "partyContactName"]
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}

Example 3: Expand results to include related records:

# For each match, also return the related record
query {
  partyViewConnection(
    first: 10
    searchCustom: {
      terms: "urgent"
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}

Example 4: Combine include and extend:

# Search in defaults + additional fields, then expand to related records
query {
  partyViewConnection(
    first: 10
    searchCustom: {
      terms: "acme corp"
      include: ["customField1"]
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}

status

Label: Status
Type: List|String
Enabled: Yes
Options:
- Active (PARTY_ENABLED)
- Inactive (PARTY_DISABLED)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiCustomerOrganization") {
    dataSets(name: "party") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  partyViewConnection(
    first: 10
    status: ["PARTY_ENABLED", "PARTY_DISABLED"]
  ) {
    edges {
      node {
        name
        status
      }
    }
  }
}