---
updatedAt: 2026-03-13T17:01:00.000Z
agentTools:
projectIndex: https://developers.masspay.io/llms.txt
---
# Get all tax form submissions
This **GET** endpoint is used to obtain all previous tax form submissions for the user with the provided user token.
To use this endpoint, you need to provide the `user_token` as a parameter in the URL Path.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"description": "MassPay API",
"version": "1.0.0",
"title": "MassPay API",
"termsOfService": "https://www.masspay.io/terms/",
"contact": {
"name": "MassPay",
"email": "info@masspay.io",
"url": "https://www.masspay.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"x-amazon-apigateway-api-key-source": "AUTHORIZER",
"tags": [
{
"name": "Tax",
"description": "Tax resource for managing tax responsibilities."
}
],
"paths": {
"/payout/{user_token}/tax/forms": {
"get": {
"summary": "Get all tax form submissions",
"description": "This **GET** endpoint is used to obtain all previous tax form submissions for the user with the provided user token.
To use this endpoint, you need to provide the `user_token` as a parameter in the URL Path.",
"tags": [
"Tax"
],
"responses": {
"200": {
"description": "OK",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxFormSubmission"
}
},
"examples": {
"Example": {
"value": [
{
"provider": "TaxBandits",
"submission_id": "945dfedc-ad7f-4af7-b20c-06082ffa3cb3",
"tax_year": "2024",
"tax_form": "1099NEC",
"status": "ACCEPTED",
"fee": 2.5,
"currency": "USD",
"gross_amount": 5000,
"supplemental_gross_amount": 0,
"is_postal": false,
"time_created": "2024-01-15T14:15:22Z",
"files_content": {
"file_name": "1099NEC_2024.pdf",
"content": "base64encodedcontent..."
}
}
]
}
}
}
}
},
"400": {
"description": "Bad request.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error400"
}
}
}
},
"401": {
"description": "Unauthorized.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error401"
}
}
}
},
"403": {
"description": "Forbidden.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error403"
}
}
}
},
"404": {
"description": "Not Found"
},
"405": {
"description": "Method Not Allowed.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error405"
}
}
}
},
"500": {
"description": "Internal server error.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error500"
}
}
}
},
"504": {
"description": "Gateway Time-out.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error504"
}
}
}
}
},
"operationId": "get-tax-form-submissions",
"parameters": [],
"security": [
{
"AUTHORIZER_NAME": []
},
{
"api_key": []
}
],
"x-amazon-apigateway-integration": {
"uri": "LAMBDA_URI",
"responses": {
"default": {
"statusCode": "200"
}
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"type": "aws_proxy"
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"name": "user_token",
"in": "path",
"required": true
}
]
}
},
"servers": [
{
"url": "https://{environment}.masspay.io/{VERSION}",
"description": "MassPay's API server",
"variables": {
"VERSION": {
"default": "v1.0.0",
"enum": [
"v1.0.0"
]
},
"environment": {
"default": "api",
"enum": [
"api",
"staging-api"
]
}
},
"x-amazon-apigateway-endpoint-configuration": {
"disableExecuteApiEndpoint": true
}
}
],
"components": {
"schemas": {
"Error400": {
"description": "Bad request.",
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Bad request."
],
"example": "Bad request."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included."
],
"example": "The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
400
],
"example": 400
},
"error": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"example": "Error initiating payout",
"description": "Reason for error"
},
"details": {
"type": "array",
"description": "Specific details of the cause of the error",
"items": {
"type": "string",
"example": "Source amount cannot be $0"
}
}
}
}
},
"required": [
"message",
"code"
]
},
"Error401": {
"description": "Unauthorized.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Unauthorized."
],
"example": "Unauthorized."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API."
],
"example": "Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
401
],
"example": 401
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error403": {
"description": "Forbidden.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Forbidden."
],
"example": "Forbidden."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action."
],
"example": "The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
403
],
"example": 403
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error405": {
"description": "Method not allowed.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Method not allowed."
],
"example": "Method not allowed."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The HTTP method used for the request is not supported by the MassPay API. Please ensure that you are using the correct HTTP method (e.g., POST) for the specific MassPay API endpoint."
],
"example": "The HTTP method used for the request is not supported by the MassPay API. Please ensure that you are using the correct HTTP method (e.g., POST) for the specific MassPay API endpoint."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
405
],
"example": 405
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error500": {
"description": "Internal server error",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Internal server error."
],
"example": "Internal server error."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists."
],
"example": "An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
500
],
"example": 500
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error504": {
"description": "Gateway Time-out.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Gateway Time-out."
],
"example": "Gateway Time-out."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists."
],
"example": "The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
500
],
"example": 500
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"TaxFormSubmission": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"TaxBandits"
],
"description": "Tax form provider"
},
"submission_id": {
"type": "string",
"format": "uuid",
"description": "Unique submission identifier"
},
"tax_year": {
"type": "string",
"pattern": "^[0-9]{4}$",
"description": "Tax year (4 digits)"
},
"tax_form": {
"type": "string",
"enum": [
"1099K",
"1099NEC",
"1099MISC"
],
"description": "Type of tax form"
},
"status": {
"type": "string",
"enum": [
"CREATED",
"TRANSMITTED",
"SENT_TO_AGENCY",
"ACCEPTED",
"REJECTED",
"ACCEPTED_WITH_ERRORS",
"YET_TO_RETRANSMIT"
],
"description": "Submission status"
},
"fee": {
"type": "number",
"format": "float",
"description": "Fee charged for the submission"
},
"currency": {
"type": "string",
"description": "Currency of the fee"
},
"gross_amount": {
"type": "number",
"format": "float",
"description": "Gross amount reported"
},
"supplemental_gross_amount": {
"type": "number",
"format": "float",
"description": "Supplemental gross amount"
},
"is_postal": {
"type": "boolean",
"description": "Whether postal delivery was used"
},
"time_created": {
"type": "string",
"format": "date-time",
"description": "Timestamp of submission creation"
},
"files_content": {
"$ref": "#/components/schemas/TaxFormFileContent"
}
}
},
"TaxFormFileContent": {
"type": "object",
"properties": {
"file_name": {
"type": "string",
"description": "Name of the tax form file"
},
"content": {
"type": "string",
"description": "Base64 encoded content of the file"
}
}
}
},
"securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "x-api-key",
"in": "header",
"x-internal": true
},
"AUTHORIZER_NAME": {
"x-amazon-apigateway-authtype": "custom",
"x-amazon-apigateway-authorizer": {
"authorizerUri": "AUTHORIZER_VALIDATION_INVOKE_ARN",
"authorizerCredentials": "AUTHORIZER_VALIDATION_ROLE",
"authorizerResultTtlInSeconds": 300,
"identityValidationExpression": "AUTHORIZER_VALIDATION_EXP",
"type": "token"
},
"name": "Authorization",
"in": "header",
"type": "apiKey"
}
}
},
"x-amazon-apigateway-gateway-responses": {
"AUTHORIZER_FAILURE": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"EXPIRED_TOKEN": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"REQUEST_TOO_LARGE": {
"statusCode": 413,
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 413 }"
}
},
"ACCESS_DENIED": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"INVALID_API_KEY": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"QUOTA_EXCEEDED": {
"statusCode": 429,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Unauthorized.\",\n \"message\": $context.error.messageString,\n \"code\": 429\n}"
}
},
"INVALID_SIGNATURE": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"DEFAULT_4XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": $context.error.messageString,\n \"code\": 400\n}"
}
},
"THROTTLED": {
"statusCode": 429,
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 429 }"
}
},
"BAD_REQUEST_PARAMETERS": {
"statusCode": 400,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": \"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included.\",\n \"code\": 400\n}"
}
},
"API_CONFIGURATION_ERROR": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"AUTHORIZER_CONFIGURATION_ERROR": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"INTEGRATION_TIMEOUT": {
"statusCode": 504,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Gateway Time-out.\",\n \"message\": \"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists.\",\n \"code\": 504\n}"
}
},
"BAD_REQUEST_BODY": {
"statusCode": 400,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": \"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included.\",\n \"code\": 400\n}"
}
},
"INTEGRATION_FAILURE": {
"statusCode": 504,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Gateway Time-out.\",\n \"message\": \"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists.\",\n \"code\": 504\n}"
}
},
"DEFAULT_5XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": $context.error.messageString,\n \"code\": 500\n}"
}
},
"RESOURCE_NOT_FOUND": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 404 }"
}
},
"UNAUTHORIZED": {
"statusCode": 401,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Unauthorized.\",\n \"message\": \"Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API.\",\n \"code\": 401\n}"
}
},
"UNSUPPORTED_MEDIA_TYPE": {
"statusCode": 415,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 415 }"
}
},
"WAF_FILTERED": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
}
},
"x-amazon-apigateway-minimum-compression-size": 1024
}
```