Overview

The Recipient endpoints allow you to add, update, and manage the recipients (vendors, contractors or other payees) for whom you are filing tax forms in TaxBandits.

When filing 1099, W-2, or other information returns through the TaxBandits API, it is recommended to create the recipients first before filing any tax forms for them. Having the recipient set up in advance keeps your integration clean and avoids repeating recipient details across every form request.

You can also include recipient details directly in the Create request for the corresponding tax form, rather than adding the recipients as a separate step.

Key Elements

• RecipientId — A unique GUID generated by TaxBandits on recipient creation. Use this as your primary recipient reference across all endpoints.
• PayeeRef — An optional identifier you define for the recipient. Can be used interchangeably with RecipientId in most endpoints.
• TIN Format — TaxBandits supports PLAIN_TIN, ENCRYPTED, and TOKEN formats, giving you flexibility in how sensitive tax identification numbers are passed through your system.
• IsActive — Indicates whether the recipient is currently active. Filings can only be made against active recipients.

Recipient endpoints

To use the following endpoints, you must first call the Auth method to obtain an access token. Include this token in your request header as a Bearer token. Refer to OAuth 2.0 Authentication

• Create: Create a new recipient in TaxBandits. Returns a unique RecipientId that can be used in all subsequent requests — no need to pass full recipient details every time.
• Update: Update the details of an existing recipient. Changes apply to returns that are in progress; they do not affect returns already transmitted.
• Get: Retrieve the full details of a specific recipient using its RecipientId or PayeeRef.
• List: Get a paginated list of recipients created within a specified date range. Supports filtering by active status, TIN, and more.
• Delete: Delete a recipient permanently. A recipient cannot be deleted if tax forms are already associated with it, unless IsForcedDelete is set to TRUE.
• Deactivate: Temporarily deactivate a recipient without deleting it. Filings cannot be made against a deactivated recipient, but all associated data remains intact.
• Reactivate: Reactivate a previously deactivated recipient. All associated data and configuration carry over — filings can resume immediately.
• AssignRecipient: Assign one or more existing recipients to a specific business (payer or employer). Recipients must be assigned to a business before filings can be made.
• UnassignRecipient: Remove the assignment of one or more recipients from a specific business without deleting them.

DBA (Doing Business As) Endpoints

If a recipient operates under a trade name different from its IRS-registered name, DBAs can be added and managed separately. Once a DBA is added, the recipient can receive transactions and 1099s under that DBA name.

• AddDBA: Add one or more DBA names to an existing recipient. Each DBA gets a unique DBAId.
• UpdateDBA: Update the name or address of an existing DBA.
• ListDBA: Retrieve all DBA names associated with a specific recipient.
• DeleteDBA: Remove a specific DBA from a recipient.