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

On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.

Response fields

3 fields
chunk_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.

Complete response schema: ApiV1RecipientDedupeApplyResponse

Structure · HTTP 200
{
  "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.