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 instructions that failed so you can correct the source data. Tax forms are issued by a tax issuance provider and synced into PCE from the instructions your program submits; this list is how you retrieve them. It's the only tax form action exposed over the API — see Tax Forms for how issuance works end to end.

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 issued PDF (present once status is GENERATED, meaning the form was issued and its digital copy synced). 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 issuance

Surface records that need corrected source data.

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

Tax forms for a joint-tenancy co-owner

List forms issued to a specific co-owner on a joint tenancy customer. Use COOWNER as the recipient entity type and pass the co-owner's ID.

Request

POST /v1/taxForm/list

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

Each co-owner on a joint tenancy customer receives their own tax forms; filter by recipientEntityId to pull forms for one owner at a time.

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: the issuing-as-a-service model, form types, how issuance works, attributes, and statuses
• Tax Form Error Codes: reasons a list request is rejected
• External Accounts & Contacts: the Contacts that appear as recipients
• Ledger & statements: account-level activity and periodic statements