Update tax withholding settings

patch

https://api.wingspan.app/v3/finance/tax-withholdings/settings

Updates the automatic tax withholding configuration.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Automatic-withholding configuration plus the tax profile a tax estimate is computed from. Every field is optional and an omitted field is left unchanged, but at least one is required. Fields cannot be cleared through this endpoint, only set to a new value.

isEnabled

boolean

withholdingRate

number

0 to 100

filingStatus

string

enum

A person's US federal income tax filing status, as an input to a tax estimate. Named for the estimate it feeds because tax spans several unrelated domains here: TaxFilingStatus is the lifecycle of a tax filing, and UsTaxProfile is the identity of record on a ComplianceEntity. Neither is this.

Allowed:

state

string

enum

State of residence, which selects the state tax brackets.

estimatedAnnualIncome

integer

0 to 10000000

Expected annual self-employment income, in whole US dollars. Not a MonetaryAmount: the calculator uses it to select a tax bracket, and the backing field is an int32, so sub-dollar precision would be truncated on the wire. The bounds mirror the users-service validator, so a bad value is a 422 with field errors here rather than an opaque upstream 400.

estimatedAnnualExpenses

number

≥ 0

Expected annual deductible business expenses, in US dollars. Feeds totalExpenses and netProfit on a tax estimate. It does not move the tax figures — the calculator does not deduct expenses today.

Headers

Idempotency-Key

string

length between 1 and 255

^[\x21-\x7e]{1,255}$

Optional idempotency token for authenticated POST and PATCH requests. Reusing the same key and body returns the cached response for 24 hours, except credential operations that explicitly document a 409 because one-time secret material is never cached; reusing it with a different body returns 409 IdempotencyKeyConflict. Use 1-255 printable ASCII characters.

X-Wingspan-Account

string

^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

200Updated settings

400Malformed request syntax

401Unauthenticated

403Forbidden

422Validation error