Skip to content

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

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

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

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

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

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

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.