Contractor payment board that keeps you 1099 ready all year

Build me a contractor operations board that my bookkeeper opens every pay cycle and leans on again at year end, so contractor compliance stops living in a spreadsheet nobody checks until January. It runs on Gusto for contractor records, forms and payments, Gmail for chasing missing paperwork, and Google Sheets as the payment ledger our books reconcile against. The whole design goal is that year to date paid and missing paperwork sit on the same row all year, rather than being discovered in a year end report against payments already made.

Settings the app stores and lets the user edit: the Gusto company, the tax year the year to date totals cover (default the current year), the reporting threshold that pins a contractor to the top (default 600 dollars), the pay period start and end dates plus the payment date for this cycle, the Google Sheets spreadsheet ID and tab holding the ledger, and the sending address and template wording for the chase emails.

The main screen is one table with a row per contractor. Load the roster with Gusto List Contractors. Dismissed contractors keep coming back in that list, so default the view to active and not dismissed using the onboarding and dismissal filters the endpoint supports, and give the user a toggle to bring dismissed contractors back in, because someone dismissed in June still needs a form for the money they were paid. Paginate explicitly with page and per (per maxes at 100) and keep reading until the last page on every list call. A truncated list silently understates year to date totals, which is exactly the failure this board exists to prevent.

Columns: contractor name and whether they are an individual or a business, wage type (hourly or fixed), the rate, onboarding status, payment method on file, bank account on file, missing forms, and year to date paid. Fill them like this. Get Contractor Payment Method tells you whether a method is actually configured and which one. List Contractor Bank Accounts tells you whether a real account exists behind it, because direct deposit selected with no bank account is still a blocker and must read as missing rather than as configured. List Contractor Forms gives the tax and onboarding forms on file and, by absence, the required ones that are not, shown as named chips such as W-9 rather than a bare count. List Contractor Payments across the whole tax year, fetched once with full pagination and grouped by contractor, gives the year to date paid figure.

Gusto returns money and hours as decimal strings such as "1234.56", so do every sum, comparison and threshold check with exact decimal arithmetic and never with floating point. Render amounts as currency with two decimals.

Above the table, pin an attention band: every contractor whose year to date paid has crossed the reporting threshold and who is still missing a required form or a usable payment method. Each pinned row states the exact gap in plain words, for example "paid 4,200 dollars this year, no W-9 on file" or "paid 1,150 dollars this year, direct deposit selected but no bank account". Sort the band by year to date paid descending, show a count so an empty band is obvious at a glance, and keep the band visible while the table scrolls. Also style anyone within a configurable distance below the threshold who is missing paperwork as a softer warning, so gaps get closed before the threshold is crossed.

Give the table search by name plus filters for onboarding status, missing forms only, missing payment details only, over threshold only, and include dismissed. These filters are how the board doubles as the year end review: filter to over threshold with dismissed included and the screen becomes the reporting checklist.

Clicking a row opens a detail drawer with that contractor's full form list from List Contractor Forms, each with its status and a view action. The view action calls Get Contractor Form PDF, which returns JSON containing a temporary s3url rather than the PDF bytes. Fetch that URL as a separate request with no Authorization header, since sending the Bearer token to the storage host fails. The link is short lived, so request it at click time instead of prefetching links when the table loads, and request a fresh one if the user returns to the drawer later.

From the same board the bookkeeper builds this cycle's payment batch. Each row gets an input for the cycle that follows the wage type on the record: hours for hourly contractors, a fixed amount for fixed wage contractors, with optional bonus and reimbursement fields where the payment supports them. As amounts are entered, a sticky summary bar shows how many contractors are in the batch and the exact running total. Rows that cannot legally be paid, meaning onboarding is incomplete or there is no usable payment method and bank account, are disabled with the reason shown in place rather than hidden from the table.

A Preview button calls Preview Contractor Payments for the whole batch and shows the dry run back in the table: per contractor amounts, the total Gusto calculates, and any warnings it returns, without creating anything. Nothing is created or funded until a person confirms. The confirmation step restates the number of contractors and the exact batch total and requires an explicit confirm; never fund automatically off the back of a preview. On confirm, walk the batch one contractor at a time: Create Contractor Payment, then Fund Contractor Payment for the payment just created. Treat created and funded as two distinct states, because a payment can exist unfunded. Each row carries its own status through pending, created, funded and failed, and a Gusto validation error is shown inline on the row that failed while the rest of the batch continues. A row stuck at created but not funded gets a Retry funding action that funds the existing payment rather than creating a second one.

Every row with a gap gets a Request missing details button. It composes an email to that contractor through Gmail Send a Message naming exactly what their row is short of, for example the specific missing form or the fact that no bank account is on file for direct deposit, rather than a generic reminder. Let the user review and edit the draft before it goes. Record when a request was last sent to each contractor and show "requested 5 days ago" on the row so nobody is chased twice in a week, and allow selecting several rows to send each of them their own personalised version in one action.

After a batch finishes funding, append it to the Google Sheets ledger with Append Values: one row per funded payment carrying the payment date, pay period, contractor name, individual or business, wage type, hours or fixed amount, amount paid, payment method, the batch identifier, and that contractor's year to date total after the payment. Append only, never overwrite, so the ledger stays an audit trail the books can reconcile against Gusto. Only funded payments are written; a created but unfunded payment must not appear in the ledger.

Keep a batch history view listing past batches with their date, contractor count, total, and any rows that ended failed or unfunded, so an unfinished batch is easy to find and close out later. Persist batches and the chase email log in the app so state survives a reload and a second bookkeeper sees the same picture.