API docs by Redocly

Tax Services API (1.0.0)

Download OpenAPI specification:

REST API for searching tax forms and retrieving tax form PDFs.

This document describes the public taxform-api contract.

Security for external callers is layered:

  1. Mutual TLS (client certificate)
  2. Bearer JWT

Notes for clients:

  • Search requests must include at least one primary search filter: ssnOrTaxId, accountNumber, accountName, payeeName, or a complete clientInfo (clientType and clientName).
    • This differs from SOAP v2, where search requires both SsnOrTaxId and AccountNumber.
  • taxYear and taxFormType are additional filters only; by themselves they are not sufficient.
  • clientInfo is optional. If you send it, send both clientName and clientType. Blank or partial clientInfo is ignored.
  • approvedOnly is optional and defaults to false. Use true to restrict results to forms that have been approved for filling.
    • When approvedOnly = true the response will exclude all forms that have not completed the approval process. Only forms explicitly marked as approved for user completion will be included.
    • When approvedOnly = false (or omitted) the response will return all forms, regardless of approval status.
  • POST /api/taxform/pdf defaults layout to DefaultType when omitted.

Authentication

Authenticate and obtain a JWT

Submit username and password to obtain a JWT. On success, the JWT is returned in the Authorization response header as Bearer {token}.

Authorizations:
mTLS
Request Body schema: application/json
required
username
required
string
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "username": "{{username}}",
  • "password": "{{password}}"
}

Response samples

Content type
application/json
{ }

Tax Forms

Search for tax forms

Search tax forms using one or more primary filters.

Request rules:

  • At least one primary filter is required: ssnOrTaxId, accountNumber, accountName, payeeName, or complete clientInfo (clientType and clientName).
  • taxFormType is optional. It narrows results; it does not make an otherwise empty search valid.
  • clientInfo is optional. If supplied, include both clientName and clientType.
  • approvedOnly is optional and defaults to false. Use true to restrict results to forms that have been approved for filling.
    • When approvedOnly = true the response will exclude all forms that have not completed the approval process. Only forms explicitly marked as approved for user completion will be included.
    • When approvedOnly = false (or omitted) the response will return all forms, regardless of approval status.
Authorizations:
(mTLSbearerAuth)
Request Body schema: application/json
required
Any of
ssnOrTaxId
required
string non-empty

Recommended format is 9 digits with no dashes, for example 555015555. Legacy dashed SSN/EIN input formats are also accepted.

accountNumber
string or null <= 25 characters

Account identifier. Not restricted to digits only. No minimum length is enforced by this contract. Search uses a starts-with match. Matching is based on the stored account number format.

accountName
string or null <= 56 characters

Search uses a starts-with match.

payeeName
string or null <= 34 characters

Search uses a contains match.

taxYear
integer or null <int32>

Optional exact-match tax year filter.

taxFormType
Array of strings or null (TaxFormTypeCode) non-empty
Enum: "R" "M" "W" "L" "D" "C" "A" "Z" "B" "O" "I" "S" "Q" "G" "E" "F" "K" "T" "N" "H" "U" "8" "J"

Optional exact-match list of tax form type codes.

object or null

Optional client filter.

If supplied, send both clientName and clientType. Valid clientType values are:

  • L = Bank Location
  • S = Plan Sponsor
  • A = Plan Administrator
  • T = Third Party Administrator (TPA)

Other values are not supported. Blank or partial clientInfo is ignored.

approvedOnly
boolean
Default: false

approvedOnly is optional and defaults to false. Use true to restrict results to forms that have been approved for filling.

  • When approvedOnly = true the response will exclude all forms that have not completed the approval process. Only forms explicitly marked as approved for user completion will be included.
  • When approvedOnly = false (or omitted) the response will return all forms, regardless of approval status.

Responses

Request samples

Content type
application/json
Example
{
  • "ssnOrTaxId": "555015555",
  • "approvedOnly": true
}

Response samples

Content type
application/json
{
  • "taxFormSearchResults": [
    ]
}

Get a single tax form PDF by id

Returns the PDF for a specific tax form id.

Authorizations:
(mTLSbearerAuth)
path Parameters
taxFormId
required
integer <int64>

Tax form id returned by the search endpoint.

Responses

Response samples

Content type
application/json
{
  • "status": {
    }
}

Get one aggregated PDF for one or more tax forms

Accepts one or more print-criteria objects and returns a single aggregated PDF.

Request rules:

  • taxFormId is required in each taxFormPrintCriteria item.
  • Optional fields such as ssnOrTaxId, accountNumber, accountName, payeeName, taxYear, and taxFormType are validation matchers only.
  • layout is optional; if omitted, taxform-api defaults it to DefaultType.
Authorizations:
(mTLSbearerAuth)
Request Body schema: application/json
required
layout
string
Default: "DefaultType"
Enum: "DefaultType" "PressureSeal" "Special"

Optional PDF layout selection. If omitted, taxform-api defaults the request to DefaultType.

required
Array of objects (TaxFormPrintCriteria) non-empty

Responses

Request samples

Content type
application/json
Example
{
  • "taxFormPrintCriteria": [
    ]
}

Response samples

Content type
application/json
{
  • "status": {
    }
}