# Guidance and adoption

> Read guidance notices, releases and update prompts, see what applies to a profile, and adopt or roll back record conditions.

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

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](https://esigncomply.com/docs/guides/guidance.md) and the [compatibility contract](https://esigncomply.com/docs/concepts/compatibility.md).

| 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](#notice-values). |
| `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**

```bash
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`

```json
{
  "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**

```bash
curl https://esigncomply.com/v1/guidance/notices/ntc_2026_0931
```

**Example response**

`200 OK` with the [notice object](#the-notice-object). Without a key the fields `affected_profiles` and `acknowledgment` are absent.

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#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](#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 {#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**

```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 the account page." }'
```

**Example response**

`200 OK`

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

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found): no such notice.
- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request): `state` is missing or not one of the three values.
- [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission): the key is not `full_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**

```bash
curl https://esigncomply.com/v1/guidance/releases
```

**Example response**

`200 OK`

```json
{
  "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**

```bash
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`](https://esigncomply.com/docs/api/errors.md#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**

```bash
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`

```text
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:

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#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**

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

**Example response**

`200 OK`

```json
{
  "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](https://esigncomply.com/docs/conformance.md). |
| `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](https://esigncomply.com/docs/api/supplements.md). |
| `required_strings[]` | Fixed wording the profile's sessions can return, by slot. |

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#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**

```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"] }'
```

**Example response**

`200 OK`

```json
{
  "object": "watched_jurisdictions",
  "domain_id": "dom_4Kx9",
  "jurisdictions": ["US-IL", "FR", "US-NY/NYC"]
}
```

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request): a code has the wrong form, or more than 100 codes were sent.
- [`not_found`](https://esigncomply.com/docs/api/errors.md#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**

```bash
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**

```bash
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](https://esigncomply.com/docs/api/profiles.md) at its new version, plus `adopted` and `baseline_detail`.

```json
{
  "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_unchanged`](https://esigncomply.com/docs/api/errors.md#baseline_unchanged) `409`: nothing is waiting for adoption.
- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) `404`: no such profile.
- [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) `403`: the key is not `full_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**

```bash
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`.

```json
{
  "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_unavailable`](https://esigncomply.com/docs/api/errors.md#rollback_unavailable) `409`: there is no earlier baseline, or the 90-day window has passed.
- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) `404`: 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](https://esigncomply.com/docs/api/webhooks.md).
