Guidance and adoption
Read guidance notices, releases and update prompts, see what applies to a profile, and adopt or roll back record conditions.
Rules, obligations, recommendations and legal notices change more often than an API should. Esign Comply publishes them as data on their own release train, separate from the API contract. Nothing in a guidance release can stop an existing integration from recording: a new blocking condition runs in the advise state for an existing profile until you adopt it.
Guidance is product information drawn from the sources it cites. It is not legal advice and it is not exhaustive. A notice never says that your flow is or is not lawful. For how to work with notices and adoption, read the guidance guide and the compatibility contract.
| Method and path | Key | Purpose |
|---|---|---|
GET /v1/guidance/notices |
None, or secret (any permission) | List notices. With a key: your domain's notices with acknowledgment state. |
GET /v1/guidance/notices/{id} |
None, or secret (any permission) | Read one notice. |
POST /v1/guidance/notices/{id}/acknowledge |
Secret (full_access) |
Mark a notice read, applied or not_applicable. |
GET /v1/guidance/releases |
None, or secret | Release list with changelogs. |
GET /v1/guidance/releases/{id} |
None, or secret | One release. |
GET /v1/guidance/updates/{update_prompt_id} |
Secret (any permission) | An update prompt, as JSON or Markdown. |
GET /v1/profiles/{id}/guidance |
Secret (any permission) | Everything that applies to a profile now. |
GET /v1/domains/{id}/watched-jurisdictions |
Secret (any permission) | Read the jurisdictions a domain watches. |
PUT /v1/domains/{id}/watched-jurisdictions |
Secret (full_access) |
Set the jurisdictions a domain watches without enabling a pack. |
POST /v1/profiles/{id}/adopt |
Secret (full_access) |
Move pending record conditions from advise to enforce. |
POST /v1/profiles/{id}/rollback |
Secret (full_access) |
Return to the previous baseline. |
Guidance reads are never metered. Public reads are cacheable for 5 minutes.
List notices
GET /v1/guidance/notices
Key: none, or a secret key with any permission.
Without a key the response is the public feed: every published notice, public fields only. With a key the response is your domain's inbox: the notices that reach the domain, each with affected_profiles and your acknowledgment. A notice reaches a domain when its jurisdictions overlap the packs enabled on the domain's profiles, the domain's watched jurisdictions, or the organization's own country and state.
Query parameters
| Parameter | Description |
|---|---|
jurisdiction |
A pack code, country, subdivision or locality, for example US-NY. A subdivision also matches its localities (US-NY/NYC). |
class |
record_change, obligation, recommendation or information. |
severity |
action_required, recommended or info. |
kind |
See notice kinds. |
topic |
One topic, for example auto_renewal. |
since |
RFC 3339 timestamp. Notices published after it. |
affecting_profile |
A profile ID. Only with a key. |
Example request
curl "https://esigncomply.com/v1/guidance/notices?jurisdiction=US-NY&since=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"object": "list",
"has_more": false,
"data": [
{
"object": "guidance_notice",
"id": "ntc_2026_0931",
"release": "2026.11.3",
"published_at": "2026-11-17T15:00:00.000Z",
"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:00.000Z",
"what_changes": {
"esign_comply_record": "None.",
"your_obligations": "...",
"recommendations": "..."
},
"affected_rules": ["NY-07"],
"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",
"affected_profiles": ["prof_signup_4f1a"],
"acknowledgment": { "state": "unread", "note": null, "at": null }
}
]
}
The list is not paginated: has_more is always false. Narrow it with since and the other filters. Newest first.
Retrieve a notice
GET /v1/guidance/notices/{id}
Key: none, or a secret key with any permission. With a key the response adds affected_profiles and acknowledgment.
Example request
curl https://esigncomply.com/v1/guidance/notices/ntc_2026_0931
Example response
200 OK with the notice object. Without a key the fields affected_profiles and acknowledgment are absent.
Errors
not_found: no such notice.
The notice object
| Field | Type | Description |
|---|---|---|
id |
string | ntc_.... Never reused. |
release |
string | The guidance release that published it, for example 2026.11.3. |
published_at |
timestamp | When it was published. |
kind, class, severity |
string | See notice values. All three lists are open. |
jurisdictions |
string[] | One or more of: a pack code, an ISO 3166-1 country (DE), an ISO 3166-2 subdivision (US-IL), or a locality under a subdivision (US-NY/NYC). A notice may cover a place that has no pack yet. |
topics |
string[] | For example auto_renewal, cancellation. |
title, summary |
string | Plain-language text. |
effective_at |
timestamp or null | When the change takes effect. |
what_changes |
object | Three statements, always separate, even when one is "None.": esign_comply_record (what changes in Esign Comply's own record), your_obligations (what changes for you), recommendations (what Esign Comply suggests). |
affected_rules |
string[] | Rule IDs, for example NY-07. |
requires_code_change |
string | no, only_to_follow_the_rule or to_adopt_a_record_condition. |
update_prompt |
string or null | ID of the update prompt, when the notice changes what you build. |
review |
object | state: draft, research_reviewed or counsel_reviewed, and counsel_reviewed_at. Notices, obligations and recommendations may be published at research_reviewed and are labelled as such. |
sources |
array | title and url of each cited source. |
supersedes |
string or null | The notice this one corrects. The earlier notice stays readable. |
url |
string | The public page for the notice. |
affected_profiles |
string[] | With a key: your profiles whose packs the notice touches. |
acknowledgment |
object | With a key: state (unread, read, applied, not_applicable), note, at. |
Notice values
| Field | Values |
|---|---|
kind |
law_enacted, law_effective, rule_change (a pack rule was added, changed or retired), 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 |
requires_code_change |
no: nothing to build. only_to_follow_the_rule: recording continues unchanged; code changes only if you choose to follow the obligation or recommendation in your flow. to_adopt_a_record_condition: a new record condition is waiting in advise; your page may need a change before you adopt it. |
New values can be added at any time. Tolerate values you do not know.
Acknowledge a notice
POST /v1/guidance/notices/{id}/acknowledge
Key: secret key with full_access.
Records that your team has seen a notice. Acknowledgment never gates recording. Unacknowledged action_required notices are repeated by email at 7 and 30 days. Esign Comply keeps a delivery and acknowledgment log per domain.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
state |
string | Yes | read, applied or not_applicable. |
note |
string | No | Up to 2,000 characters. |
Example request
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 the account page." }'
Example response
200 OK
{
"object": "guidance_acknowledgment",
"notice_id": "ntc_2026_0931",
"state": "applied",
"note": "Cancellation link added to the account page."
}
Errors
not_found: no such notice.invalid_request:stateis missing or not one of the three values.insufficient_permission: the key is notfull_access.
List releases
GET /v1/guidance/releases
Key: none, or a secret key.
Each publication of packs, obligations, recommendations, fixed strings, prompt blocks and notices is a guidance release with an ID, a content hash, a signature and a changelog. Scheduled releases go out weekly. Every session and record names the release in force as guidance_release.
Example request
curl https://esigncomply.com/v1/guidance/releases
Example response
200 OK
{
"object": "list",
"data": [
{
"object": "guidance_release",
"id": "2026.11.3",
"content_hash": "sha256:c0de...",
"signature": "eyJhbGciOiJFUzI1NiIs...",
"kid": "esc-content-2026-11",
"published_at": "2026-11-17T15:00:00.000Z",
"changelog": {
"summary": "New York City cancellation notice. US-NY pack 2026-11-17.",
"added": 1,
"changed": 2,
"retired": 0,
"packs": [{ "code": "US-NY", "version": "2026-11-17", "change": "NY-07 scope text updated." }],
"notices": ["ntc_2026_0931"]
}
}
],
"has_more": false
}
The 50 most recent releases are returned, newest first.
Retrieve a release
GET /v1/guidance/releases/{id}
Key: none, or a secret key.
Example request
curl https://esigncomply.com/v1/guidance/releases/2026.11.3
Example response
200 OK with one guidance_release object as shown above.
| Field | Description |
|---|---|
id |
Release ID, for example 2026.11.3. |
content_hash |
Hash of the release content. |
signature, kid |
Signature under the content-signing key and its key ID. |
published_at |
When the release was published. |
changelog |
summary, counts of items added, changed and retired, the packs that got a new version, and the notices in the release. |
Errors
not_found: no such release.
Retrieve an update prompt
GET /v1/guidance/updates/{update_prompt_id}
Key: secret key with any permission.
An update prompt is a short reviewed block for your AI coding tool. It describes only the change, under the same four headings as a generated prompt: "Required for the record", "Your obligations", "Recommendations" and "What you can send us". Applying it is your choice. Code built from an earlier prompt keeps working.
By default the response is JSON. Send Accept: text/markdown to get the Markdown alone.
Example request
curl https://esigncomply.com/v1/guidance/updates/upd_7c1e \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
-H "Accept: text/markdown"
Example response
200 OK with Content-Type: text/markdown; charset=utf-8
Update upd_7c1e to prompt esc_prompt_7Qm2. Guidance release 2026.11.3. This describes only
what changed. Your existing integration keeps recording whether or not you apply it.
## Required for the record
Nothing changes.
## Your obligations
...
Without the Accept header:
{
"object": "guidance_update",
"id": "upd_7c1e",
"notice": "ntc_2026_0931",
"release": "2026.11.3",
"markdown": "Update upd_7c1e to prompt esc_prompt_7Qm2. ..."
}
Errors
not_found: no such update prompt.
Get the guidance for a profile
GET /v1/profiles/{id}/guidance
Key: secret key with any permission.
Returns everything that applies to a profile now, grouped by class. The lists are resolved for every signer class and purpose the profile can see, so they show every rule the profile could fire. A single session applies a subset: read rules_fired and required_steps on the session for that.
Example request
curl https://esigncomply.com/v1/profiles/prof_signup_4f1a/guidance \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK
{
"object": "profile_guidance",
"profile": { "id": "prof_signup_4f1a", "version": 3, "jurisdictions": ["US-FED", "US-CA", "US-NY"] },
"guidance_release": "2026.11.3",
"baseline": {
"id": "bl_5Tq7",
"pack_versions": { "US-FED": "2026-11-21", "US-CA": "2026-11-21" },
"adopted_at": "2026-11-21T15:00:00.000Z"
},
"record_conditions": [
{
"rule": "US-08",
"pack": "US-FED",
"title": "...",
"text": "...",
"level": "block",
"adoption": "adopted",
"adds_steps": [],
"checks": ["CR-01"],
"sources": [{ "title": "...", "url": "..." }],
"review_state": "counsel_reviewed",
"inference": false
},
{
"rule": "NY-03",
"pack": "US-NY",
"title": "...",
"text": "...",
"level": "block",
"adoption": "pending",
"adds_steps": ["renewal_terms.presented", "renewal_consent.captured"],
"checks": ["CR-10", "CR-22"],
"sources": [{ "title": "...", "url": "..." }],
"review_state": "research_reviewed",
"inference": false
}
],
"obligations": [
{
"rule": "NY-05",
"pack": "US-NY",
"title": "...",
"duty_holder": "Seller",
"text": "...",
"sources": [{ "title": "...", "url": "..." }],
"review_state": "research_reviewed",
"mark": { "state": "open", "note": null, "at": null },
"reports_received": 12
}
],
"recommendations": [
{
"rule": "CA-05",
"pack": "US-CA",
"title": "...",
"text": "...",
"sources": [{ "title": "...", "url": "..." }],
"review_state": "research_reviewed",
"mark": { "state": "open", "note": null, "at": null }
}
],
"reports": [
{
"rule": "NY-05",
"pack": "US-NY",
"title": "...",
"text": "...",
"supplement_types": ["notice.sent"],
"sources": [{ "title": "...", "url": "..." }]
}
],
"required_strings": [],
"mark_note": "Your team's note. Not evidence that the obligation was performed.",
"note": "Esign Comply lists the obligations its rule packs identify and stores the reports you choose to send. It does not perform, monitor or verify them. The lists are not exhaustive and are not legal advice."
}
| Group | What it holds |
|---|---|
record_conditions[] |
Checks Esign Comply runs on its own record. level is block or warn. adoption is adopted (in the profile's baseline, enforced), pending (in advise until you adopt) or not_applicable. adds_steps are the step names the condition adds to required_steps once adopted. checks link to the conformance rules. |
obligations[] |
Duties the cited law places on you, with the duty_holder. Esign Comply does not perform, monitor or verify them. mark is your team's working note from the dashboard (handled, not_applicable or open). reports_received counts the supplements that name the rule. It is information for you, not a finding that the duty was met. |
recommendations[] |
Practices Esign Comply suggests. Never a condition of recording. |
reports[] |
The supplement types that fit a rule, if you want reports on file. See supplements. |
required_strings[] |
Fixed wording the profile's sessions can return, by slot. |
Errors
not_found: no such profile in this domain and environment.
Set watched jurisdictions
PUT /v1/domains/{id}/watched-jurisdictions
Key: secret key with full_access.
A domain can watch any jurisdiction code without enabling a pack, for example US-IL or FR, to receive its notices. The request replaces the whole list. {id} must be the domain the key belongs to.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
jurisdictions |
string[] | Yes | Up to 100 codes. Each is a pack code, an ISO 3166-1 country, an ISO 3166-2 subdivision, or a locality such as US-NY/NYC. Codes are upper-cased and de-duplicated. An empty array clears the list. |
Example request
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"] }'
Example response
200 OK
{
"object": "watched_jurisdictions",
"domain_id": "dom_4Kx9",
"jurisdictions": ["US-IL", "FR", "US-NY/NYC"]
}
Errors
invalid_request: a code has the wrong form, or more than 100 codes were sent.not_found:{id}is not the key's own domain.
Get watched jurisdictions
GET /v1/domains/{id}/watched-jurisdictions
Key: secret key with any permission.
Example request
curl https://esigncomply.com/v1/domains/dom_4Kx9/watched-jurisdictions \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK with the same watched_jurisdictions object. Codes are returned in alphabetical order.
Adopt pending record conditions
POST /v1/profiles/{id}/adopt
Key: secret key with full_access.
Each profile has a baseline: the pack versions whose record conditions it has adopted. Only baseline conditions can refuse to seal, add a required step or require a fact. A condition that arrives later, from a newer pack version or from a pack you have just enabled, runs in the advise state: it is evaluated, its result is stored and returned in advisories[], and it never returns an error. Adoption moves every pending condition to enforce. It creates a new baseline and a new profile version. Esign Comply never adopts on your behalf.
Before you adopt, check what is pending with GET /v1/profiles/{id} (pending_conditions) or the profile guidance above, and run your flow in test mode. Test mode always evaluates the latest release with every condition enforced, so you see what adoption would require before it reaches live traffic.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
note |
string | No | Up to 500 characters. Stored as the new version's change_note. |
Example request
curl https://esigncomply.com/v1/profiles/prof_signup_4f1a/adopt \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: adopt-prof_signup_4f1a-2026-11-3" \
-d '{ "note": "New York renewal steps built and tested." }'
Example response
200 OK. The body is the profile object at its new version, plus adopted and baseline_detail.
{
"object": "profile",
"id": "prof_signup_4f1a",
"version": 4,
"livemode": true,
"name": "Signup",
"jurisdictions": ["US-FED", "US-CA", "US-NY"],
"jurisdiction_mode": "auto",
"method": "checkbox",
"assurance_level": "L1",
"baseline": "bl_8Rw2",
"change_note": "New York renewal steps built and tested.",
"created_at": "2026-11-24T10:12:03.117Z",
"adopted": [
{ "rule": "NY-03", "pack": "US-NY", "level": "block", "adds_steps": ["renewal_terms.presented", "renewal_consent.captured"] }
],
"baseline_detail": {
"id": "bl_8Rw2",
"pack_versions": { "US-FED": "2026-11-21", "US-CA": "2026-11-21", "US-NY": "2026-11-17" },
"rollback_until": "2027-02-22T10:12:03.117Z"
}
}
The example omits some profile fields. After adoption, new sessions on the profile can list the adopted steps in required_steps and can be refused when an adopted block condition is not met. Sessions and records created earlier keep the profile version they pinned. The profile.adopted webhook is sent with profile_id, profile_version, baseline, adopted_rules and adopted_by.
Errors
baseline_unchanged409: nothing is waiting for adoption.not_found404: no such profile.insufficient_permission403: the key is notfull_access.
Roll back an adoption
POST /v1/profiles/{id}/rollback
Key: secret key with full_access. No request body.
Returns the profile to the baseline it had before its latest adoption. Available for 90 days after that adoption (baseline_detail.rollback_until). It creates a new profile version. Records sealed in between keep the conditions that applied to them.
Example request
curl -X POST https://esigncomply.com/v1/profiles/prof_signup_4f1a/rollback \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
Example response
200 OK. The profile object at its new version, plus baseline_detail.
{
"object": "profile",
"id": "prof_signup_4f1a",
"version": 5,
"livemode": true,
"name": "Signup",
"jurisdictions": ["US-FED", "US-CA", "US-NY"],
"baseline": "bl_5Tq7",
"change_note": "Rolled back to baseline bl_5Tq7.",
"created_at": "2026-11-25T08:40:11.902Z",
"baseline_detail": {
"id": "bl_5Tq7",
"pack_versions": { "US-FED": "2026-11-21", "US-CA": "2026-11-21" }
}
}
The profile.rolled_back webhook is sent with profile_id, profile_version, baseline and rolled_back_by.
Errors
rollback_unavailable409: there is no earlier baseline, or the 90-day window has passed.not_found404: no such profile.
Webhooks
| Event | Sent when | data |
|---|---|---|
guidance.notice_published |
A notice that reaches the domain was published. | notice_id, kind, class, severity, jurisdictions, effective_at, affected_profiles, update_prompt |
guidance.release_published |
A guidance release was published that concerns the domain. | release_id, content_hash, published_at, added, changed, retired, jurisdictions, url |
jurisdiction.pack_updated |
A new version of a pack enabled on one of the domain's profiles was published. | code, previous_version, version, effective_at, guidance_release, adds_block_rule, adds_required_step, affected_profiles |
profile.adoption_available |
A guidance release left a profile with record conditions waiting in advise. | profile_id, profile_version, guidance_release, pending_rules, pack_versions, url |
profile.adopted, profile.rolled_back |
A member or key adopted, or the profile returned to its previous baseline. | As shown above |
A handler for guidance.notice_published should forward the title, summary and link to your team. It should not change application behavior by itself. See webhooks.