Evenbead docs
Contents

Tax forms

28 operations. All areas

GET/v1/tax-forms/1099

The year's 1099s: per vendor the amounts by box (from the books, plus amounts paid outside Evenbead), which forms are needed at the thresholds, W-9 status, what is already filed, and what blocks filing; the payer, due dates, providers and filings.

  • Operation get1099Workspace
  • Scope: read
  • Read
Parameters
  • year query, integer, required
  • threshold_cents query, integer
Responses
  • 200 Workspace (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

GET/v1/tax-forms/payer

The company as the 1099 payer (TIN masked)

  • Operation getPayerProfile
  • Scope: read
  • Read
Responses
  • 200 Payer (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/payer

Set the payer's name, address, phone and TIN (people only; the TIN is sealed and needed the first time). Audited.

  • Operation setPayerProfile
  • Scope: approve
  • Write: sets a value, no Idempotency-Key needed
Request body
  • name string, required
  • name2 string
  • address1 string, required
  • address2 string
  • city string, required
  • state string, required
  • zip string, required
  • phone string, required
  • tin_type "EIN" | "SSN" | "ITIN", required
  • tin string The full number (write-only: never returned except by the audited reveal).
Responses
  • 200 Saved (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/tax-forms/account-boxes

Expense accounts mapped to 1099 boxes (unmapped accounts use the vendor's default box)

  • Operation listAccountBoxes
  • Scope: read
  • Read
Responses
  • 200 Mapping (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/account-boxes

Map an expense account to a 1099 box (null removes the mapping). Audited.

  • Operation setAccountBox
  • Scope: propose
  • Write: sets a value, no Idempotency-Key needed
Request body
  • account string, required Account code
  • box "NEC1" | "MISC1" | "MISC2" | "MISC3" | "MISC6" | "MISC10", required NEC1 nonemployee compensation; MISC1 rents, MISC2 royalties, MISC3 other income, MISC6 medical and health care payments, MISC10 gross proceeds paid to an attorney.
Responses
  • 200 Saved (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/vendors/{id}/form1099-box

A vendor's default 1099 box (where payments to unmapped accounts go). Audited.

  • Operation setVendor1099Box
  • Scope: propose
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body
  • box "NEC1" | "MISC1" | "MISC2" | "MISC3" | "MISC6" | "MISC10", required NEC1 nonemployee compensation; MISC1 rents, MISC2 royalties, MISC3 other income, MISC6 medical and health care payments, MISC10 gross proceeds paid to an attorney.
Responses
  • 200 Saved (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/vendors/{id}/tax-profile

A vendor's W-9 details (TIN masked), earlier versions and W-9 requests

  • Operation getVendorTaxProfile
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Profile (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/vendors/{id}/tax-profile

Enter a vendor's W-9 details (from a paper W-9, say); people only. The TIN is sealed; only its last four digits are shown. A new profile supersedes the old. Audited.

  • Operation setVendorTaxProfile
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • legal_name string, required
  • business_name string
  • tax_class "individual" | "c_corp" | "s_corp" | "partnership" | "trust_estate" | "llc_c" | "llc_s" | "llc_p" | "other", required W-9 line 3a: individual/sole proprietor, C corporation, S corporation, partnership, trust/estate, LLC taxed as C, S or partnership, other.
  • tax_class_other string
  • foreign_partners boolean
  • exempt_payee_code string
  • fatca_code string
  • address1 string, required
  • address2 string
  • city string, required
  • state string, required
  • zip string, required
  • tin_type "SSN" | "EIN" | "ITIN" | "ATIN", required
  • tin string, required The full number (write-only: never returned except by the audited reveal).
Responses
  • 201 Saved (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/vendors/{id}/tax-profile/reveal

Show a vendor's full TIN: a person with "See full tax IDs" only, never an agent; each reveal is in the audit log.

  • Operation revealVendorTin
  • Scope: read
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 200 TIN (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/vendors/{id}/tin-match

Check the vendor's name and TIN with the TIN-matching service connected to this deployment (none yet: the answer says so). People only; audited.

  • Operation checkVendorTin
  • Scope: propose
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 200 Result (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/w9-requests

W-9 requests sent to vendors, newest first

  • Operation listW9Requests
  • Scope: read
  • Read
Parameters
  • contact_id query, string
Responses
  • 200 Requests (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/w9-requests

Ask a vendor for a W-9: emails a single-use secure link (no sign-in) that expires (default 30 days). The vendor fills in the form and signs it electronically; the TIN is sealed on arrival. Audited.

  • Operation createW9Request
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required
  • email string
  • expires_days integer
  • message string
Responses
  • 201 Sent (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/w9-requests/{id}/cancel

Cancel an open W-9 request (its link stops working). Audited.

  • Operation cancelW9Request
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
Responses
  • 200 Cancelled (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/tax-forms/prior-amounts

1099 amounts paid outside Evenbead in a year (before switching), per vendor and box

  • Operation listPrior1099Amounts
  • Scope: read
  • Read
Parameters
  • year query, integer, required
  • include_voided query, boolean
Responses
  • 200 Amounts (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/prior-amounts

Record what vendors were paid outside Evenbead this year (a mid-year switch: QuickBooks January to April), per vendor and box, so the year's 1099s are complete. Never edited: void and re-enter. Audited.

  • Operation addPrior1099Amounts
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • amounts array of object, required
Responses
  • 201 Recorded (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/prior-amounts/{id}/void

Void an amount paid outside Evenbead (with a reason). Audited.

  • Operation voidPrior1099Amount
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
Responses
  • 200 Voided (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/tax-forms/filings

1099 filings (proposals and what became of them)

  • Operation list1099Filings
  • Scope: read
  • Read
Parameters
  • year query, integer
Responses
  • 200 Filings (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/filings

Propose a 1099 filing: the returns the year needs (or CORRECTED returns), through a provider. dry_run shows exactly what would be filed (TINs masked) and its SHA-256; otherwise it becomes a proposal that a person with "File 1099s" approves. Agents may propose; nothing is sent until approval.

  • Operation propose1099Filing
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • year integer, required
  • provider "iris_csv" | "iris_a2a" | "partner_mock" | "taxbandits", required
  • kind "original" | "correction"
  • contact_ids array of string
  • corrections array of object
  • threshold_cents integer The indexed §6041 threshold for years after 2026 (default $2,000).
  • dry_run boolean
Responses
  • 200 Dry run (object)
  • 201 Proposed (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/tax-forms/filings/{id}

A filing with its exact preview, returns and the IRS's answers

  • Operation get1099Filing
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Filing (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/filings/{id}/approve

Approve a proposed filing and send it: a person with "File 1099s" only (never an agent or AI app), confirming the preview's SHA-256. The filed copy and the provider's answer go into the audit record.

  • Operation approve1099Filing
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • preview_sha256 string, required
  • note string
Responses
  • 200 Approved and sent (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/filings/{id}/reject

Reject a proposed filing (with a reason); nothing is sent. People with "File 1099s" only.

  • Operation reject1099Filing
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
Responses
  • 200 Rejected (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/filings/{id}/retry

Send an approved filing again after the provider failed. People with "File 1099s" only.

  • Operation retry1099Filing
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 200 Sent (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/filings/{id}/ack

Record what the IRS answered for files uploaded in the IRIS portal: the Receipt ID and status, optionally per return. People with "File 1099s" only. Audited.

  • Operation record1099Ack
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • receipt_id string, required
  • status "submitted" | "accepted" | "partially_accepted" | "rejected_by_irs", required
  • rejected_records array of integer
  • note string
Responses
  • 200 Recorded (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/tax-forms/filings/{id}/refresh

Ask the filing partner for the IRS's answer so far and record it: people with "File 1099s" (agents read the filing instead). Audited.

  • Operation refresh1099Filing
  • Scope: approve
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 200 Status (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/tax-forms/filings/{id}/filed

The filed copy (full TINs): the exact file(s) sent or exported, for a person with "File 1099s"; each download is in the audit log.

  • Operation get1099FiledCopy
  • Scope: read
  • Read
Parameters
  • id path, string, required
  • file query, integer
Responses
  • 200 File (string)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

GET/v1/tax-forms/filings/{id}/recipient-copies

Recipient copies (Copy B) as one PDF, or one vendor's; the recipient's TIN truncated, the payer's in full (Pub 1179). People with "File 1099s"; audited.

  • Operation get1099RecipientCopies
  • Scope: read
  • Read
Parameters
  • id path, string, required
  • contact_id query, string
Responses
  • 200 PDF (string)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

GET/v1/w9/{token}

The vendor's W-9 link: who asks and until when (no credential; the link is the proof)

  • Operation getW9Form
  • Scope: none (public)
  • Read
Parameters
  • token path, string, required
Responses
  • 200 Form (object)
  • Errors 400, 401, 409, 422, 429, 500, 503 (Error: error.type, message)

POST/v1/w9/{token}

The vendor submits the W-9 once, with an electronic signature under penalties of perjury

  • Operation submitW9Form
  • Scope: none (public)
  • Read
Parameters
  • token path, string, required
Request body
  • legal_name string, required
  • business_name string
  • tax_class "individual" | "c_corp" | "s_corp" | "partnership" | "trust_estate" | "llc_c" | "llc_s" | "llc_p" | "other", required W-9 line 3a: individual/sole proprietor, C corporation, S corporation, partnership, trust/estate, LLC taxed as C, S or partnership, other.
  • tax_class_other string
  • foreign_partners boolean
  • exempt_payee_code string
  • fatca_code string
  • address1 string, required
  • address2 string
  • city string, required
  • state string, required
  • zip string, required
  • tin_type "SSN" | "EIN" | "ITIN" | "ATIN", required
  • tin string, required The full number (write-only: never returned except by the audited reveal).
  • signed_name string, required
  • certify true, required
  • backup_withholding_crossed boolean
Responses
  • 200 Received (object)
  • Errors 400, 401, 409, 422, 429, 500, 503 (Error: error.type, message)