Jurisdictions
Read the catalogue of jurisdiction packs and dry-run which packs, rules, steps and strings a session would apply.
Jurisdiction packs are data. Each pack is a versioned rule set for one body of law, published by Esign Comply. A profile enables any set of packs, each session applies the subset that fits the signer and the documents, and the record pins exactly what was applied.
Selecting a pack tells Esign Comply which rules to apply. It is not a determination of which law governs, and a pack is not a statement that a flow meets the law of that jurisdiction. State packs are research drafts until reviewed by counsel admitted in that state.
| Method and path | Key | Purpose |
|---|---|---|
GET /v1/jurisdictions |
None or secret | The catalogue: the latest version of every pack. |
GET /v1/jurisdictions/{code} |
None or secret | One pack with its rules, strings, exclusions, retention floors and fact keys. |
GET /v1/jurisdictions/{code}/versions |
None or secret | Version history and changelog for one pack. |
POST /v1/jurisdictions/resolve |
Secret (any permission) | Dry run: what would apply to a given signer, documents and purpose. Creates nothing. Not metered. |
A rendered copy of the catalogue is at /docs/jurisdictions, with one page per pack, for example /docs/jurisdictions/us-ca.
Pack codes
| Code | Pack |
|---|---|
US-FED |
United States, Federal. Base pack for every U.S. signer. |
US-CA, US-NY, US-FL, US-TX, US-DE, US-VA, US-MA |
California, New York, Florida, Texas, Delaware, Virginia, Massachusetts. |
EU |
Flows subject to EU and EEA rules. |
UK |
Flows subject to UK law. |
CH |
Flows subject to Swiss law. |
- U.S. state codes follow ISO 3166-2. Any
US-xxstate pack impliesUS-FED: the API adds it and reports it with reasonbase. A state pack holds only differences fromUS-FEDand never relaxes a Federal rule. - Read the catalogue at run time and do not hard-code it. New packs need no SDK release.
- Rule IDs, pack codes, step names and string slots are never reused or renumbered. A retired rule stays in the catalogue with
status: "retired". - Enterprise contracts may add organization-scoped custom packs with codes prefixed
X-.
List packs
GET /v1/jurisdictions
Key: none. A secret key is accepted and changes nothing.
Returns one summary per pack, latest version, in catalogue order. A summary has the pack's header fields, a rule_count, and fact_keys as a plain list of key names. It leaves out rules, fixed_strings, exclusions, retention_floors, evidence_wording and sources_watched. Add ?expand=rules to get full pack objects in the list.
Query parameters
| Parameter | Description |
|---|---|
expand |
rules returns full pack objects instead of summaries. |
Example request
curl https://esigncomply.com/v1/jurisdictions
Example response
200 OK
{
"object": "list",
"data": [
{
"object": "jurisdiction_pack",
"code": "US-CA",
"name": "California",
"parent": "US-FED",
"version": "2026-11-21",
"status": "active",
"effective_at": "2026-11-21T00:00:00Z",
"reviewed_at": null,
"review_state": "research_reviewed",
"description": "California's UETA limits how parties agree to transact electronically...",
"content_hash": "sha256:c0de...",
"coverage": ["esign_statute", "consumer_consent", "cancellation", "exclusions", "auto_renewal", "evidence_wording", "retention"],
"not_covered": ["remote_online_notarization", "ccpa_rights_handling", "clause_content_rules"],
"no_difference": ["attribution", "error correction", "legal recognition"],
"guidance_release": "2026.11.3",
"rule_set_version": "2026.11.21",
"prompt_block": "us.state.ca",
"changelog_url": "https://esigncomply.com/docs/jurisdictions/us-ca/changelog",
"rule_count": 16,
"fact_keys": ["document_category", "econsent_basis"]
}
],
"has_more": false,
"guidance_release": "2026.11.3",
"note": "A pack records which rules Esign Comply applies. It is not a statement that a flow meets the law of that jurisdiction (JR-15)."
}
The example shows one of the eleven packs, with shortened lists.
Caching
Catalogue responses carry an ETag and Cache-Control: public, max-age=300. Send the tag back in If-None-Match: an unchanged catalogue answers 304 Not Modified with no body. A new guidance release needs no client change.
Retrieve a pack
GET /v1/jurisdictions/{code}
Key: none or secret.
code is case-insensitive. Without a query parameter the latest version is returned. ?version=2026-11-21 returns that version.
Example request
curl https://esigncomply.com/v1/jurisdictions/US-CA
Example response
200 OK
{
"object": "jurisdiction_pack",
"code": "US-CA",
"name": "California",
"parent": "US-FED",
"version": "2026-11-21",
"status": "active",
"effective_at": "2026-11-21T00:00:00Z",
"reviewed_at": null,
"review_state": "research_reviewed",
"description": "California's UETA limits how parties agree to transact electronically...",
"content_hash": "sha256:c0de...",
"coverage": ["esign_statute", "consumer_consent", "cancellation", "exclusions", "auto_renewal", "evidence_wording", "retention"],
"not_covered": ["remote_online_notarization", "ccpa_rights_handling", "clause_content_rules"],
"no_difference": ["attribution", "error correction", "legal recognition"],
"guidance_release": "2026.11.3",
"rule_set_version": "2026.11.21",
"rules": [
{
"id": "CA-01",
"title": "Basis for agreeing to transact electronically",
"summary": "Require a customer-asserted basis for each party's electronic agreement...",
"enforcement": "Block; Obligation",
"status": "active",
"inference": false,
"parts": [
{
"class": "record_condition",
"level": "block",
"summary": "Esign Comply requires a customer-asserted basis for each party's agreement to transact electronically...",
"checks": ["CR-23"],
"requires_facts": ["econsent_basis"]
},
{ "class": "obligation", "duty_holder": "Customer", "summary": "..." }
],
"triggers": ["governing_law"],
"scope": { "text": "All classes; all purposes" },
"adds_steps": [],
"strings": [],
"topics": ["esign_statute", "consumer_consent"],
"legal_basis": [{ "title": "...", "url": "..." }],
"implemented_in": "..."
}
],
"fixed_strings": [
{
"slot": "ca_retention_cancel_control",
"label": "Online retention-offer cancel control",
"rule": "CA-10",
"block": "us.state.ca",
"kind": "elements",
"elements": ["\"click to cancel\" or equivalent wording"],
"basis": [{ "title": "Bus. & Prof. Code § 17602(e)(2)", "url": "..." }]
}
],
"exclusions": [
{
"id": "US-CA/commercial-code",
"category": "Commercial Code Divisions 3, 4, 5, 8, 9 and 11, and Division 1 except §§ 1206 and 1306",
"treatment": "blocked",
"document_categories": ["commercial_code_record"],
"rule": "CA-04",
"basis": [{ "title": "Civ. Code § 1633.3(b)", "url": "..." }]
}
],
"retention_floors": [
{
"rule": "US-20",
"subject": "Auto-renewal consent verification (already US-20)",
"floor": "3 years, or 1 year after termination, whichever is longer",
"years": 3,
"scope": { "signer_class": ["consumer"], "purpose": ["auto_renewal", "free_trial"] },
"basis": [{ "title": "Bus. & Prof. Code § 17602(a)(6)", "url": "..." }]
}
],
"fact_keys": [
{ "key": "document_category", "type": "enum", "values": ["employment", "noncompete", "commission_plan", "..."], "description": "...", "rules": ["..."] }
],
"evidence_wording": [
{ "code": "US-CA", "forum": "California", "rule": "CA-14", "business_records": "...", "declaration_form": "...", "basis": [{ "title": "...", "url": "..." }] }
],
"prompt_block": "us.state.ca",
"sources_watched": [{ "title": "...", "url": "..." }],
"changelog_url": "https://esigncomply.com/docs/jurisdictions/us-ca/changelog"
}
Text values and lists are shortened with ... in this example. The response carries an ETag and a five-minute cache lifetime.
Errors
jurisdiction_unknown (400, param: "code") when the code is not in the catalogue. not_found when the pack has no such version.
Pack fields
| Field | Type | Description |
|---|---|---|
code, name, parent |
string | Pack code, display name, and the base pack (US-FED for state packs, otherwise null). |
version |
string | Date version, for example 2026-11-21. |
status |
active or retired |
|
effective_at |
timestamp | When this version takes effect. |
reviewed_at |
timestamp or null | Counsel review date. Null means research draft. A state pack with reviewed_at: null is applied in test mode only. |
review_state |
string | counsel_reviewed when reviewed_at is set, otherwise research_reviewed. |
content_hash |
string | SHA-256 of the canonical pack content. |
guidance_release |
string | The guidance release that published this version. bundled before the first release is published. |
rule_set_version |
string | The pack version in dotted form, as sessions report it. |
description |
string | One paragraph on what the pack is. |
coverage[], not_covered[] |
string arrays | Topics the pack covers and topics it explicitly does not. A pack covers selected rules, not every law of the jurisdiction. |
no_difference[] |
string array | State packs: topics on which the pack adds nothing to US-FED. |
rules[] |
array | See "Rule fields". |
fixed_strings[] |
array | Wording the law constrains, with slots. Served on sessions as required_strings[]. |
exclusions[] |
array | Document categories that are blocked or flagged. |
retention_floors[] |
array | Minimum retention periods the pack records, each with rule, subject, floor (as text) and, where it can be computed from the signing date, years or months. advisory: true marks a floor that is recorded but not applied. |
fact_keys[] |
array | The context.facts keys the pack's rules read: key, type (boolean, number, string, enum, date, string[]), values for enums, description, rules, and aliases. |
evidence_wording[] |
array | How a statement or declaration is worded for a forum. Used only when a certificate is requested. It never changes ceremony rules. |
prompt_block |
string | ID of the prompt block for this pack. |
sources_watched[] |
array | The official sources Esign Comply reviews for this pack, each with title and optional url. |
changelog_url |
string | Where the pack's changelog is published. |
Rule fields
| Field | Type | Description |
|---|---|---|
id |
string | Stable rule ID: US-01, CA-08, NY-05, EU-10. |
title, summary |
string | Short name and the full product behavior. |
enforcement |
string | The classes of the rule's parts as one label, for example Block; Obligation; Report. |
parts[] |
array | One entry per class. See the next table. |
triggers[] |
array | What fires the rule in auto mode: base, signer_region, governing_law, organization_region. forum selects evidence wording only. |
scope |
object | Narrows the rule: signer_class[], document_type[], purpose[], profile_kind[] (signature, acceptance), locality[], country[], region[], document_category[], facts (conditions on fact keys), and text (the scope in words). |
adds_steps[] |
array | Every step name the rule's record conditions add to required_steps once adopted. |
strings[] |
array | Fixed-string slots whose presence the rule checks. |
legal_basis[] |
array | Sources, each with title and optional url. |
topics[] |
array | Topics used to target guidance notices. |
implemented_in |
string or null | Where the product implements the rule, in words. |
inference |
boolean | True for a row awaiting counsel confirmation. Its record conditions are treated as warn. |
status |
active or retired |
Rule parts
Every part has exactly one class. The class decides who does the work.
class |
Meaning | Extra fields |
|---|---|---|
service |
Esign Comply performs it. The result is part of its own record. | |
record_condition |
A check Esign Comply runs on its own record. Your interface has to satisfy it. | level (block or warn), checks[] (conformance rules such as CR-23), adds_steps[], requires_facts[], strings[] (slots whose presence is checked) |
obligation |
A duty the cited law places on you. Esign Comply lists it and does not perform, monitor or verify it. | duty_holder |
recommendation |
A practice Esign Comply suggests. Never a condition of recording. | |
report |
A supplement you may send about it. | supplement_types[] |
Only record_condition parts can affect a session, and only after the profile has adopted them.
List pack versions
GET /v1/jurisdictions/{code}/versions
Key: none or secret.
Returns the version history of one pack, newest first. Sealed records keep the pack versions they pinned: a later version never changes a record.
Example request
curl https://esigncomply.com/v1/jurisdictions/US-CA/versions
Example response
200 OK
{
"object": "list",
"has_more": false,
"data": [
{
"object": "jurisdiction_pack_version",
"code": "US-CA",
"version": "2026-11-21",
"effective_at": "2026-11-21T00:00:00Z",
"reviewed_at": null,
"review_state": "research_reviewed",
"content_hash": "sha256:c0de...",
"guidance_release": "2026.11.3",
"published_at": "2026-11-21T00:00:00Z",
"changelog": "Initial version.",
"rule_count": 16
}
]
}
Errors
jurisdiction_unknown when the code is not in the catalogue.
Dry-run a resolution
POST /v1/jurisdictions/resolve
Key: secret key with any permission.
Accepts the jurisdiction inputs of POST /v1/sessions and returns the resolution without creating a session. Nothing is stored and nothing is metered. Use it in the profile editor, in CI, and before enabling a pack.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
profile |
string | Yes | Profile ID. |
signer.class |
string | No | consumer, business or employee. |
signer.country |
string | No | ISO 3166-1 alpha-2. |
signer.region |
string | No | ISO 3166-2 (US-CA), or a bare subdivision code with signer.country. |
signer.locality |
string | No | Locality code, for example NYC. |
jurisdictions.mode |
string | No | Overrides the profile's mode for this call. |
jurisdictions.packs |
array | No | Narrows the profile's packs. Required when the mode is explicit. |
jurisdictions.governing_law |
string | No | Overrides the profile's governing law. |
documents[] |
array, up to 10 | No | { "document": "doc_...", "version": "current" }, as on a session. Document types feed rule scope, and each version adds a document.presented:<version_id> step. |
context.purpose |
string | No | For example auto_renewal. |
context.facts |
object | No | Asserted facts the rules read. |
context.locale |
string | No | Selects translations when version is current. |
baseline |
current or latest |
No | current (default) uses the profile's adopted baseline. latest shows what would be enforced after adopting every pending condition. |
livemode |
boolean | No | Defaults to the mode of the key. A test key evaluates as test mode does, with every condition enforced and research-draft state packs applied. Send true with a test key to preview live behavior. |
Example request
POST /v1/jurisdictions/resolve
Authorization: Bearer esc_test_us_...
Content-Type: application/json
{
"profile": "prof_signup_4f1a",
"signer": { "class": "consumer", "country": "US", "region": "US-CA" },
"documents": [{ "document": "doc_8Hq2", "version": "current" }],
"context": { "purpose": "auto_renewal" }
}
Example response
200 OK
{
"object": "jurisdiction_resolution",
"mode": "auto",
"applied_jurisdictions": [
{ "code": "US-FED", "version": "2026-11-21", "reason": "base" },
{ "code": "US-CA", "version": "2026-11-21", "reason": "signer_region" },
{ "code": "US-NY", "version": "2026-11-21", "reason": "governing_law" }
],
"rule_set_version": "2026.11.21",
"rules_fired": ["US-01", "US-20", "CA-01", "CA-02", "NY-01"],
"rule_states": [
{ "rule": "US-20", "state": "enforce", "level": "block" },
{ "rule": "CA-01", "state": "enforce", "level": "block" }
],
"required_steps": [
"client.attached",
"document.presented:dv_3kT9",
"renewal_terms.presented",
"renewal_consent.captured",
"notice.captured",
"intent.captured",
"signature.applied"
],
"required_strings": [
{
"slot": "renewal_consent",
"block": "us.purchase",
"rule": "US-20",
"kind": "verbatim",
"text": "I agree that my subscription continues and renews automatically every {renewal term} at {price}{, which may change to {new price} on {date}} until I cancel. {Minimum purchase obligation, if any.} Cancellation policy: {cancellation policy}. I can cancel at {cancel path}.",
"statutory": false,
"label": "us.purchase renewal consent (unchecked; by Esign Comply policy separate from the terms checkbox)",
"check": true
}
],
"retention_floor": { "rule": "US-20", "basis": "longest of applied packs", "floor": "3 years, or 1 year after termination, whichever is longer", "years": 3 },
"exclusions": [],
"baseline": "current",
"guidance_release": "2026.11.3",
"obligations": [
{ "rule": "CA-10", "pack": "US-CA", "duty_holder": "Seller", "summary": "...", "sources": [{ "title": "...", "url": "..." }] }
],
"recommendations": [
{ "rule": "CA-05", "pack": "US-CA", "summary": "...", "sources": [{ "title": "...", "url": "..." }] }
],
"reports": [
{ "rule": "CA-10", "pack": "US-CA", "summary": "...", "supplement_types": ["notice.sent", "cancellation.requested"] }
],
"advisories": [],
"warnings": []
}
Resolution fields
| Field | Description |
|---|---|
mode |
The mode used: auto, strictest or explicit. |
applied_jurisdictions[] |
Each applied pack with code, version and reason. |
rule_set_version |
Version of the rule set, taken from the newest applied pack. |
rules_fired[] |
IDs of the rules that fired. |
rule_states[] |
For each fired rule that has a record condition: rule, state (enforce or advise) and level (block or warn). |
required_steps[] |
The steps a session with these inputs would require, in ceremony order. |
required_strings[] |
Wording to render. kind is verbatim (use text, with {slots} you fill, and translations where present) or elements (fill every entry of elements[]). statutory: true means quoted statutory text that cannot be reworded. check: true means its presence in the captured assent region is checked (CR-20). check: false means the wording lives outside the ceremony, for example a renewal reminder: it is served for your prompt and never checked. |
retention_floor |
The longest retention floor among the applied packs, or null. |
exclusions[] |
Exclusion rows hit by the declared document_category: id, category, treatment (blocked or warning), rule, pack. |
obligations[] |
Your duties under the resolved rules, each naming the duty_holder. Esign Comply lists them and does not perform, monitor or verify them. |
recommendations[] |
Practices Esign Comply suggests. Never a condition of recording. |
reports[] |
Supplement types you may send about a rule. Optional. |
advisories[] |
Record conditions in advise that would add steps if adopted: rule, finding, notice. |
warnings[] |
Non-blocking concerns. The list is open. See "Warnings". |
would_fail |
Present only when a session with these inputs would be refused for an excluded document category or a missing fact: code (document_type_excluded or jurisdiction_fact_required), message, rule. The dry run still returns 200 so you can read the rest of the resolution. |
baseline, guidance_release |
The baseline mode used and the guidance release in force. |
Errors
Structural problems are errors, as on a session: jurisdiction_unknown, jurisdiction_not_enabled (strict profiles only), signer_region_required, invalid_request (malformed body, or explicit mode without jurisdictions.packs), not_found for an unknown profile or document, and version_not_published.
document_type_excluded and jurisdiction_fact_required are not returned as errors by the dry run. They appear in would_fail. POST /v1/sessions returns them as 422.
How resolution works
The same logic runs for POST /v1/sessions and for the dry run.
1. Which packs are candidates. The profile's jurisdictions, or the session's jurisdictions.packs when sent. A session may narrow the profile's packs freely. A pack the profile does not enable is added only when allow_session_packs is true. Otherwise the session proceeds under the profile's packs with the warning jurisdiction_not_enabled:<code>, or returns 422 jurisdiction_not_enabled when strict_jurisdictions is true. A pack added by a session is not part of the baseline, so its record conditions run in advise.
2. Which candidates apply, and why.
| Mode | Packs applied | reason |
|---|---|---|
auto (default) |
The base pack for the signer's country (US-FED for US, UK for GB, CH for CH, EU for EU and EEA countries). A state pack when signer.region names it. A pack named by governing_law. A state pack matching your organization's registered state. |
base, signer_region, governing_law, organization_region |
strictest |
Every enabled pack, in full, whatever the signer's location. | strictest |
explicit |
Exactly the packs in jurisdictions.packs, in full. A session without the list returns 400 invalid_request. |
explicit |
3. Unknown or uncovered location, in auto mode.
| Situation | Result |
|---|---|
U.S. signer, no signer.region, state packs enabled |
on_unknown_region decides: strictest applies every enabled state pack, base_only applies US-FED alone, reject returns 422 signer_region_required. The first two add the warning signer_region_missing. |
signer.region names a state with no pack |
US-FED applies, with the warning state_pack_unavailable:<code>, for example state_pack_unavailable:US-WA. The record states that no state-specific rules were applied for the signer's location. A pack applied for another reason, such as governing_law, still applies. |
signer.region names a state whose pack exists but is not enabled on the profile |
US-FED applies, with the warning jurisdiction_not_enabled:<code>. |
Live mode, state pack not yet reviewed by counsel (reviewed_at: null) |
The pack is not applied to live sessions. The session carries state_pack_unavailable:<code>. In test mode the pack applies as a research draft. |
No signer.country and no U.S. region |
Every enabled pack applies with reason strictest, with the warning signer_country_missing. |
| A country no pack covers | Every enabled pack applies with reason strictest, with the warning signer_country_not_covered:<country>. |
Location is asserted. signer.country, signer.region and governing_law come from your form or account data and are tagged asserted in the record. Esign Comply does not choose law from an IP address.
4. Which rules fire. In auto mode a rule fires only when one of its triggers matched the reason the pack applied and its scope fits the signer class, document types, purpose and facts. In strictest and explicit modes every in-scope rule of an applied pack fires. The ESIGN consumer consent rules of US-FED fire only when the profile sets consumer_econsent.
5. Enforce or advise. A record condition is in enforce when the profile's baseline has adopted it and counsel has reviewed its pack. Otherwise it is in advise. Test mode, and a dry run with baseline: "latest", treat every condition as enforced so you can see what adoption would require.
6. Composition. Required steps are the union across applied packs. For each parameter the more protective value wins, for example the longest retention floor. Exclusion screens are a union: a document category blocked by any applied pack is blocked. The general exclusions carried by US-FED screen every session, whichever packs apply. An EU, UK or CH pack switches the session to minimal capture.
Facts
Some rules depend on facts only you know, such as whether a subscription has a free trial. Pass them in context.facts. Each pack lists the keys its rules read in fact_keys[].
| Situation | Result |
|---|---|
| A key no rule reads | Stored as sent, with the warning fact_unrecognized:<key>. Never an error. |
| A rule that fired needs a key that is absent, and its condition is a Warn or is in advise | Warning fact_missing:<key>. The rule does not fire. Its obligations and recommendations are still listed. Reported as CR-24. |
| The same, for an adopted Block condition in live mode | 422 jurisdiction_fact_required. The error names the rule in rule, the key in param (context.facts.<key>) and in fact, and every missing key in facts[]. |
document_category matches an exclusion |
treatment: "blocked" returns 422 document_type_excluded with the rule ID. treatment: "warning" adds document_type_requires_review:<exclusion id> and the ceremony proceeds. |
Facts are sealed in the record and tagged asserted. Esign Comply does not verify them. A fact key is never renamed: a replaced key keeps working as an alias.
Warnings
warnings[] on sessions and dry runs is an open list of strings. Treat unknown values as information.
| Warning | Meaning |
|---|---|
signer_country_missing |
No country was sent and none could be derived from the region. |
signer_region_missing |
U.S. signer without a state, on a profile with state packs. |
signer_region_unrecognized |
signer.region is not an ISO 3166-2 code and could not be normalized. |
signer_country_not_covered:<country> |
No pack covers the signer's country. |
signer_class_missing |
A purchase, trial or renewal purpose was sent without a signer class. The signer is treated as the most protected class in scope. |
state_pack_unavailable:<code> |
The state has no pack, or its pack is a research draft and the session is live. |
jurisdiction_not_enabled:<code> |
A pack that would have applied is not enabled on the profile. |
governing_law_no_pack:<code> |
governing_law names a jurisdiction with no pack. |
fact_missing:<key>, fact_unrecognized:<key> |
See "Facts". |
document_type_requires_review:<exclusion id> |
The declared document category is flagged for review by an applied pack. |
record_conditions_pending_adoption |
Live session on a profile with record conditions waiting in advise. |
pack_version_stale |
The profile's baseline is more than 12 months behind the latest pack version. Recording continues. |
pack_not_counsel_reviewed:<code> |
A non-state pack applied to a live session has no counsel review date yet. |
Related
- Jurisdictions guide: choosing packs, modes and facts.
- Profiles: enabling packs.
- Guidance: notices, adoption and rollback.
- Compatibility contract: why rule changes do not break recording.