---
updatedAt: 2026-08-31T14:49:29.000Z
---

# Forms

Form and form fields in particular taxing scenarios.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "version": "2.0.0",
    "title": "Payroll Cloud v2"
  },
  "servers": [
    {
      "url": "https://payroll-test.vertexcloud.com/payroll",
      "description": "Production Test"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": false
  },
  "tags": [
    {
      "name": "Queries",
      "description": "Various queries exist to assist customers in understanding what data is contained within the system and how to effectively integrate."
    }
  ],
  "paths": {
    "/v2/forms": {
      "get": {
        "summary": "Forms",
        "operationId": "getForms",
        "description": "Form and form fields in particular taxing scenarios.",
        "tags": [
          "Queries"
        ],
        "parameters": [
          {
            "name": "$filter",
            "in": "query",
            "description": "oData filter Query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "$skip",
            "in": "query",
            "description": "oData skip Query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "$top",
            "in": "query",
            "description": "oData top Query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "payDate",
            "in": "query",
            "description": "Pay Date to use for search",
            "schema": {
              "$ref": "#/components/schemas/date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full list of forms",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/formResults"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth 2.0 Bearer token. Request a token from your token endpoint and insert it here."
      }
    },
    "schemas": {
      "errorResponse": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Collection of one or more errors resulting from the request.",
            "items": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "target": {
            "type": "string"
          }
        }
      },
      "formResults": {
        "type": "object",
        "properties": {
          "queryResults": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/form"
            }
          },
          "recordCount": {
            "$ref": "#/components/schemas/recordCount"
          },
          "versionInfo": {
            "$ref": "#/components/schemas/versionInfo"
          }
        },
        "required": [
          "recordCount",
          "versionInfo"
        ]
      },
      "form": {
        "type": "object",
        "properties": {
          "taxRule": {
            "$ref": "#/components/schemas/taxRuleView"
          },
          "formFieldIdentifier": {
            "type": "string",
            "description": "Identifying string for the form (or field within the form) in DOM format."
          },
          "parentFormId": {
            "allOf": [
              {
                "$ref": "#/components/schemas/idType"
              },
              {
                "description": "For internal use. Id guidelines are to use string type, but Vertex Payroll IDs must be constrained to integer values."
              }
            ]
          },
          "formFieldDescriptiveName": {
            "type": "string",
            "description": "Short descriptive name for the form field."
          },
          "formDocumentation": {
            "type": "string",
            "description": "Full description of the form data."
          },
          "formValueRestriction": {
            "type": "string",
            "description": "Description of value restrictions on the form data."
          },
          "reciprocalJurisdictionGeoCodeId": {
            "type": "string",
            "description": "Geocode of a reciprocal jurisdiction this form is associated with."
          }
        }
      },
      "taxRuleView": {
        "type": "object",
        "description": "tax rule view",
        "properties": {
          "taxRecordIdentifier": {
            "$ref": "#/components/schemas/taxRecordIdentifier"
          },
          "taxName": {
            "type": "string",
            "description": "Descriptive name for the tax."
          },
          "startDate": {
            "allOf": [
              {
                "$ref": "#/components/schemas/date"
              },
              {
                "description": "The date the tax rule takes effect. Date in format YYYY-MM-DD. For example, September 27, 2012 is represented as 2012-09-27."
              }
            ]
          },
          "stopDate": {
            "allOf": [
              {
                "$ref": "#/components/schemas/date"
              },
              {
                "description": "The date the tax rule expires. Date in format YYYY-MM-DD. For example, September 27, 2012 is represented as 2012-09-27."
              }
            ]
          }
        }
      },
      "taxRecordIdentifier": {
        "type": "object",
        "description": "Combination of IDs that define a tax record.",
        "properties": {
          "taxIdentifierId": {
            "allOf": [
              {
                "$ref": "#/components/schemas/taxIdentifierId"
              },
              {
                "description": "Applies to the tax id. Note - for the complete list, refer to /tax-identifiers query."
              }
            ]
          },
          "geocodeId": {
            "allOf": [
              {
                "$ref": "#/components/schemas/geocodeId"
              },
              {
                "description": "The geocode that applies to the jurisdiction. A value of 000000000 defaults to federal taxes. For state taxes, supply a geocode id with the state part specified and the county and local parts zeroed (that is, 390000000 for Pennsylvania)."
              }
            ]
          },
          "schoolDistrictId": {
            "allOf": [
              {
                "$ref": "#/components/schemas/schoolDistrictId"
              },
              {
                "description": "Specifies the school district (relevant only for certain taxes)."
              }
            ]
          }
        },
        "required": [
          "taxIdentifierId",
          "geocodeId"
        ]
      },
      "versionInfo": {
        "type": "object",
        "description": "version information",
        "properties": {
          "version": {
            "type": "string",
            "description": "version"
          },
          "legacyVersion": {
            "type": "string",
            "description": "legacyVersion"
          },
          "dataVersion": {
            "type": "string",
            "description": "dataVersion"
          },
          "minimumWageDataVersion": {
            "type": "string",
            "description": "Minimum wage data version. This is only sent back on the minimum-wages endpoint."
          },
          "transDateTime": {
            "type": "string",
            "description": "transDateTime"
          }
        },
        "required": [
          "version",
          "legacyVersion",
          "dataVersion",
          "transDateTime"
        ]
      },
      "recordCount": {
        "type": "object",
        "description": "Record count information",
        "properties": {
          "firstRecord": {
            "type": "integer",
            "default": 0,
            "description": "Index of the first record in the current result, within all available records."
          },
          "lastRecord": {
            "type": "integer",
            "default": 0,
            "description": "Index of the last record in the current result, within all available records."
          },
          "totalAvailableRecords": {
            "type": "integer",
            "default": 0,
            "description": "Total number of records available."
          }
        },
        "required": [
          "firstRecord",
          "lastRecord",
          "totalAvailableRecords"
        ]
      },
      "date": {
        "description": "Date in format YYYY-MM-DD. For example, September 27, 2012 is represented as 2012-09-27.",
        "type": "string",
        "format": "date"
      },
      "idType": {
        "description": "Id guidelines are to use string type, but Vertex Payroll IDs must be constrained to integer values.",
        "type": "string",
        "pattern": "[0-9]*"
      },
      "geocodeId": {
        "type": "string",
        "pattern": "[0-9]*",
        "minLength": 9,
        "maxLength": 9,
        "description": "Id for a full geocode."
      },
      "taxIdentifierId": {
        "type": "string",
        "pattern": "^(-1|100|101|102|103|104|105|200|201|202|203|204|205|300|301|302|303|304|305|400|401|402|403|404|405|406|407|408|409|410|411|412|413|414|415|416|417|418|419|448|449|450|451|452|453|454|455|456|457|458|459|460|461|462|463|464|465|466|467|468|469|470|471|472|473|474|475|476|477|478|479|480|481|482|483|484|485|486|487|488|489|490|491|492|493|494|495|500|501|502|503|504|505|506|507|508|509|510|511|512|513|514|530|531|532|533|534|535|536|537|538|539|540|541|542|543|544|545|546|547)$",
        "description": "Id for a tax identifier."
      },
      "schoolDistrictId": {
        "type": "string",
        "pattern": "[0-9]*",
        "maxLength": 5,
        "description": "Id for a school district."
      }
    }
  }
}
```