Retrieve every tax form that matches a set of criteria with the List Tax Forms API. It's a filtered, paginated search: you pass filter conditions (which payor or recipient, which type, year, or status) and PCE returns the matching forms, each with the linked PDF you can distribute.

Use it to pull all forms for a recipient, gather every form of a type for a tax year, or surface forms that failed generation so you can correct the source data. Tax forms are generated by PCE; this list is how you read them.

List tax forms

Make a POST request to /v1/taxForm/list.

Request

POST /v1/taxForm/list

{
  "pageNumber": "1",
  "pageSize": "100",
  "criteria": {
    "filters": [
      { "key": "recipientEntityName", "operator": "eq", "values": ["CONTACT"] },
      { "key": "recipientEntityId", "operator": "eq", "values": ["4014841"] }
    ]
  }
}

Response

{
  "totalCount": 21,
  "returnedCount": 1,
  "pageNumber": 1,
  "offset": 159,
  "hasMore": "false",
  "resources": [
    {
      "resourceName": "taxForm",
      "id": 138,
      "referenceNumber": "63fe678da3a46549f0f869dcedb99047",
      "type": "TAX_FORM_1099MISC",
      "year": 2023,
      "linkedDocument": {
        "id": 49861,
        "purpose": "TAX_FORM",
        "status": "VERIFIED",
        "document": {
          "resourceName": "document",
          "url": "/v1/document/id/4060549",
          "id": 4060549,
          "name": "PASSPORT_FORM_1099_MISC_P138.pdf",
          "type": "TAX_FORM"
        },
        "linkedOn": "12/24/2024 12:59:27",
        "linkedBy": { "username": "SYSTEM", "status": "ACTIVE", "userType": "SYSTEM" }
      },
      "createdOn": "12/24/2024 12:32:53",
      "lastUpdatedOn": "01/02/2025 05:58:21",
      "status": "GENERATED",
      "statusReason": "Form successfully generated",
      "payor": { "id": 4230255, "url": "/v1/customer/id/4230255", "type": "CUSTOMER" },
      "recipient": { "id": 4014841, "url": "/v1/customer/id/4228222/contact/id/4014841", "type": "CONTACT" }
    }
  ]
}

Each resource carries the linkedDocument.document.url for the generated PDF (present once status is GENERATED). A FAILED form has no linked document and explains the problem in statusReason.

Filters

Pass one or more conditions in criteria.filters[]. Each condition is a key, an operator, and one or more values.

The payorEntityName / recipientEntityName keys filter by entity type, for example CUSTOMER, CONTACT, or COOWNER (a joint-tenancy co-owner). year supports eq only, don't use in with year.

Sorting & pagination

You can sort the result set by:

• status
• id
• createdOn
• lastUpdatedOn

Set sortOptions.sortOrder to asc or desc. The response echoes totalCount, returnedCount, pageNumber, offset (the ID of the last record returned), and hasMore so you can request the next page.

Scenarios

All forms for one recipient

Pull every form issued to a specific recipient, for example a contractor saved as a Contact.

• Filter recipientEntityName eq the entity type and recipientEntityId eq its ID.

Every form of a type for a tax year

Gather all forms of one type for year-end distribution.

• Combine type eq (or in for several types) with year eq the tax year.

Forms that failed generation

Surface records that need corrected source data.

• Filter status eq FAILED, then read each statusReason to see what to fix, and re-share the corrected data.

Errors

Filter-validation errors specific to this call are listed on Tax Form Error Codes (for example, an invalid entity-name filter value, or using the in operator on year).

See also

• Tax Forms overview: form types, how forms are generated, attributes, and statuses
• Tax Form Error Codes: reasons a list request is rejected
• Bank accounts & contacts: the Contacts that appear as recipients
• Ledger & statements: account-level activity and periodic statements