# Connect to the Property Tax API

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

Guide: Avalara Property Tax

# Connect to the Property Tax API

Use the Avalara Property Tax API GraphQL endpoint by getting license credentials, generating an OAuth2 access token, and sending authenticated queries.

The Avalara Property Tax API provides a single GraphQL endpoint for querying property tax data. This guide explains how to obtain credentials, generate an OAuth2 access token, and execute authenticated GraphQL queries.

The Property Tax API operates as a single GraphQL endpoint where client applications define the exact data fields to retrieve.

To connect to the API, you must:

1.  Obtain account license credentials (`client_id` and `client_secret`) provisioned by Avalara.

2.  Exchange these credentials for a short-lived Bearer access token using the Avalara Identity OAuth2 token endpoint.

3.  Pass the Bearer token in the `Authorization` header of each HTTP POST request sent to the GraphQL endpoint.

Table 1. End points

Purpose

URL

GraphQL API endpoint

`https://returns-api.avalara.com/graphql`

OAuth2 token endpoint

`https://identity.avalara.com/connect/token`

## Obtain license credentials

Avalara provisions API access against an active tenant. Your account license credentials consist of a `client_id` and `client_secret`. Contact your Avalara representative to have credentials provisioned for your organization.

## Generate an OAuth2 access token

Exchange your license credentials for an access token by sending a `POST` request to the Avalara Identity service using the client credentials grant type.

**View request**:

```
POST https://identity.avalara.com/connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={your_client_id}&client_secret={your_client_secret}
```

**View response**:

```
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2N...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

The returned token remains valid for the number of seconds specified in `expires_in` (typically 3,600 seconds or 1 hour). Refresh or request a new token upon expiration rather than caching tokens beyond their validity window.

## Send a GraphQL query request

Include the generated access token in the `Authorization` header as a Bearer token with every GraphQL request.

**View request format**:

```
POST https://returns-api.avalara.com/graphql
Content-Type: application/json
Authorization: Bearer {access_token}
```

**Example query using cURL**:

```
curl -X POST https://returns-api.avalara.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{"query":"query { propertyTaxJurisdictionTypes { jurisdictionTypeId jurisdictionTypeName isActive } }"}'
```

## Query a paginated entity

Most entity queries (such as `propertyTaxJurisdictions`, `propertyTaxProperties`, and `propertyTaxTaxBills`) return a collection segment with pagination, filtering, and sorting capabilities.

**Example query definition**:

```
query GetJurisdictions(
  $skip: Int
  $top: Int
  $filter: PropertyTaxJurisdictionFilterInput!
  $order: [PropertyTaxJurisdictionSortInput!]
) {
  propertyTaxJurisdictions(
    skip: $skip
    top: $top
    filter: $filter
    order: $order
  ) {
    pageInfo {
      totalRecords
      skip
      top
      hasNextPage
      hasPreviousPage
    }
    items {
      jurisdictionId
      jurisdictionName
      reportedName
      internalCode
      stateProvince {
        stateProvinceCode
        stateProvinceName
      }
      isActive
      createdDateTime
      modifiedDateTime
      modifiedBy {
        firstName
        lastName
        email
      }
      jurisdictionType {
        jurisdictionTypeId
        jurisdictionTypeName
      }
      jurisdictionTaxRates {
        jurisdictionTaxRateId
        taxYear
        taxRate
        propertyTypeId
        isDefaultFlag
      }
    }
  }
}
```

**Query variables**:

```
{
  "skip": 0,
  "top": 25,
  "filter": {
    "jurisdictionName": { "contains": "Dallas" },
    "stateProvinceCodes": ["TX"],
    "isActive": true
  },
  "order": [
    {
      "jurisdictionName": "ASC"
    }
  ]
}
```

**Parameter guidelines**:

-   `filter`: Scopes the dataset using specific fields and comparison operators (e.g., `eq`, `contains`).

-   `skip`: Number of records to skip before returning results (default: `0`).

-   `top`: Number of records to return per page (default: `25`, maximum: `100`).

-   `order`: Optional array specifying fields and directions (`ASC` or `DESC`) for result sorting.