Capture immutable prepared-document identity with encrypted TIN; this does not assert filing or furnishing

POST/customers/{id}/tax-document-identities

Prepared-document capture does not assert furnishing or filing. Fresh staff customers:tax:read with explicit information_return purpose, or actual svc_accounts with customers:tax:read and the verified staff subject in on_behalf_of. Source name/address and full TIN are copied under the customer lock; only immutable metadata/last4 leave this call, and the TIN remains separately encrypted. Same customer/year/document_ref replays the original snapshot.

Path parameters

idstringRequired

Query parameters

purposestringOptional

on_behalf_ofstringOptional

Headers

Idempotency-KeystringOptional

Send on every write that creates or changes money or state; a replay with the same key returns the original result with 200.

Body parameters

document_refstringRequired

tax_yearintegerRequired

Returns

200 OK

addressobjectRequired

6 child attributes

citystringRequired

countrystringRequired

line1stringRequired

line2stringOptional

postal_codestringRequired

statestringRequired

customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

document_refstringRequired

idstringRequired

legal_namestringRequired

recorded_atstring · date-timeRequired

recorded_bystringRequired

recorded_forstringOptional

tax_id_last4stringRequired

tax_yearintegerRequired

tin_typestringRequired

Errors

Every error is a problem document with a stable code. See Errors.

400401403404409412413422424429500503