# file-ein

Paid (standard Exact-EVM rail, variable — `get-pricing` with `product: "ein"`). Obtains a federal EIN for an active managed entity. **SSN path only in v1**: a responsible party with an SSN is required; no-SSN filings are not offered (a disclosed exclusion).

## Input

| Field | Required | Notes |
|---|---|---|
| `entity` | yes | Handle of an entity you own, e.g. `"US-WY:daski-labs-llc"`. |
| `formData` | yes | The federal EIN contract from `get-pricing` — includes `responsible_party` (a person object with the `dob` adjunct) and the **top-level `ssn` field**. Keys supplier-verbatim; dates are `MM/DD/YYYY`. |
| `filingPlanId` | yes | Copy the current ID from detailed `get-pricing` for this product. |
| `filingAddresses` / `filingFiler` | per plan | Explicit public-address and filer choices from the plan requirements. |
| `filingProfileId` | per plan | Owner-scoped profile from `get-entity-status` when managed contact/official fields are required. |
| `assetId` | no | Immutable UUID — disambiguates re-formed names. |

## Example

Illustrative request. Select Northwest only for targets permitted by the actual plan; supply any additional required choices and profile reference it publishes.

```jsonc
{
  "entity": "US-WY:daski-labs-llc",
  "filingPlanId": "copy-current-plan-uuid",
  "filingAddresses": [
    { "target": "/company_principal_address", "source": "northwest" },
    { "target": "/company_mailing_address", "source": "northwest" }
  ],
  "formData": {
    "responsible_party": {
      "first_name": "Riley", "last_name": "Chen",
      "phone_number": "+13075550100", "dob": "1990-04-12"   // dob: screening-only adjunct
    },
    "ssn": "***-**-****",                 // top-level on the federal form
    "number_of_members": "2",
    "start_date": "07/04/2026",           // MM/DD/YYYY per the federal contract
    "principal_activity": "Software consulting",
    "ein_has_employees": false,
    "ein_involves_gambling": false
  }
}
```

## SSN handling

The SSN is **encrypted immediately** on receipt, **redacted from every persisted record** (`<redacted:ssn>`), **injected only into the federal filing**, and **purged once the order is accepted**. Because it is never kept in recoverable form, the `inputRequest` of a task that round-trips through `input-required` shows `formData.ssn` as `withheld`: resubmit the complete corrected request, `formData` including `ssn`, as order input. That is by design, not a bug.

The IRS matches the responsible party's name against the SSN. `first_name` and `last_name` must be the person's legal given name and surname exactly as on their Social Security card; a mismatch comes back as `input-required` after filing.

## Screening

The responsible party is screened against sanctions lists (together with the entity's stored parties) before any supplier spend. A hold shows the neutral review message with no timeline promise.

## Result artifacts — `ein_details`, `ein_letter`

```jsonc
{
  "entity": "US-WY:daski-labs-llc",
  "assetId": "5f0c2f6a-…",
  "documents": ["7c31d2e8-…", "8d42e3f9-…"]   // documentIds for list/download
}
```

Completion delivers the **IRS EIN letter and the SS-4** as entity documents; `ein_letter` is the letter PDF as a URL artifact (expiring link — re-fetch any time via `download-entity-document`). The EIN value itself is not parsed into the artifact in v1 — read it from the letter. `get-entity-status` flips `einPresent: true`, and a completion email goes to the entity's `contactEmail`.

## Failure modes & refunds

- Correctable input problems (missing/invalid `responsible_party`, `dob` format, `formData` violations, an SSN that arrived redacted, or Northwest returning the filing after an IRS mismatch): `input-required` — read the `inputRequest` on the order status and resubmit the complete corrected request; no refund needed.
- Unavailable, stale or revoked filing plans and ambiguous supplier evidence: paused for operator review; no automatic refund is promised.
- After the filing is committed federally: operator-resolved via support.

## Next step

- `list-entity-documents` / `download-entity-document` for the letter later.
- Done — the asset stays `active`.

## Filing plan and addresses

Before buying, obtain the current `filingPlanId` from detailed `get-pricing`
and pass it with the request. Include explicit `filingAddresses` and
`filingFiler` choices when the plan requires them. Do not repeat managed
address, filer, officials or registered-agent fields in `formData`.
When `filerRequirements.profileRequired` is true, also pass the owner-scoped
`filingProfileId` and filer option returned by `get-entity-status`. The request
pins that profile's roster. Missing historical evidence requires support review.
The selected method is retained across retries; an unavailable or revoked plan
pauses work instead of silently switching methods.