Recipients
Merge duplicate recipients
Apply a reviewed decision about duplicate recipients.
/api/v1/recipients/dedupe/apply- Authentication
- OAuth 2.0 access token
- Required scopes
recipients.writerecipients.delete- Idempotency key
- Required
- Rate-limit cost
- 10 units
How to use this endpoint
Read the duplicate group first. Supply the current versions, survivor and merge choices. Released records and invalid parent filers can prevent a merge; resolve those issues before retrying.
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/dedupe/apply' \
--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
4 fieldsfiler_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.
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.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
3 fieldschunk_countAlways returnedinteger
Minimum: 0.
deleted_recipient_idsAlways returnedarray<string (uuid)>
Type: array<string (uuid)>.
survivorAlways returnedobject
Recipient read view with annual form values. Mutation responses never echo a full Tax ID. Optional fields omitted by serialization are distinct from nullable values. Unknown fields are rejected.
Nested fields (58)
address_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.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
filing_outcomeMay be omittedobject
Latest recorded IRS filing outcome and response summary. Absent until an outcome has been recorded. Provider acceptance and required customer action are distinct. Unknown fields are rejected.
Nested fields (20)
attempt_started_atAlways returnedstring
Type: string.
bucket_idAlways returnedstring
Type: string.
decision_digestAlways returnedstring
Type: string.
evidence_digestAlways returnedstring
Type: string.
filing_kindAlways returnedstring
Allowed values: "original", "correction".
generationAlways returnedinteger
Type: integer.
item_idAlways returnedstring
Type: string.
observed_atAlways returnedstring
Type: string.
order_idAlways returnedstring (uuid)
Type: string (uuid).
received_atAlways returnedstring | null
Type: string | null.
record_idAlways returnedinteger
Type: integer.
record_priorityAlways returnedinteger
Type: integer.
recovery_case_idAlways returnedstring | null
Type: string | null.
response_generationAlways returnedinteger
Type: integer.
retry_source_run_idAlways returnedstring | null
Type: string | null.
run_idAlways returnedstring
Type: string.
submission_idAlways returnedstring
Type: string.
submitted_atAlways returnedstring | null
Type: string | null.
summaryAlways returnedobject
Unknown fields are rejected.
Nested fields (9)
acceptanceAlways returnedstring
Allowed values: "accepted", "rejected", "processing", "undetermined".
conditionsAlways returnedarray<string>
Type: array<string>.
contract_digestAlways returnedstring
Type: string.
contract_versionAlways returnedstring
Historical outcomes retain their recorded response-policy version; this is independent of the APP form revision. Allowed values: "iris_response_contract_v1", "iris_response_contract_v2".
inherited_rejectionAlways returnedboolean
Type: boolean.
issue_countAlways returnedinteger
Minimum: 0.
next_actionAlways returnedstring
Allowed values: "none", "correct", "repair_rejected", "review", "technical_handling", "new_original".
terminal_reasonAlways returnedstring | null
Type: string | null.
unmatched_issue_countAlways returnedinteger
Minimum: 0.
transmission_idAlways returnedstring
Type: string.
fire_revisionMay be omittedstring
Type: string.
first_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.
from_importAlways returnedboolean
Type: boolean.
immutableAlways returnedboolean
Type: boolean.
immutable_reasonMay be omittedstring
Type: string.
import_entity_type_cdMay be omittedstring
Type: string.
import_entity_type_reasonMay be omittedstring
Type: string.
import_entity_type_sourceMay be omittedstring
Type: string.
import_run_idMay be omittedstring
Type: string.
import_sourceMay be omittedstring
Type: string.
imported_atMay be omittedstring
Type: string.
iris_repair_submissionAlways returnedobject | null
Recorded authorization to repair rejected filing records. Null when no repair has been submitted; this is not IRS acceptance. Unknown fields are rejected.
Nested fields (6)
case_idsAlways returnedarray<string>
Type: array<string>.
generationAlways returnedinteger
Type: integer.
request_sha256Always returnedstring | null
Type: string | null.
source_run_idAlways returnedstring
Type: string.
source_versionAlways returnedinteger
Type: integer.
submitted_atAlways returnedstring
Type: string.
iris_revisionMay be omittedstring
Type: string.
is_archivedAlways returnedboolean
Type: boolean.
is_btin_validatedAlways returnedboolean
Type: boolean.
is_correctedAlways returnedboolean
Type: boolean.
is_releasedAlways returnedboolean
Type: boolean.
is_tin_match_pendingAlways returnedboolean
Type: boolean.
is_tin_matchedAlways returnedboolean
Type: boolean.
is_validatedAlways returnedboolean
Type: boolean.
last_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.
last_tin_match_resultMay be omittedstring
Type: string.
middle_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.
phoneMay be omittedstring
Type: string.
postal_codeMay 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.
recipient_filingMay be omittedobject
Historical filing provenance. This metadata alone does not authorize a correction. Unknown fields are rejected.
Nested fields (6)
accepted_amendment_countMay be omittedinteger
Minimum: 0. Maximum: 65535.
external_predecessor_sha256May be omittedstring
Type: string.
scopeAlways returnedstring
Type: string.
source_filing_stateAlways returnedstring
Allowed values: "unfiled", "fire_released".
source_group_sha256Always returnedstring
Type: string.
source_is_correctedAlways returnedboolean
Type: boolean.
recipient_idAlways returnedstring (uuid)
Type: string (uuid).
source_correction_systemMay be omittedstring
Type: string.
source_digestMay be omittedstring
Type: string.
source_external_idMay be omittedstring
Type: string.
source_external_refMay be omittedstring
Type: string.
source_filing_systemMay be omittedstring
Type: string.
source_platformMay be omittedstring
Type: string.
stateMay 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.
statusAlways returnedstring
Type: string.
target_filing_systemMay be omittedstring
Type: string.
tinMay 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.
tin_kindMay be omittedstring
Type: string.
tin_last4May be omittedstring
Type: string.
transition_correction_policyMay be omittedstring
Type: string.
updated_atAlways returnedstring
Type: string.
validation_issue_countAlways returnedinteger
Type: integer.
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.
versionAlways returnedinteger
Type: integer.
{
"data": {
"chunk_count": "integer",
"deleted_recipient_ids": "array<string (uuid)>",
"survivor": "object"
},
"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.