---
title: "Initialize Tax Filing"
method: POST
path: "/v1/exp/initialize_tax_filing"
---

# Initialize Tax Filing

`POST /v1/exp/initialize_tax_filing`

## Request body

- object
  - `user_identifier` string, required — A unique identifier (e.g. GUID) from the host app system that will be used to reference this user. This identifier must be the same across sessions for a given user.
  - `user` object, required — Details about the user.
    - `email` string, required — The users's email address. Must be a valid email.
  - `user_metadata` object, required — Metadata about the user. You must send up-to-date information for each request.
    - `password_changed_date` string, date, required — The date in ISO 8601 format: "YYYY-MM-DD" of the last time the user’s password changed. Please send null if the user’s password was only set once and never changed.
    - `account_locked_date` string, date, required — The date in ISO 8601 format: "YYYY-MM-DD" of the last time the user was “locked out” of their account. Please send null if the user has never been locked out.
    - `passed_mfa_at_this_login` boolean, required — Did the user complete an MFA challenge (e.g. one-time password) to login for their current session?
    - `failed_login_attempts` integer, required — How many failed login attempts did the user have for their current session?
    - `cell_phone_changed_date` string, date, required — The date in ISO 8601 format: "YYYY-MM-DD" of the last time the user’s cell phone number changed. Please send null if the user’s cell phone number was only set once and never changed.
    - `email_changed_date` string, date, required — The date in ISO 8601 format: "YYYY-MM-DD" of the last time a user's email changed. Please send null if the user’s email was only set once and never changed.
  - `tax_filing_fee` object — Details about the fee the taxpayer will pay to file their return. If free, specify 0 for tax_filing_fee_cents. This can be changed after initializing a tax return for a given user, but not after a user pays or submits their tax filing.
    - `tax_filing_fee_cents` integer — Tax filing fee in cents. If free, specify 0.
  - `refund_bank_account` object — Routing information for the bank account where the user's refund will be sent. **prefill**
    - `account_type` 'checking' | 'savings' — The bank account type, either "checking" or "savings". Note that the request will fail if an invalid value is passed.
    - `routing_number` string — The routing number for the bank account.
    - `account_number` string — The user's bank account number.
  - `payment_bank_account` object — Routing information for direct debit in the case of payment to the IRS (or state agencies). **prefill**
    - `account_type` 'checking' | 'savings' — The bank account type, either "checking" or "savings". Note that the request will fail if an invalid value is passed.
    - `routing_number` string — The routing number for the bank account.
    - `account_number` string — The user's bank account number.
  - `taxpayer_personal_info` object — Personal information about the taxpayer. **prefill**
    - `date_of_birth` string, date — The taxpayer's date of birth in ISO 8601 format: "YYYY-MM-DD".
    - `first_name` string — The taxpayer's first name.
    - `middle_initial` string — The taxpayer's middle initial, if they have one.
    - `last_name` string — The taxpayer's last name.
    - `social_security_number` string — The taxpayer's Social Security Number without dashes. Column Tax stores this (and all) information about users securely (encrypted at rest).
    - `occupation` string — The taxpayer's occupation.
    - `phone` string — The taxpayer's phone number. This should be a 10-digit number. Do not include country code because we are expecting a US phone number.
  - `address` object — Taxpayer's address information. **prefill**
    - `address` string — The taxpayer's address.
    - `apt_no` string — The taxpayer's apartment number.
    - `city` string — The city corresponding to the taxpayer's address.
    - `state` string — The state as a two-letter abbreviation, e.g. "CA".
    - `zip_code` string — The ZIP code corresponding to the taxpayer's address.
  - `federal_estimated_quarterly_payments` object — Details about estimated quarterly payments (federal only) that a user has made. **prefill**
    - `estimated_tax_payment_1_amount_cents` integer — estimated tax payment user paid from Jan 1 to March 31st in cents
    - `estimated_tax_payment_2_amount_cents` integer — estimated tax payment user paid from April 1 to June 30
    - `estimated_tax_payment_3_amount_cents` integer — estimated tax payment user paid from July 1 to Sept 30
    - `estimated_tax_payment_4_amount_cents` integer — estimated tax payment user paid from October 1st to Dec 31st
  - `schedule_c_businesses` object[] — Details about any businesses that a user has. We currently only pre-fill schedule Cs pertaining to the taxpayer. **prefill**
    - `description` string, required — The business code can be very general so the business description allows the user to be more specific if they want. For example, a business with the code other_transit_ground_passenger_transportation could have a description of uber driver, ridesharing, or even simply other transit and ground passenger transportation. Ultimately, it is at the discretion of the user. The API call will error out if this is missing.
    - `ein` string — The EIN should be 9 digits. There is no need to format the string before passing it into the API. If the user’s EIN is the same as their SSN, there is no need to pass the SSN in.
    - `code` '721310' | '721210' | '721100' | '722514' | '722410' | '722511' | '722513' | '722515' | '722300' | '561430' | '561740' | '561440' | '561450' | '561410' | '561300' | '561710' | '561210' | '561600' | '561720' | '561730' | '561110' | '561420' | '561500' | '561490' | '561790' | '561900' | '562000' | '112900' | '114110' | '113000' | '114210' | '115210' | '115110' | '115310' | '713100' | '713200' | '713900' | '712100' | '711410' | '711510' | '711100' | '711300' | '711210' | '236200' | '236100' | '237310' | '237210' | '237100' | '237990' | '238310' | '238210' | '238350' | '238330' | '238130' | '238150' | '238140' | '238320' | '238220' | '238110' | '238160' | '238170' | '238910' | '238120' | '238340' | '238290' | '238390' | '238190' | '238990' | '611000' | '522100' | '522200' | '522300' | '524210' | '524290' | '523140' | '523130' | '523110' | '523210' | '523120' | '523900' | '621610' | '621510' | '621310' | '621210' | '621330' | '621320' | '621340' | '621111' | '621112' | '621391' | '621399' | '621400' | '621900' | '622000' | '623000' | '624410' | '624200' | '624100' | '624310' | '511000' | '515000' | '517000' | '518210' | '519100' | '512100' | '512200' | '315000' | '312000' | '334000' | '335000' | '332000' | '337000' | '333000' | '339110' | '322000' | '324100' | '326000' | '331000' | '323100' | '313000' | '314000' | '336000' | '321000' | '339900' | '325100' | '325500' | '325300' | '325410' | '325200' | '325600' | '325900' | '311110' | '311800' | '311500' | '311400' | '311200' | '311610' | '311710' | '311300' | '311900' | '316210' | '316110' | '316990' | '327300' | '327100' | '327210' | '327400' | '327900' | '212110' | '211120' | '212200' | '211130' | '212300' | '213110' | '812111' | '812112' | '812220' | '812310' | '812320' | '812210' | '812330' | '812113' | '812930' | '812910' | '812920' | '812190' | '812990' | '811120' | '811110' | '811190' | '811310' | '811210' | '811430' | '811410' | '811420' | '811490' | '541100' | '541211' | '541214' | '541213' | '541219' | '541310' | '541350' | '541340' | '541330' | '541360' | '541320' | '541370' | '541380' | '541510' | '541400' | '541800' | '541600' | '541910' | '541920' | '541700' | '541930' | '541940' | '541990' | '531100' | '531210' | '531320' | '531310' | '531390' | '532100' | '532400' | '532210' | '532281' | '532310' | '532283' | '532284' | '532282' | '532289' | '813000' | '444130' | '444110' | '444200' | '444120' | '444190' | '448130' | '448150' | '448140' | '448310' | '448320' | '448110' | '448210' | '448120' | '448190' | '443142' | '443141' | '445310' | '445220' | '445230' | '445100' | '445210' | '445290' | '442110' | '442200' | '447100' | '452000' | '446120' | '446130' | '446110' | '446190' | '441300' | '441222' | '441228' | '441110' | '441210' | '441120' | '451211' | '451120' | '451140' | '451212' | '451130' | '451110' | '453920' | '453110' | '453220' | '453930' | '453210' | '453910' | '453310' | '453990' | '454110' | '454310' | '454210' | '454390' | '481000' | '485510' | '484110' | '484120' | '485210' | '486000' | '482110' | '487000' | '485410' | '484200' | '485300' | '485110' | '483000' | '485990' | '488000' | '492000' | '493100' | '221000' | '423200' | '423700' | '423600' | '423940' | '423300' | '423800' | '423500' | '423100' | '423400' | '423930' | '423910' | '423920' | '423990' | '424300' | '424800' | '424920' | '424600' | '424210' | '424500' | '424910' | '424930' | '424400' | '424950' | '424100' | '424700' | '424940' | '424990' | '425110' | '425120' | '999999' — Note: These will likely change every year. Your prefill may fail if this is missing. The IRS code needed to classify each business. Use https://cotaxaide.org/tools/Business%20Activity%20Codes.html to help determine the correct classification to use. The API only accepts codes as defined in the Schedule C instruction PDF: https://www.irs.gov/pub/irs-pdf/i1040sc.pdf. This list is a subset of the entire BLS NAICS list.
    - `accounting_method` 'cash' | 'accrual' — Accounting method for the business
    - `name` string — The name that the business operates under. Can be empty
    - `street` string — Include this field if it is different from the user's permanent address. Your schedule C prefill may fail if you’re missing both this field and the user's address.
    - `city` string — Include this field if it is different from the user's permanent address. Your schedule C prefill may fail if you’re missing both this field and the user's address.
    - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'PR' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'VI' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' — Include this field if it is different from the user's permanent address. Your schedule C prefill may fail if you’re missing both this field and the user's address.
    - `zip` string — Include this field if it is different from the user's permanent address. Your schedule C prefill may fail if you’re missing both this field and the user's address.
    - `new_business` boolean — Indicate if the user has started or acquired the business in the current tax year.
    - `business_home_area` integer — The area (in square feet) of the tax payers home that they use for their business
    - `expenses` object
      - `advertising_amount_cents` integer — Advertising expenses in cents
      - `commission_and_fees_amount_cents` integer — Commissions and fees in cents
      - `contract_labor_amount_cents` integer — Contract labor expenses in cents
      - `depletion_amount_cents` integer — Depletion allowable for business extracting natural resources in cents (line 12)
      - `employee_benefit_program_amount_cents` integer — Employee benefit programs (other than on line 19) in cents
      - `business_insurance_amount_cents` integer — amount spent on non health and non vehicle insurance in cents
      - `personal_health_insurance_amount_cents` integer — amount spent on health insurance for self and family in cents
      - `supplies_amount_cents` integer — amount spent on supplies in cents. This field ultimately represents line 22. For tax payers with a business with less than 25M in gross revenue, you can combine the values of Line 36 (Items purchased for resale) and Line 38 (materials and supplies) into this field.
      - `mortgage_interest_amount_cents` integer — Mortgage (paid to banks, etc.) in cents
      - `other_interest_amount_cents` integer — amount spent on non mortgage interest in cents
      - `legal_and_professional_services_amount_cents` integer — Legal and professional services expenses in cents
      - `office_expenses_amount_cents` integer — Office expenses in cents
      - `pension_profit_sharing_plans_amount_cents` integer — Pension and profit-sharing plans expenses in cents
      - `machinery_equipment_rent_amount_cents` integer — Vehicles, machinery, and equipment rent or lease in cents
      - `other_rent_amount_cents` integer — amount spent on non machinery or non equipment rent in cent
      - `repairs_and_maintenance_amount_cents` integer — Repairs and maintenance in cents
      - `utilities_amount_cents` integer — Utilities in cents
      - `wages_amount_cents` integer — Wages (less employment credits) in cents
      - `tax_licenses_amount_cents` integer — Taxes and licenses in cents
      - `travel_amount_cents` integer — Travel expenses in cents
      - `meals_amount_cents` integer — Amount spent on all meals in cents
      - `entertainment_amount_cents` integer — Total amount spent on entertainment in cents
      - `other_expenses` object[]
        - `expense_description` string — The name of the expense
        - `expense_amount_cents` integer — The amount of the expense in cents
      - `payments_require_1099` boolean — Boolean representing if the tax payer paid anyone 600$ or more to perform a service for the business
    - `vehicles` object[]
      - `service_date` string, date — The date the vehicle was placed in service for business purposes. Your prefill may fail if this is missing.
      - `business_miles` integer — [New for Tax Year 2023 returns!] Miles driven on specific vehicle for business during the year
      - `business_miles_first_half_year` integer — [Deprecated, was used just for tax year 2022] Miles driven on specific vehicle for business before 7/1/2022
      - `business_miles_second_half_year` integer — [Deprecated, was used just for tax year 2022] Miles driven on specific vehicle for business on and after 7/1/2022
      - `total_commuting_miles` integer — Miles driven for commuting to and from work on specific vehicle
      - `total_other_miles` integer — Number of miles driven for other purposes
      - `parking_expense_amount_cents` integer — Amount spent for specific vehicle on parking fees in cents
      - `toll_expense_amount_cents` integer — Amount spent for specific vehicle on tolls in cents
      - `interest_expense_amount_cents` integer — Amount spent for specific vehicle on interest in cents
      - `was_used_for_personal` boolean — A boolean representing if a user used the vehicle for personal use
      - `another_vehicle_available` boolean — A boolean representing if user has another vehicle available for personal use
      - `has_supporting_evidence` boolean — A boolean representing if a user has supporting evidence for your business use for this vehicle
      - `has_written_evidence` boolean — A boolean representing if a user has written evidence for your business use for this vehicle
  - `w2s` object[] — Details about a user's w2s. We currently only pre-fill w2s pertaining to the taxpayer. **prefill**
    - `employer_name` string, required — The name of the employer on W2. The API call will error out if this is missing.
    - `ein` string — the EIN of the employer business. Usually 9 digits
    - `employer_address` string — street address of where business is located
    - `employer_city` string — City where business is located
    - `employer_state` '"AL"' | '"AK"' | '"AZ"' | '"AR"' | '"CA"' | '"CO"' | '"CT"' | '"DE"' | '"DC"' | '"FL"' | '"GA"' | '"HI"' | '"ID"' | '"IL"' | '"IN"' | '"IA"' | '"KS"' | '"KY"' | '"LA"' | '"ME"' | '"MD"' | '"MA"' | '"MI"' | '"MN"' | '"MS"' | '"MO"' | '"MT"' | '"NE"' | '"NV"' | '"NH"' | '"NJ"' | '"NM"' | '"NY"' | '"NC"' | '"ND"' | '"OH"' | '"OK"' | '"OR"' | '"PA"' | '"PR"' | '"RI"' | '"SC"' | '"SD"' | '"TN"' | '"TX"' | '"VI"' | '"UT"' | '"VT"' | '"VA"' | '"WA"' | '"WV"' | '"WI"' | '"WY"' | '' — State where employer is located. Can be upper or lower case
    - `employer_zip` string — Zipcode, should be 5 characters
    - `wages_tips_other_comp_amount_cents` integer — Tax Year 2022: Corresponds to box 1 in cents
    - `federal_income_tax_withheld_amount_cents` integer — Tax Year 2022: Corresponds to box 2 in cents
    - `social_security_wages_amount_cents` integer — Tax Year 2022: Corresponds to box 3 in cents
    - `social_security_tax_withheld_amount_cents` integer — Tax Year 2022: Corresponds to box 4 in cents
    - `medicare_wages_and_tips_amount_cents` integer — Tax Year 2022: Corresponds to box 5 in cents
    - `medicare_tax_withheld_amount_cents` integer — Tax Year 2022: Corresponds to box 6 in cents
    - `social_security_tips_amount_cents` integer — Tax Year 2022: Corresponds to box 7 in cents
    - `allocated_tips_amount_cents` integer — Tax Year 2022: Corresponds to box 8 in cents
    - `dependent_care_benefits_amount_cents` integer — Tax Year 2022: Corresponds to box 10 in cents
    - `non_qualified_plans_amount_cents` integer — Tax Year 2022: Corresponds to box 11 in cents
    - `box_12` object[]
      - `code` '"a"' | '"b"' | '"c"' | '"d"' | '"e"' | '"f"' | '"g"' | '"h"' | '"j"' | '"k"' | '"l"' | '"m"' | '"n"' | '"p"' | '"q"' | '"r"' | '"s"' | '"t"' | '"v"' | '"w"' | '"y"' | '"z"' | '"aa"' | '"bb"' | '"dd"' | '"ee"' | '"ff"' | '"gg"' | '"hh"' | '', required — The Box 12 code (e.g. `D`)
      - `amount_cents` integer — The amount for the code in cents
    - `is_statutory_employee` boolean — Tax Year 2022: Corresponds to indicator in box 13
    - `has_retirement_plan` boolean — Tax Year 2022: Corresponds to indicator in box 13
    - `has_third_party_sick_pay` boolean — Tax Year 2022: Corresponds to indicator in box 13
    - `other_deductions` object[]
      - `description` string — Box 14 - Description
      - `amount_cents` integer, required — Box 14 amount in cents
    - `state_and_local_tax_groups` object[]
      - `state` '"AL"' | '"AK"' | '"AZ"' | '"AR"' | '"CA"' | '"CO"' | '"CT"' | '"DE"' | '"DC"' | '"FL"' | '"GA"' | '"HI"' | '"ID"' | '"IL"' | '"IN"' | '"IA"' | '"KS"' | '"KY"' | '"LA"' | '"ME"' | '"MD"' | '"MA"' | '"MI"' | '"MN"' | '"MS"' | '"MO"' | '"MT"' | '"NE"' | '"NV"' | '"NH"' | '"NJ"' | '"NM"' | '"NY"' | '"NC"' | '"ND"' | '"OH"' | '"OK"' | '"OR"' | '"PA"' | '"PR"' | '"RI"' | '"SC"' | '"SD"' | '"TN"' | '"TX"' | '"VI"' | '"UT"' | '"VT"' | '"VA"' | '"WA"' | '"WV"' | '"WI"' | '"WY"' | '', required — Tax Year 2022: Corresponds to box 15
      - `employer_state_id` string — Tax Year 2022: Corresponds to id in box 15
      - `state_wages_amount_cents` integer — Tax Year 2022: Corresponds to box 16 in cents
      - `state_income_tax_amount_cents` integer — Tax Year 2022: Corresponds to box 17 in cents
      - `local_wages_amount_cents` integer — Tax Year 2022: Corresponds to box 18 in cents
      - `local_income_tax_amount_cents` integer — Tax Year 2022: Corresponds to box 19 in cents
      - `locality` string — Tax Year 2022: Corresponds to box 20
  - `additional_products` object[] — Configurations for additional products offered by Column Tax. If this value is present, it will configure the additional products for that session.
    - `additional_product_identifier` string, required — The identifier of the additional product being configured. Accepted value: `expert_assist`
    - `configuration` string — The configuration status for this user. Accepted values: `enrolled`, `unenrolled`. Users are `unenrolled` by default, but to downgrade them after enrolling you must pass `unenrolled` here.
    - `fee_cents` integer — The fee for this product, in cents, for this user session. If Column Tax is collecting payment for the product, this fee is applied at checkout, otherwise it is used to display correct pricing information.

## Response `200`

200

- object
  - `user_identifier` string
  - `user_url` string
  - `user_token` string
  - `data_errors` string[] — An array of warnings / alerts. If providing prefill tax document data, validation errors or prefill alerts may be included here.

## Other responses

- `400` — 400
- `401` — 401
- `404` — 404
- `410` — Gone

---

[API](https://skmtc.dev/columntax/apis/column-tax-api.md) · [All operations](https://skmtc.dev/columntax/apis/column-tax-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/columntax/column-tax-api/revisions/8585bfa3770f/schema)