E-File Magic

Recipients

Merge duplicate recipients

Apply a reviewed decision about duplicate recipients.

POST
/api/v1/recipients/dedupe/apply
Authentication
OAuth 2.0 access token
Required scopes
recipients.writerecipients.delete
Idempotency key
Required
Rate-limit cost
10 units

Request fields

4 fields
filer_idRequiredstring (uuid)

ID of the filer that owns this operation's records.

survivorRequiredobject

Recipient and version to retain after the reviewed duplicate merge. Save one canonical APP form. Common identity and mailing-address fields are backend-maintained projections, not independent inputs. Supply IRS values in forms[0].data using its exact form_id/tax_year/schema_rev contract. Full Tax ID writes require tax_ids.write and are never echoed. Unknown fields are rejected.

Nested fields (18)

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.

display_nameRequiredstring

Operator display label, independently editable; does not replace the IRS filing name in forms[0].data. Minimum characters: 1. Maximum characters: 256.

emailOptionalstring (email) | null

Operational recipient delivery/contact email. Independently editable; not a projection of an IRS form field. Maximum characters: 254.

expected_versionOptionalinteger | null

Minimum: 1.

filer_idRequiredstring (uuid)

Type: string (uuid).

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.

formsRequiredarray<object>

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.

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.

middle_nameOptionalstring | null

Backend-maintained common projection of PersonMiddleNm, or the annual contract's primary-party middle-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.

phoneOptionalstring | null

Operational contact phone. Independently editable; not a projection of an IRS form field. Maximum characters: 32.

postal_codeOptionalstring | null

Backend-maintained common projection of ZipCode for a domestic address or ForeignPostalCd for a foreign address, 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: 32.

recipient_idOptionalstring (uuid) | null

Type: string (uuid) | null.

stateOptionalstring | null

Backend-maintained common projection of State for a domestic address or ProvinceCode for a foreign address, 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.

tinOptionalstring | null

Backend-maintained common projection of TaxID, or the annual contract's primary-party TIN field (the common copy is digits-only) 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: 32.

chunk_sizeOptionalinteger | null

Minimum: 1. Maximum: 100.

delete_recipientsOptionalarray<object>

Duplicate recipients and versions to remove as part of the merge. Maximum items: 100.

Nested fields (2)

expected_versionRequiredinteger

Minimum: 1.

recipient_idRequiredstring (uuid)

Type: string (uuid).

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: ApiV1RecipientDedupeApplyRequest

cURL request
curl --request POST 'https://api.efilemagic.com/api/v1/recipients/dedupe/apply' \
  --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.