E-File Magic

Recipients

Create or update a recipient

Save recipient details and forms under a filer.

POST
/api/v1/recipients/upsert
Authentication
OAuth 2.0 access token
Required scopes
recipients.write
Idempotency key
Required
Rate-limit cost
5 units

How to use this endpoint

Submit exactly one form in forms with its exact form_id, tax_year and schema_rev. forms[0].data is canonical for IRS fields. The backend normalizes and validates that APP data, then maintains first_name, middle_name, last_name, company_name, tin, address_line1, address_line2, city, state, postal_code and country as common projections. Incoming values in these legacy top-level fields are disregarded for persistence; omit them. They never fill a missing APP value. Normal JSON/envelope constraints still apply.

For standard recipient contracts, names project from PersonFirstNm/PersonMiddleNm/PersonLastNm and Name1; tin is the digits-normalized TaxID. Mailing address uses Address1/Address2/City and the selected ForeignEntity branch: domestic State/ZipCode with country US, or foreign ProvinceCode/ForeignPostalCd/CountryCode. This does not substitute the 1042-S country of tax residence, intermediary country, property address or foreign tax identifier. Current 8027, 8596 and 8955-SSA contracts use their establishment, contractor and plan-sponsor identity/address fields respectively; control-only recipient contracts do not borrow identity from the filer. Resolve the exact annual catalog for field availability. The Recipients workspace prevents manually typed commas in its recipient personal and business name inputs. This client typing guard does not change this endpoint's annual APP validation or normalize API/import values.

An optional missing, null or blank canonical value clears its common projection; required missing values remain validation errors. display_name is an independent operator label; email and phone remain operational delivery/contact inputs. Read canonical IRS values from data_app.forms. Existing records and frozen orders are not rewritten on read. Updates retain their existing version, correction and immutability guards.

Full Tax ID input also requires tax_ids.write and is not echoed. Use the exact form/year contract. A correction requires an accepted original or preceding correction and complete filing history; pending acceptance prevents a corrected save. Fix an invalid parent filer first. Saving a form does not mean the IRS has accepted it.

FedIncTaxWith is subject to blocking EFM withholding safeguards, including corrected saves: DIV 24%; B/G/INT/K/MISC/NEC/OID/PATR/R and W-2G 36% of their applicable income basis. Positive withholding requires a positive basis. R uses GrossDistribution + TaxableAmount + CapitalGain; K uses GrossAmtOfMerchTPNetPay; OID uses OriginalIssueDiscCur + OtherPerInt + MarketDiscount + OrigIssueDiscOnUST, including signed Treasury OID; B uses the signed Proceeds + ProfitOrLossCur + AggregrateProfitOrLoss sum. Exact annual amount precision applies; ratios are not rounded. These are application safeguards, independent of IRS acceptance. Ordinary imports preserve invalid values with validation issues and is_validated=false until corrected. DA and 1042-S retain their distinct annual withholding rules.

Use the exact annual field catalog to resolve money units. In current TY2026 APP revision 3, Form 3922 ExPricePerShare uses integer strings at 100,000 units per dollar (for example, "123456" means $1.23456), like the existing 3921 per-share prices and 3922 fair values. TY2025 and older contracts keep their declared units. Refresh catalog metadata when the application is updated; revision 3 remains unchanged. Existing current TY2026 3922 values are normalized from cents by the server; do not append zeros again to values returned by the API.

Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.

cURL request
curl --request POST 'https://api.efilemagic.com/api/v1/recipients/upsert' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Idempotency-Key: <unique-operation-key>' \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Replace placeholders with your own values. Use the API resource origin provided for your environment.

Create request.json using the documented fields. Field descriptions are not sample values.