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

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

Response fields

58 fields
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.

Complete response schema: ApiV1Recipient

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