Logo

Tax

The Tax resource is used for managing customer tax returns — listing in-progress and filed returns, starting new filings, and reading or updating the annual tax questionnaire. All routes are scoped under a customer userId.

GET/users/:userId/tax-returns

List of tax returns

This endpoint returns the status of a customer's tax returns, grouped into in-progress and filed returns.

Required parameters

  • Name
    userId
    Type
    string
    Description

    Unique UUID of the customer.

Response behavior

  • Returns 200 with currentReturns and filedReturns arrays
  • Returns 400 if userId is not a valid UUID
  • Returns 404 if the user is not found
  • Archived returns are excluded from both lists

Request

GET
/users/:userId/tax-returns
curl https://beta-api.uprise.us/users/{userId}/tax-returns \
  -H "Authorization: Bearer {token}"

Response

{
  "currentReturns": [
    {
      "id": "5c59c810-3aaf-4995-b736-bd324aef45af",
      "taxYear": "2025",
      "returnTypeLabel": "Individual return",
      "status": "follow_up_questions",
      "description": "Tax return in progress"
    }
  ],
  "filedReturns": []
}
POST/users/:userId/tax-returns

Create a tax return

This endpoint creates a new annual tax return for a customer and starts the tax filing workflow.

Required parameters

  • Name
    userId
    Type
    string
    Description

    Unique UUID of the customer.

Response behavior

  • Returns 200 with the new tax return id and associated financialPlanId
  • Returns 400 if userId is not a valid UUID or the return cannot be created
  • Returns 404 if the user is not found

Request

POST
/users/:userId/tax-returns
curl -X POST https://beta-api.uprise.us/users/{userId}/tax-returns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Response

{
  "id": "04e429ba-6f6c-4765-8289-a4794495f9f3",
  "financialPlanId": "72f5abc7-d6fb-4d05-8f56-7de2cae537d8"
}
GET/users/:userId/tax-returns/:taxReturnId/questionnaire

Get tax questionnaire

This endpoint returns the annual tax questionnaire definition and the customer's current (decrypted) response for a given tax return.

Required parameters

  • Name
    userId
    Type
    string
    Description

    Unique UUID of the customer.

  • Name
    taxReturnId
    Type
    string
    Description

    Unique UUID of the tax return.

Response behavior

  • Returns 200 with questionnaire structure and response
  • Returns 400 if userId or taxReturnId is not a valid UUID
  • Returns 404 if the user or tax return is not found

Request

GET
/users/:userId/tax-returns/:taxReturnId/questionnaire
curl https://beta-api.uprise.us/users/{userId}/tax-returns/{taxReturnId}/questionnaire \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "04e429ba-6f6c-4765-8289-a4794495f9f3",
  "questionnaire": {},
  "questionnaireResponse": "[response data]"
}
PATCH/users/:userId/tax-returns/:taxReturnId/response

Update tax questionnaire response

This endpoint updates the tax questionnaire response for the tax return specified by taxReturnId. Pass the tax return ID in the path and include the updated answers in the request body — the response is saved against that tax return.

To get a valid taxReturnId, call List of tax returns first.

Required parameters

  • Name
    userId
    Type
    string
    Description

    Unique UUID of the customer.

  • Name
    taxReturnId
    Type
    string
    Description

    Unique UUID of the tax return.

Required body attributes

  • Name
    response
    Type
    object
    Description

    Customer's questionnaire response as a JSON object keyed by question text.

Optional body attributes

  • Name
    resumeQuestionId
    Type
    string
    Description

    Question ID to resume from on the next visit.

  • Name
    tracking
    Type
    object
    Description

    Progress tracking metadata for the questionnaire session.

Response behavior

  • Returns 200 with the updated tax return id
  • Returns 400 if parameters are invalid or response is missing
  • Returns 404 if the user or tax return is not found

Request

PATCH
/users/:userId/tax-returns/:taxReturnId/response
curl -X PATCH https://beta-api.uprise.us/users/{userId}/tax-returns/{taxReturnId}/response \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"response": {"Do you have any dependents you plan to claim this year?": "Yes"}}'

Response

{
  "id": "04e429ba-6f6c-4765-8289-a4794495f9f3"
}