Recipients
Create or update a recipient
Save recipient details and forms under a filer.
/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 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.jsonReplace 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.
Request fields
18 fieldsdisplay_nameRequiredstring
Operator display label, independently editable; does not replace the IRS filing name in forms[0].data. Minimum characters: 1. Maximum characters: 256.
filer_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
formsRequiredarray<object>
Recipient forms and their values, using each form's exact annual contract. Minimum items: 1. Maximum items: 1.
Nested fields (15)
app_revisionOptionalinteger | null
Minimum: 1.
correction_codeOptionalstring | null
Maximum characters: 32.
correction_typeOptionalstring | null
Maximum characters: 64.
dataOptionalobject | null
APP form payload validated against form_id, tax_year, and schema_rev.
data_refOptionalstring | null
Maximum characters: 2048.
data_sha256Optionalstring | null
Pattern: ^[a-f0-9]{64}$
filer_revisionOptionalinteger | null
Minimum: 1.
fire_revisionOptionalinteger | null
Minimum: 1.
form_idRequiredstring
Minimum characters: 1. Maximum characters: 64.
form_profilesOptionalobject | null
Type: object | null.
iris_revisionOptionalinteger | null
Minimum: 1.
is_correctedOptionalboolean | null
Type: boolean | null.
schema_revRequiredinteger
Minimum: 1.
tax_yearRequiredinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
unique_record_idOptionalstring | null
Maximum characters: 128.
address_line1Optionalstring | null
Backend-maintained common projection of the selected primary-party mailing street field in forms[0].data. Incoming values are disregarded for persistence; omit this legacy input. Normal JSON/envelope constraints still apply. Missing or blank optional APP values clear the projection; a separate common value never fills an APP field. Maximum characters: 160.
address_line2Optionalstring | null
Backend-maintained common projection of the selected primary-party second mailing address line in forms[0].data. Incoming values are disregarded for persistence; omit this legacy input. Normal JSON/envelope constraints still apply. Missing or blank optional APP values clear the projection; a separate common value never fills an APP field. Maximum characters: 160.
cityOptionalstring | null
Backend-maintained common projection of the selected primary-party mailing city in forms[0].data. Incoming values are disregarded for persistence; omit this legacy input. Normal JSON/envelope constraints still apply. Missing or blank optional APP values clear the projection; a separate common value never fills an APP field. Maximum characters: 80.
company_nameOptionalstring | null
Backend-maintained common projection of Name1, or the annual contract's primary-party business-name field in forms[0].data. Incoming values are disregarded for persistence; omit this legacy input. Normal JSON/envelope constraints still apply. Missing or blank optional APP values clear the projection; a separate common value never fills an APP field. Maximum characters: 256.
countryOptionalstring | null
Backend-maintained common projection of US for the domestic mailing address choice, or CountryCode for the foreign choice, or the corresponding primary-party field in forms[0].data. Incoming values are disregarded for persistence; omit this legacy input. Normal JSON/envelope constraints still apply. Missing or blank optional APP values clear the projection; a separate common value never fills an APP field. Maximum characters: 80.
emailOptionalstring (email) | null
Operational recipient delivery/contact email. Independently editable; not a projection of an IRS form field. Maximum characters: 254.
expected_versionOptionalinteger | null
Version from the latest read of the record. A changed version requires review before updating. Minimum: 1.
first_nameOptionalstring | null
Backend-maintained common projection of PersonFirstNm, or the annual contract's primary-party first-name field in forms[0].data. Incoming values are disregarded for persistence; omit this legacy input. Normal JSON/envelope constraints still apply. Missing or blank optional APP values clear the projection; a separate common value never fills an APP field. Maximum characters: 160.
last_nameOptionalstring | null
Backend-maintained common projection of PersonLastNm, or the annual contract's primary-party last-name field in forms[0].data. Incoming values are disregarded for persistence; omit this legacy input. Normal JSON/envelope constraints still apply. Missing or blank optional APP values clear the projection; a separate common value never fills an APP field. Maximum characters: 160.
Headers (3)
AuthorizationRequired- OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
Idempotency-KeyRequired- Opaque caller-generated key bound to resolved tenant, connection, and actor scope.
DPoPConditional / optional- Required when the application, connection, or credential is proof-of-possession bound.
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.jsonReplace 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.
Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
58 fieldsaddress_line1May be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
address_line2May be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
app_revisionMay be omittedstring
Type: string.
arch_bucketAlways returnedstring
Type: string.
cityMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
company_nameMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
correction_typeAlways returnedstring
Type: string.
countryMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
created_atAlways returnedstring
Type: string.
data_appAlways returnedobject
Unknown fields are rejected.
Nested fields (1)
formsMay be omittedarray<object>
Type: array<object>.
Nested fields (21)
app_revisionAlways returnedinteger
Type: integer.
correction_codeAlways returnedstring
Type: string.
correction_typeMay be omittedstring
Type: string.
dataMay be omittedvalue
Form values under the exact annual APP contract returned by the form catalog.
data_refMay be omittedstring
Type: string.
data_sha256May be omittedstring
Type: string.
error_countAlways returnedinteger
Type: integer.
filer_revisionMay be omittedinteger
Type: integer.
fire_revisionMay be omittedinteger
Type: integer.
fire_translation_contract_idMay be omittedstring
Type: string.
form_idAlways returnedstring
Type: string.
has_errorsAlways returnedboolean
Type: boolean.
iris_revisionAlways returnedinteger
Type: integer.
iris_translation_contract_idAlways returnedstring
Type: string.
is_correctedMay be omittedboolean
Type: boolean.
schema_revAlways returnedinteger
Type: integer.
statusAlways returnedstring
Type: string.
tax_yearAlways returnedinteger
Type: integer.
unique_record_idMay be omittedstring
Type: string.
updated_atAlways returnedstring
Type: string.
validation_issuesMay be omittedarray<object>
Type: array<object>.
Nested fields (4)
codeAlways returnedstring
Type: string.
fieldMay be omittedstring
Type: string.
messageAlways returnedstring
Type: string.
originMay be omittedstring
Type: string.
display_nameAlways returnedstring
Type: string.
emailMay be omittedstring
Type: string.
{
"data": {
"address_line1": "string",
"address_line2": "string",
"app_revision": "string",
"arch_bucket": "string",
"city": "string",
"company_name": "string",
"correction_type": "string",
"country": "string",
"created_at": "string",
"data_app": "object",
"display_name": "string",
"email": "string",
"filer_id": "string (uuid)",
"filing_outcome": "object",
"fire_revision": "string",
"first_name": "string",
"from_import": "boolean",
"immutable": "boolean",
"immutable_reason": "string",
"import_entity_type_cd": "string",
"import_entity_type_reason": "string",
"import_entity_type_source": "string",
"import_run_id": "string",
"import_source": "string",
"imported_at": "string",
"iris_repair_submission": "object | null",
"iris_revision": "string",
"is_archived": "boolean",
"is_btin_validated": "boolean",
"is_corrected": "boolean",
"is_released": "boolean",
"is_tin_match_pending": "boolean",
"is_tin_matched": "boolean",
"is_validated": "boolean",
"last_name": "string",
"last_tin_match_result": "string",
"middle_name": "string",
"phone": "string",
"postal_code": "string",
"recipient_filing": "object",
"recipient_id": "string (uuid)",
"source_correction_system": "string",
"source_digest": "string",
"source_external_id": "string",
"source_external_ref": "string",
"source_filing_system": "string",
"source_platform": "string",
"state": "string",
"status": "string",
"target_filing_system": "string",
"tin": "string",
"tin_kind": "string",
"tin_last4": "string",
"transition_correction_policy": "string",
"updated_at": "string",
"validation_issue_count": "integer",
"validation_issues": "array<object>",
"version": "integer"
},
"meta": {
"api_version": "v1",
"request_id": "string"
}
}Successful response structure. This outline shows field types, not a response to copy. Expand Response fields for nested properties and optional values.
Errors to handle
Errors use {error: {code, message}, meta}. Check the code and message before retrying. Authentication, validation and availability errors can occur before the operation runs.
- 400
invalid_request - Check required fields, selectors and supported values.
- 401
invalid_token - Obtain a valid OAuth token for this resource. Check its expiry and current authorization.
- 403
insufficient_scope - Request the listed scopes through the application's authorization flow.
- 403
forbidden - Check the connection's permissions and allowed filers. More scopes alone may not grant access.
- 404
not_found - Check the resource ID and its owning filer. Batch reads report missing IDs as documented.
- 409
conflict - Read the current state and resolve the conflict. Do not change the body under an existing idempotency key.
- 412
precondition_failed - Read the current version or preview again; a required precondition has changed.
- 422
validation_failed - Correct the reported validation issues before retrying.
- 429
rate_limited - Wait for Retry-After before retrying. Avoid concurrent retries.
- 500
internal_error - Retain request_id and retry an uncertain result with the same body and idempotency key.
- 503
service_unavailable - Retry with bounded backoff, preserving the body and idempotency key.
- 402
service_capacity_required - Purchase the required service capacity in E-File Magic before creating records.