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

Request fields

18 fields
display_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.

Complete request schema: ApiV1RecipientUpsertRequest

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.

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