# Guidance and adoption

> How rule changes reach you as notices, why they never stop an existing integration from recording, and how to adopt or roll back new record conditions.

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

Rules, obligations, recommendations and legal notices change far more often than an API should. Esign Comply publishes them as data on their own release train, separate from code deployments and separate from the API contract. You and your AI coding tool can read every change, and nothing in a guidance release can stop an existing integration from recording.

A guidance update does not break your existing recording integration. You may still need to change your flow to meet a new legal requirement. That decision is yours.

## What guidance contains

| Item | What it is | Where you meet it |
|---|---|---|
| Pack version | The rules of one jurisdiction pack, each split into parts with a class | Session resolution, conformance findings, reports |
| Obligation | A duty the cited law places on you, with its source, scope and duty holder | The generated prompt, the dashboard obligations list, `GET /v1/profiles/{id}/guidance` |
| Recommendation | A practice Esign Comply suggests | Same |
| Fixed string | Wording the law constrains, with slots | `required_strings[]`, prompt blocks |
| Prompt block | Reviewed text for AI coding tools | The prompt generator |
| Notice | A dated message about a legal or product change in a state, country or locality | Inbox, email, webhook, feeds, API |

Each publication is a guidance release with an ID such as `2026.11.3`, a content hash and a changelog. Scheduled releases go out weekly. An urgent release can go out the same business day. Every session and every record carries the `guidance_release` in force, so you can later show what you were told and when.

Guidance is product information drawn from the sources it cites. It is not legal advice and it is not exhaustive.

## Notices

A notice (`ntc_...`) tells you about one change:

```json
{
  "object": "guidance_notice",
  "id": "ntc_2026_0931",
  "release": "2026.11.3",
  "published_at": "2026-11-17T15:00:00Z",
  "kind": "law_effective",
  "class": "obligation",
  "severity": "action_required",
  "jurisdictions": ["US-NY", "US-NY/NYC"],
  "topics": ["auto_renewal", "cancellation"],
  "title": "New York City: online cancellation after in-person signup",
  "summary": "...",
  "effective_at": "2026-10-01T04:00:00Z",
  "what_changes": { "esign_comply_record": "None.", "your_obligations": "...", "recommendations": "..." },
  "affected_rules": ["NY-07"],
  "affected_profiles": ["prof_signup_4f1a"],
  "requires_code_change": "only_to_follow_the_rule",
  "update_prompt": "upd_7c1e",
  "review": { "state": "research_reviewed", "counsel_reviewed_at": null },
  "sources": [{ "title": "...", "url": "..." }],
  "supersedes": null,
  "url": "https://esigncomply.com/docs/guidance/ntc_2026_0931",
  "acknowledgment": { "state": "unread", "note": null, "at": null }
}
```

| Field | Values |
|---|---|
| `kind` | `law_enacted`, `law_effective`, `rule_change`, `case_law`, `regulator_guidance`, `enforcement_action`, `correction`, `product` |
| `class` | `record_change` (Esign Comply's own behavior changes), `obligation`, `recommendation`, `information` |
| `severity` | `action_required`, `recommended`, `info` |
| `jurisdictions` | A pack code, an ISO 3166-1 country (`DE`), an ISO 3166-2 subdivision (`US-IL`), or a locality (`US-NY/NYC`) |
| `review.state` | `draft`, `research_reviewed`, `counsel_reviewed` |

`GET /v1/guidance/notices` and `GET /v1/guidance/notices/{id}` work without a key and then return the public fields only. With a secret key they add `affected_profiles` and your domain's `acknowledgment`.

Treat all of these lists as open: new values may appear without a new API version. A notice may cover a place that has no pack yet, so you can hear about a change before a pack exists. An item found to be wrong is corrected by a new notice that supersedes it. The earlier one stays readable and is marked superseded.

## The three-way split

Every notice states three things separately in `what_changes`, even when one of them is "None":

| Key | Question it answers |
|---|---|
| `esign_comply_record` | What changes in what Esign Comply records or checks? |
| `your_obligations` | What changes in the duties the law places on you? Esign Comply lists these. It does not perform, monitor or verify them. |
| `recommendations` | What does Esign Comply suggest? Recommendations are not legal requirements or conditions of recording. |

`requires_code_change` then says whether your code must change:

| Value | Meaning |
|---|---|
| `no` | Nothing to build |
| `only_to_follow_the_rule` | Recording is unaffected. You change your flow only if you decide to follow the obligation or recommendation. |
| `to_adopt_a_record_condition` | A new record condition is waiting in advise. Your interface must satisfy it before you adopt it. |

A notice never says that your flow is or is not lawful.

## Channels

| Channel | Behavior |
|---|---|
| Dashboard inbox | With an unread count |
| Email | To organization owners and to a notices address you configure. At once for `action_required`, weekly digest otherwise. |
| Webhooks | `guidance.notice_published` and `guidance.release_published` |
| API | `GET /v1/guidance/notices` with filters `jurisdiction`, `class`, `severity`, `kind`, `topic`, `since`, `affecting_profile` |
| Public changelog | Atom and JSON feeds, filterable by jurisdiction |

A notice reaches your domain when its jurisdictions overlap your enabled packs, your watched jurisdictions or your organization's own country and state, and its topics overlap your profiles' purposes, document types or facts. Every notice is also in the public feed, which is open to everyone. Dashboard, email, webhook and API delivery are included in every paid plan.

### Watch a jurisdiction

You can watch any jurisdiction code without enabling a pack, for example `US-IL` or `FR`, to receive its notices. The call replaces the whole list and needs a `full_access` key. Up to 100 codes.

```bash
curl -X PUT https://esigncomply.com/v1/domains/dom_4Kx9/watched-jurisdictions \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jurisdictions": ["US-IL", "FR", "US-NY/NYC"] }'
```

See the [Guidance API](https://esigncomply.com/docs/api/guidance.md).

### Forward notices from a webhook

The handler forwards the notice to people. It never changes application behavior by itself.

```ts
// app/api/esigncomply/webhook/route.ts
import { esc } from "@/lib/esigncomply";
import { sendAdminEmail } from "@/lib/email"; // your own mailer

export const runtime = "nodejs";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const { data: event, error } = esc.webhooks.verify(rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!);
  if (error) return new Response("Invalid signature", { status: 400 });

  if (event.type === "guidance.notice_published") {
    const { data: notice } = await esc.guidance.notices.get(event.data.notice_id);
    if (notice) {
      await sendAdminEmail({
        subject: `[Esign Comply] ${notice.severity}: ${notice.title}`,
        text: [
          notice.summary,
          `Record: ${notice.what_changes.esign_comply_record}`,
          `Your obligations: ${notice.what_changes.your_obligations}`,
          `Recommendations: ${notice.what_changes.recommendations}`,
          `Code change: ${notice.requires_code_change}`,
          notice.update_prompt ? `Update prompt: ${notice.update_prompt}` : "",
        ].join("\n\n"),
      });
    }
  }

  // Ignore event types you do not recognize and return 200.
  return new Response(null, { status: 200 });
}
```

Handle deliveries idempotently on `webhook-id`. If you prefer polling, call `GET /v1/guidance/notices?since=<last check>` on a schedule. See [Webhooks](https://esigncomply.com/docs/api/webhooks.md).

## Acknowledgments

An owner, admin or developer may mark a notice `read`, `applied` or `not_applicable`, with a note. Through the API this needs a `full_access` key:

```bash
curl https://esigncomply.com/v1/guidance/notices/ntc_2026_0931/acknowledge \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "state": "applied", "note": "Cancellation link added to account settings." }'
```

```json
{ "object": "guidance_acknowledgment", "notice_id": "ntc_2026_0931", "state": "applied", "note": "Cancellation link added to account settings." }
```

- Acknowledgment never gates recording.
- Unacknowledged `action_required` notices are repeated by email at 7 and 30 days.
- Esign Comply keeps a delivery log per domain: each notice delivery (channel, address or endpoint, time, result) and each acknowledgment (member, time, state). You can export it.
- An acknowledgment is your own working note. It is not a finding that an obligation was met, and it never appears on an evidence report or a certificate.

## Update prompts

A notice that changes what you build carries an update prompt (`upd_...`): a short reviewed block that describes only the change, under the same four headings as the original prompt: "Required for the record", "Your obligations", "Recommendations" and "What you can send us". It names the prompt ID it updates and opens with a line that says your existing integration keeps recording whether or not you apply it.

Fetch it with `GET /v1/guidance/updates/upd_7c1e`, or `esc.guidance.updates.get("upd_7c1e")`. The response is JSON with the prompt in a `markdown` field. Send `Accept: text/markdown` to get the raw Markdown instead. Give it to your coding tool under review. Applying it is your choice. Code built from any earlier prompt keeps working against the API version it was written for.

## Advise until adopted

Only record conditions can refuse to seal a record, add a required step or require a fact. And only the ones your profile has adopted.

Each profile has a **baseline**: the pack versions whose record conditions it has adopted. Creating a profile adopts every record condition of the packs it enables at that moment. A record condition that arrives later, from a newer pack version or from a pack you have just enabled, runs in the `advise` state for that profile:

- It is evaluated on every session.
- Its result is stored beside the record and returned in `advisories[]`, each with the rule ID and a finding.
- It never returns an error and never adds to `required_steps`.
- Live sessions on that profile carry the warning `record_conditions_pending_adoption`.

Everything that cannot stop a call applies to every profile at its `effective_at`: obligations, recommendations, notices, evidence wording and fixed-string text. A relaxed or retired record condition also stops blocking at once.

Test mode always evaluates the latest release with every condition enforced, so you see what adoption would require before it reaches live traffic. Test mode still never blocks on a finding: it reports them. The dry run does the same comparison with `baseline: "latest"`. See [Jurisdiction packs](https://esigncomply.com/docs/guides/jurisdictions.md).

### See what is pending

`GET /v1/profiles/prof_signup_4f1a` lists the conditions waiting for adoption:

```json
{
  "object": "profile",
  "id": "prof_signup_4f1a",
  "version": 3,
  "jurisdictions": ["US-FED", "US-CA", "US-NY"],
  "baseline": "bl_7Qm2",
  "pending_conditions": [
    { "rule": "CA-08", "pack": "US-CA", "level": "block", "reason": "new_pack" },
    { "rule": "NY-03", "pack": "US-NY", "level": "warn", "reason": "changed" }
  ]
}
```

`reason` is `new_pack` (you enabled the pack after the baseline was set), `new_rule` (a newer pack version added the rule) or `changed` (the rule's record condition changed).

`GET /v1/profiles/{id}/guidance` returns everything that applies to the profile now, grouped by class:

| Group | Each item carries |
|---|---|
| `record_conditions[]` | `rule`, `pack`, `title`, `text`, `level` (`block` or `warn`), `adoption` (`adopted` or `pending`), `adds_steps`, `checks`, `sources`, `review_state` |
| `obligations[]` | `rule`, `pack`, `title`, `duty_holder`, `text`, `sources`, `review_state`, your team's `mark`, and `reports_received` (a count of supplements that name the rule) |
| `recommendations[]` | `rule`, `pack`, `title`, `text`, `sources`, `review_state`, your team's `mark` |
| `reports[]` | `rule`, `pack`, `title`, `text`, `supplement_types` you can send |

A `mark` (`handled`, `not_applicable` or `open`) is your team's working note. `reports_received` is information for you. Neither is a finding that an obligation was met, and neither appears on an evidence report or a certificate.

### Adopt

1. Read the notice and the update prompt.
2. Apply the update prompt in your codebase and run it in test mode, where the new condition is already enforced.
3. Run the conformance check and fix findings marked `block`. See [Conformance](https://esigncomply.com/docs/conformance.md).
4. Adopt:

```bash
curl -X POST https://esigncomply.com/v1/profiles/prof_signup_4f1a/adopt \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Adopted after test run on 2026-12-02." }'
```

Adoption needs a `full_access` key. It moves every pending record condition of the profile's packs to `enforce`, and writes a new baseline and a new profile version. The response is the profile at its new version, with what was adopted:

```json
{
  "object": "profile",
  "id": "prof_signup_4f1a",
  "version": 4,
  "jurisdictions": ["US-FED", "US-CA", "US-NY"],
  "baseline": "bl_9Rk4",
  "change_note": "Adopted after test run on 2026-12-02.",
  "adopted": [
    { "rule": "CA-08", "pack": "US-CA", "level": "block", "adds_steps": ["renewal_terms.presented", "renewal_consent.captured"] },
    { "rule": "NY-03", "pack": "US-NY", "level": "warn", "adds_steps": [] }
  ],
  "baseline_detail": {
    "id": "bl_9Rk4",
    "pack_versions": { "US-FED": "2026-11-21", "US-CA": "2026-11-21", "US-NY": "2026-11-21" },
    "rollback_until": "2027-03-02T16:20:11.402Z"
  }
}
```

The other profile fields are omitted here. The `profile.adopted` webhook follows:

```json
{
  "object": "event",
  "id": "whe_3Yb8",
  "type": "profile.adopted",
  "api_version": "2026-11-21",
  "livemode": true,
  "created_at": "2026-12-02T16:20:11.402Z",
  "data": {
    "profile_id": "prof_signup_4f1a",
    "profile_version": 4,
    "baseline": "bl_9Rk4",
    "adopted_rules": ["CA-08", "NY-03"],
    "adopted_by": "key:key_2bQ1"
  }
}
```

Sessions already created keep the profile version they pinned. If nothing is pending, the call returns [`baseline_unchanged`](https://esigncomply.com/docs/api/errors.md#baseline_unchanged) (409).

Esign Comply never adopts on your behalf. A record condition also enforces in live mode only once counsel has reviewed its pack. Until then it runs in advise even after adoption, and sessions carry `pack_not_counsel_reviewed:<code>`.

### Roll back

```bash
curl -X POST https://esigncomply.com/v1/profiles/prof_signup_4f1a/rollback \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

Rollback returns the profile to its previous baseline, writes a new profile version and sends `profile.rolled_back`. The response is the profile at its new version with `baseline_detail`. It is available for 90 days after an adoption. After that, or when there is no earlier baseline, the call returns [`rollback_unavailable`](https://esigncomply.com/docs/api/errors.md#rollback_unavailable) (409). Records sealed while the newer baseline was in force keep it: a sealed record pins each condition's state and result.

## Adding or removing a state

- **Adding.** Enabling a pack on a profile with live traffic needs no code change to keep recording. The pack's obligations, recommendations and notices apply at once. Its record conditions start in advise, and state-specific steps appear in `required_steps` only after adoption.
- **Removing.** Disabling a pack never causes an error. A session that would have used it proceeds under the remaining packs with the warning `jurisdiction_not_enabled:<code>`, and the record says the pack was not applied.

The full rules are in the [compatibility contract](https://esigncomply.com/docs/concepts/compatibility.md).

## Related webhooks

| Event | Sent when |
|---|---|
| `guidance.notice_published` | A notice that targets your domain was published. Payload: notice ID, kind, class, severity, jurisdictions, `effective_at`, affected profile IDs, update prompt ID. |
| `guidance.release_published` | A guidance release was published that concerns your domain: a pack you enable or a jurisdiction you watch. Payload: `release_id`, `content_hash`, `published_at`, counts `added`, `changed` and `retired`, `jurisdictions`, `url`. |
| `jurisdiction.pack_updated` | A new version of a pack enabled on one of your profiles was published. Payload: `code`, `previous_version`, `version`, `effective_at`, `adds_block_rule`, `adds_required_step`, `affected_profiles`. |
| `profile.adoption_available` | A guidance release left a profile with record conditions waiting in advise. Payload: `profile_id`, `profile_version`, `pending_rules`, `pack_versions`, `url`. |
| `profile.adopted`, `profile.rolled_back` | A member or key adopted, or the profile returned to its previous baseline |
