# Jurisdiction packs

> Select rule packs on a profile, pass the signer's state, and read which packs, rules, steps and strings each session applied.

Source: https://esigncomply.com/docs/guides/jurisdictions

A jurisdiction pack is a versioned set of rules for one body of law, published by Esign Comply as data. A profile enables any set of packs. Each session applies the subset that fits the signer and the documents, and the record pins exactly what was applied.

Selecting a pack tells Esign Comply which rules to apply. It is not a determination by Esign Comply of which law governs. Read [What a pack is not](#what-a-pack-is-not) before you describe your flow to anyone.

Browse every pack, rule and source in the [pack catalogue](https://esigncomply.com/docs/jurisdictions.md).

## Pack codes

| Code | Covers |
|---|---|
| `US-FED` | U.S. federal baseline. Added automatically when any state pack is selected. |
| `US-CA`, `US-NY`, `US-FL`, `US-TX`, `US-DE`, `US-VA`, `US-MA` | State packs. Each holds only its differences from `US-FED` and never relaxes a Federal rule. |
| `EU`, `UK`, `CH` | Separate packs for EU and EEA, United Kingdom and Swiss flows |

Read the catalogue from `GET /v1/jurisdictions` and do not hard-code it. New packs need no SDK release. An unknown code returns [`jurisdiction_unknown`](https://esigncomply.com/docs/api/errors.md#jurisdiction_unknown). Every published pack is available on every plan, in test mode and live, in any combination, at no per-pack fee.

## Select packs on a profile

```bash
curl https://esigncomply.com/v1/profiles \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Signup",
    "jurisdictions": ["US-FED", "US-CA", "US-NY"],
    "jurisdiction_mode": "auto",
    "on_unknown_region": "strictest",
    "governing_law": "US-NY",
    "method": "checkbox",
    "assurance_level": "L1"
  }'
```

| Field | Values | Default | Effect |
|---|---|---|---|
| `jurisdictions` | Pack codes | `["US-FED"]` | The packs this profile enables |
| `jurisdiction_mode` | `auto`, `strictest`, `explicit` | `auto` | How enabled packs are applied per session |
| `on_unknown_region` | `strictest`, `base_only`, `reject` | `strictest` | What happens when a U.S. signer has no `signer.region` |
| `governing_law` | A pack code or ISO 3166 code | `null` | Fires the governing-law rules of that pack |
| `allow_session_packs` | Boolean | `false` | Lets a session add a pack the profile does not enable |
| `strict_jurisdictions` | Boolean | `false` | Turns the `jurisdiction_not_enabled` warning into an error |
| `pack_versions` | `"latest"` or a map of code to version | `"latest"` | Pinning is an Enterprise option |

Creating a profile adopts every record condition of the packs it enables. Packs you add later start in advise. See [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md).

## Modes

| Mode | Which packs apply | Which rules fire | `reason` on the applied pack |
|---|---|---|---|
| `auto` | An enabled pack applies when the signer's asserted location matches it, when `governing_law` names it, or when your organization's registered state matches it. `US-FED` applies to every U.S. signer. | Only rules whose trigger matched. A consumer rule keyed to the signer's residence does not fire merely because the contract names that state's law. | `base`, `signer_region`, `governing_law`, `organization_region` |
| `strictest` | Every enabled pack, whatever the signer's location | Every in-scope rule of every applied pack | `strictest` |
| `explicit` | Exactly the packs the session sends in `jurisdictions.packs` | Every in-scope rule of those packs | `explicit` |

In `explicit` mode a session without `jurisdictions.packs` returns `400 invalid_request`.

## Pass the signer's location

Location is asserted by you. Esign Comply does not choose law from an IP address, and neither should your code.

```ts
const { data: session, error } = await esc.sessions.create(
  {
    profile: "prof_signup_4f1a",
    signer: {
      external_id: "user_7c1d",
      email: "dana@example.org",
      class: "consumer",
      country: "US",
      region: "US-CA", // from your signup form's State field or your account data
    },
    documents: [{ document: "doc_8Hq2", version: "current" }],
    context: { url: "http://localhost:3000/signup", locale: "en-US", purpose: "account_signup" },
  },
  { idempotencyKey: "signup-user_7c1d" },
);
if (error) throw new Error(`${error.code}: ${error.message}`);
```

- `signer.region` is an ISO 3166-2 code (`US-CA`) or a bare subdivision code with `signer.country` (`CA` with `US`). It is normalized to ISO 3166-2 before sealing. A value in neither form adds the warning `signer_region_unrecognized`.
- It means the state where the signer resides or, for the `employee` class, primarily works.
- `signer.locality` (for example `NYC`) is optional and read only by rules that declare a locality scope.
- `signer.country` selects the base pack outside the United States: EU and EEA countries map to `EU`, `GB` to `UK`, `CH` to `CH`. A region that starts with `US-` implies the United States.
- `signer.class` is `consumer`, `business` or `employee`. Where it is missing, rules treat the signer as the most protected class in scope.

If your form has no State field, add one. Do not guess.

## Unknown state

When a U.S. signer has no `signer.region` and the profile enables state packs, `on_unknown_region` decides:

| Value | Behavior |
|---|---|
| `strictest` (default) | Every enabled state pack applies. Warning `signer_region_missing`. |
| `base_only` | `US-FED` applies alone. Warning `signer_region_missing`. |
| `reject` | The session is refused with [`signer_region_required`](https://esigncomply.com/docs/api/errors.md#signer_region_required). |

When the country is unknown as well, every enabled pack applies with reason `strictest` and the warning `signer_country_missing`. When the country is known and no pack covers it, the warning is `signer_country_not_covered:<country>`.

## A state without a pack

When `signer.region` names a state that has no pack, `US-FED` applies and the session carries the warning `state_pack_unavailable:<code>`, for example `state_pack_unavailable:US-WA`. The record states that no state-specific rules were applied for the signer's location. Do not tell the user the flow meets that state's law.

The same warning appears in live mode for a state pack that is still a research draft: it is not applied to live sessions until counsel admitted in that state has reviewed it. In test mode the draft pack applies in full so you can build against it.

## Governing law

`governing_law` on the profile, or `jurisdictions.governing_law` on one session, names the law your documents choose. In `auto` mode it applies that pack with reason `governing_law` and fires only the rules triggered by governing law, such as evidence wording. If the code has no pack, the session proceeds with the warning `governing_law_no_pack:<code>`.

The forum for a dispute is not a session field. You choose it when you request a certificate. See [Certificates](https://esigncomply.com/docs/guides/certificates.md).

## Session overrides

A session may narrow or redirect the profile's packs for one ceremony:

```json
{
  "jurisdictions": { "mode": "explicit", "packs": ["US-FED", "US-CA"], "governing_law": "US-NY" }
}
```

- A session may narrow the profile's packs freely.
- It may add a pack the profile does not enable only when `allow_session_packs` is true. A pack added by a session is not part of the profile's baseline, so its record conditions run in advise and add no required step.
- Otherwise the session proceeds under the profile's packs with the warning `jurisdiction_not_enabled:<code>`, and the record says the named pack was not applied.
- With `strict_jurisdictions: true` the session is refused with [`jurisdiction_not_enabled`](https://esigncomply.com/docs/api/errors.md#jurisdiction_not_enabled) instead.

Disabling a pack on a profile with live traffic never causes an error by default. See the [compatibility contract](https://esigncomply.com/docs/concepts/compatibility.md).

## Facts

Some rules depend on facts only you know: whether a subscription has a free trial, which state a company is formed in, whether a document is a noncompete. Pass them in `context.facts`:

```json
{
  "context": {
    "purpose": "auto_renewal",
    "facts": { "subscription.trial_days": 14, "subscription.auto_renews": true, "document_category": "other" }
  }
}
```

- Each pack in the catalogue lists the fact keys its rules read, with type, allowed values and rule IDs. Read them from the [pack pages](https://esigncomply.com/docs/jurisdictions.md).
- Facts are sealed in the record and labeled asserted. Esign Comply does not verify them.
- A boolean flag you do not send is treated as not flagged.
- When a rule that fired needs a fact that is absent, the session carries `fact_missing:<key>` and the rule does not fire. Its obligations and recommendations are still listed.
- For an adopted Block condition in live mode the session is refused with [`jurisdiction_fact_required`](https://esigncomply.com/docs/api/errors.md#jurisdiction_fact_required). The error names the key in `param` and the rule ID in `rule`.
- A key that no rule reads is stored as sent with the warning `fact_unrecognized:<key>`. It is never rejected. Fact keys are never renamed.

The `document_category` fact also feeds the exclusion screen. A category blocked by any applied pack returns [`document_type_excluded`](https://esigncomply.com/docs/api/errors.md#document_type_excluded) with the rule ID. A category that needs review adds `document_type_requires_review:<exclusion id>`. The general exclusions of the Federal pack screen every session.

## Read what was applied

Session creation returns the resolution. Use it at run time. Do not hard-code which state rules apply.

```json
{
  "applied_jurisdictions": [
    { "code": "US-FED", "version": "2026-11-21", "reason": "base" },
    { "code": "US-CA", "version": "2026-11-21", "reason": "signer_region" },
    { "code": "US-NY", "version": "2026-11-21", "reason": "governing_law" }
  ],
  "jurisdiction_mode": "auto",
  "rule_set_version": "2026.11.21",
  "rules_fired": ["US-01", "US-08", "US-09", "US-11"],
  "required_steps": ["client.attached", "document.presented:dv_3kT9", "notice.captured", "intent.captured", "signature.applied"],
  "required_strings": [],
  "retention_floor": null,
  "guidance_release": "2026.11.3",
  "advisories": [],
  "warnings": []
}
```

| Field | What to do with it |
|---|---|
| `applied_jurisdictions` | Log it. The same list is sealed in the record under `jurisdictions.applied`. |
| `rules_fired` | Rule IDs that fired. Each links to the catalogue. |
| `required_steps` | The authoritative step list. Render a state-specific step only when this list contains it. |
| `required_strings` | Wording a pack asks the page to carry. Render each one in the slot it names. |
| `retention_floor` | The longest floor among applied packs, when one applies |
| `advisories` | Record conditions in advise that were not met. They never change the status code or `required_steps`. |
| `warnings` | Non-blocking concerns. The list is open. |

Each `required_strings` entry has this shape:

```json
{
  "slot": "renewal_consent",
  "block": "us.purchase",
  "rule": "US-20",
  "kind": "verbatim",
  "text": "I agree that my subscription continues and renews automatically every {renewal term} at {price}{, which may change to {new price} on {date}} until I cancel. {Minimum purchase obligation, if any.} Cancellation policy: {cancellation policy}. I can cancel at {cancel path}.",
  "label": "us.purchase renewal consent (unchecked; by Esign Comply policy separate from the terms checkbox)",
  "statutory": false,
  "check": true
}
```

`kind` is `verbatim` (text with `{slots}` you fill in) or `elements` (a list of required elements you supply). `statutory: true` marks text quoted from a statute: render it exactly. `check: true` means the conformance engine looks for the wording in the captured assent region ([CR-20](https://esigncomply.com/docs/conformance.md#cr-20)). `check: false` marks wording that lives outside the ceremony, such as a reminder email. The browser SDK returns the same list from `ceremony.requiredStrings()`.

## Composition

When several packs apply, they compose:

- Required steps are the union across applied packs.
- For each parameter the most protective value wins: the longest retention floor, the stricter signature method, the larger minimum text size.
- Exclusion screens are a union. A document category blocked by any applied pack is blocked.
- Where two packs dictate wording for the same slot, the catalogue publishes a merged string that carries every required element.

## Warnings you may see

| Warning | Meaning |
|---|---|
| `signer_country_missing` | No `signer.country` and none could be inferred |
| `signer_region_missing` | U.S. signer without a state; `on_unknown_region` was applied |
| `signer_region_unrecognized` | `signer.region` is not an ISO 3166-2 code |
| `signer_country_not_covered:<country>` | No pack covers the signer's country; every enabled pack was applied |
| `signer_class_missing` | A purchase-type purpose without `signer.class` |
| `state_pack_unavailable:<code>` | No pack for that state, or the pack is a research draft and the session is live |
| `jurisdiction_not_enabled:<code>` | A matching pack exists and the profile does not enable it |
| `governing_law_no_pack:<code>` | `governing_law` names a jurisdiction with no pack |
| `fact_missing:<key>`, `fact_unrecognized:<key>` | See [Facts](#facts) |
| `document_type_requires_review:<id>` | The exclusion screen flagged the document category for review |
| `record_conditions_pending_adoption` | Live session on a profile with record conditions waiting in advise |
| `pack_version_stale` | The profile's baseline is more than 12 months behind the latest pack version. Recording continues. |
| `pack_not_counsel_reviewed:<code>` | Live session under a pack whose record conditions are not yet counsel-reviewed. They run in advise. |

Warnings never block. Treat unknown entries as information.

## Dry run

`POST /v1/jurisdictions/resolve` accepts the same inputs as session creation and returns the resolution without creating a session. Nothing is metered.

```bash
curl https://esigncomply.com/v1/jurisdictions/resolve \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "prof_signup_4f1a",
    "signer": { "class": "consumer", "country": "US", "region": "US-CA" },
    "documents": [{ "document": "doc_8Hq2", "version": "current" }],
    "context": { "purpose": "auto_renewal" }
  }'
```

Any secret key can call it. Only `profile` is required. The response has `object: "jurisdiction_resolution"` and the same fields as above, plus:

| Field | Content |
|---|---|
| `rule_states[]` | For each fired rule with a record condition: `rule`, `state` (`enforce` or `advise`) and `level` (`block` or `warn`) |
| `exclusions[]` | Exclusion-screen hits for the declared `document_category` |
| `obligations[]`, `recommendations[]`, `reports[]` | The parts of the resolved rules that are yours, each with rule ID, pack, text and sources |
| `baseline` | `current` or `latest`, as requested |
| `would_fail` | Present when session creation would be refused for an excluded document category or a missing fact: `code`, `message`, `rule`. The dry run itself still returns `200`. |

Two inputs change what the dry run enforces:

- `baseline: "latest"` shows what adoption of pending record conditions would require. The default, `"current"`, shows what the profile's baseline enforces today.
- `livemode: true` previews live behavior with a test key. Without it, a test key shows what test mode does: every condition of the latest release enforced, and research-draft state packs applied.

The conformance checker uses the same call: `npx esigncomply check --region US-CA --region US-NY`. See the [Jurisdictions API](https://esigncomply.com/docs/api/jurisdictions.md).

## What a pack is not

- A pack records which rules Esign Comply applied. It is not a statement that a flow meets the law of a jurisdiction.
- A pack covers selected rules, not every law in that state or country. Each pack lists the topics it covers in `coverage[]` and the topics it does not in `not_covered[]`. Read both on the pack's page.
- State packs are research drafts until reviewed by counsel admitted in that state. `reviewed_at` is `null` until then, and a draft state pack runs in test mode only.
- A pack does not perform your duties. Rules are split into parts: what Esign Comply records or checks, your obligations, recommendations, and what you can send. Esign Comply lists the obligations and does not perform, monitor or verify them. See [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md).
- Later pack versions never change a sealed record. The record keeps the pack versions, the asserted inputs and each condition's state as they were.

Your team is responsible for legal review and for building and sending post-signing notices. Ask your counsel whether your documents and signers have requirements beyond those a pack describes.
