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.
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:
{
"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 |
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.
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.
Forward notices from a webhook
The handler forwards the notice to people. It never changes application behavior by itself.
// 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.
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:
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." }'
{ "object": "guidance_acknowledgment", "notice_id": "ntc_2026_0931", "state": "applied", "note": "Cancellation link added to account settings." }
- Acknowledgment never gates recording.
- Unacknowledged
action_requirednotices 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.
See what is pending
GET /v1/profiles/prof_signup_4f1a lists the conditions waiting for adoption:
{
"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
- Read the notice and the update prompt.
- Apply the update prompt in your codebase and run it in test mode, where the new condition is already enforced.
- Run the conformance check and fix findings marked
block. See Conformance. - Adopt:
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:
{
"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:
{
"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 (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
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 (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_stepsonly 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.
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 |