Recipient
The Recipient entity in Treasury.
A recipient is the person or business you send payouts to. A recipient record stores their identity (name, email, type), zero or more payment methods (bank accounts), and tax-compliance fields (W-9 status, tokenized tax ID). You either create the recipient yourself with banking pre-populated, or invite them to enter their own banking via a one-time link — the invite flow is the recommended path because it keeps you off the hook for collecting account numbers directly.
Lifecycle
- Created —
POST /treasury/recipientswithname+email(and optional initialpayment_methods). Recipient is now addressable but not payable until at least one payment method is attached. - Invited —
POST /treasury/recipients/{id}/inviteemails the recipient a 72-hour link. Sending a new invite revokes any pending one. - Linked — Recipient submits banking through the invite (Plaid Link or manual entry). A payment method is attached, the recipient is now payable. For US contractors hitting the 1099 threshold you'll also collect a W-9 — see Tax Document.
- Active — Receives payouts. You can add up to 5 payment methods per
recipient (
POST /treasury/recipients/{id}/payment-methods). - Archived —
DELETE /treasury/recipients/{id}soft-deletes. Historical payouts and tax documents remain queryable; no new payouts can be sent.
Relationships
A recipient owns one-to-many Bank Accounts as payment methods. It is the destination for many Payouts and the subject of one Tax Document per tax year (when applicable). Recipients are scoped to your company and environment (sandbox vs. production recipients are isolated).
Fields that matter
name(string, ≤255) — display name. Required.email(string, RFC 5322) — used for invitations and W-9 requests. Required and must be unique per company.type("person" | "business") — drives 1099 vs. W-9 logic and tax-ID validation rules.payment_methods[]— initial bank accounts; can be empty if you plan to invite.metadata(Record<string, string>) — your own key/value tags, returned on every read.