# Avalara Property tax data model and key relationships

Source: https://developer.avalara.com/products/property-tax/integration-guides/avalara-property-tax/tik3599145392222/

Guide: Avalara Property Tax

# Avalara Property tax data model and key relationships

Understand the core entities, relationships, query capabilities, reference data, and error structure used in the Avalara Property Tax GraphQL API.

Avalara Property Tax organizes property tax compliance data around a client organizational structure, physical properties, taxing authorities, and compliance records. This document outlines the core entity model, structural relationships, query capabilities, static reference datasets, and error responses used across the GraphQL API.

## Data model overview

Property tax data is organized around a client's legal entity hierarchy, the properties owned or leased, and the government authorities (assessors and collectors) that assess and collect tax on those properties.

![Data model overview](https://knowledge-be.avalara.com/bundle/jop6788783806925_jop6788783806925/page/pot3324523751587.png?_LANG=enus)

## Key entity relationships

-   Client to legal entities: A client represents the top-level organization and can have multiple legal entities beneath it (such as operating subsidiaries or filing entities).

-   Legal entity to properties: A legal entity owns or leases one or more properties (locations, facilities, or physical parcels).

-   Property to assessor accounts: Each property associates with one or more assessor accounts for property tax valuation.

-   Assessor accounts and collector accounts:

    -   An assessor account represents the registration of a property (or group of properties) with a specific assessor for valuation purposes.

    -   A collector account represents the corresponding registration with a tax collector for billing and payment tracking.

    -   Assessor accounts and collector accounts link directly to each other because tax collection calculations are based on assessed valuations.

-   Notices and appeals: Assessment notices issued by assessors and formal valuation appeals attach to the corresponding assessor account.

-   Fixed assets: Fixed asset records belong to a property and roll up into an assessor account for business personal property assessment.

-   Tax bills and installments: Tax bills are issued against a collector account. Each tax bill contains one or more tax bill installments representing scheduled payments throughout the tax year.

## Supported query capabilities

The GraphQL API supports read-only queries across the core data model:

-   Core entities: Query records across clients, legal entities, properties, assessors, assessor accounts, collectors, collector accounts, tax bills, assessment notices (personal property and real estate), fixed assets, and jurisdictions.

-   Pagination: Collection queries return a collection segment with a `pageInfo` object and an `items` array. Use `skip` (records to offset) and `top` (page size, default 25, maximum 100) to page through large datasets.

-   Filtering: Queries accept a non-null `filter` input supporting string operators (`eq`, `contains`) and required scoping fields (such as `taxYear` or explicit identifier lists).

-   Sorting: Queries support an optional `order` argument containing sort objects with field names and directions (`ASC` or `DESC`).

## Static reference data

Reference queries return static, non-paginated lookup arrays that can be cached by client applications:

-   `propertyTaxJurisdictionTypes`: Lists jurisdiction classifications (such as County, City, and School District).

-   `propertyTaxCollectorTypes`: Lists collector classifications (such as County Tax Office and City Tax Office).

-   `propertyTaxStateProvinces`: Lists supported two-letter state and province codes.

-   `propertyTaxSystemEntityTypes`: Lists system entity classifications (such as `AssessorAccount` and `CollectorAccount`).

-   `propertyTaxTrackerStatuses`: Lists operational status values grouped by functional category.

-   `propertyTaxAppraisalAccountTypes`: Lists appraisal account categories (such as Real Estate and Personal Property).

## Error response structure

When a query fails validation or execution, the API returns a standard GraphQL error response containing an `errors` array alongside the `data` payload:

```
{
  "data": {
    "propertyTaxJurisdictions": null
  },
  "errors": [
    {
      "message": "Authorization failed.",
      "extensions": {
        "code": 403,
        "status": "Forbidden",
        "type": "AuthorizationError",
        "documentation": "Failed fetching propertyTaxJurisdictions",
        "timestamp": "2025-04-17T11:51:28.548Z",
        "requestId": "3b48f1ce-2323-40d6-922e-c78fee021af4"
      }
    }
  ]
}
```

**Error field definitions**

-   `message`: A concise summary of the error condition.

-   `extensions`: Structured metadata providing debugging and troubleshooting context:

    -   `code`: The HTTP status code (such as `400`, `401`, `403`, `404`, or `500`).

    -   `status`: The standard status descriptor (such as `Forbidden`, `NotFound`, or `InternalServerError`).

    -   `type`: The error category (such as `AuthenticationError`, `AuthorizationError`, `ValidationError`, `QueryTooComplexError`, or `InternalError`).

    -   `documentation`: Specific guidance explaining why the request failed.

    -   `timestamp`: The ISO 8601 timestamp when the error occurred.

    -   `requestId`: A unique tracing identifier to provide when contacting Avalara support.