Skip to content

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-xx state pack implies US-FED: the API adds it and reports it with reason base. A state pack holds only differences from US-FED and 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.