Skip to content

Profiles

Create and version ceremony profiles, the named rule sets that sessions run under.

A ceremony profile is a named rule set: which jurisdiction packs are enabled and how they are selected per session, the signer class, the signature method, the assurance level, and the failure mode. A session names one profile. Every record pins the profile ID and the profile version it was made under.

Profiles are versioned. Creating a profile writes version 1. Every update writes a new version and leaves earlier versions, sessions and records untouched.

Method and path Key Purpose
POST /v1/profiles Secret (full_access) Create a profile.
GET /v1/profiles Secret (any permission) List profiles, latest version of each.
GET /v1/profiles/{id} Secret (any permission) Retrieve a profile with its pending conditions and version history.
POST /v1/profiles/{id} or PATCH /v1/profiles/{id} Secret (full_access) Update a profile. Writes a new version.

Adoption (POST /v1/profiles/{id}/adopt), rollback (POST /v1/profiles/{id}/rollback) and GET /v1/profiles/{id}/guidance are documented under Guidance.

The profile object

{
  "object": "profile",
  "id": "prof_signup_4f1a",
  "version": 1,
  "livemode": false,
  "name": "Signup",
  "jurisdictions": ["US-FED", "US-CA", "US-NY"],
  "jurisdiction_mode": "auto",
  "on_unknown_region": "strictest",
  "governing_law": "US-NY",
  "allow_session_packs": false,
  "strict_jurisdictions": false,
  "pack_versions": "latest",
  "signer_class": null,
  "document_type": null,
  "purpose": null,
  "method": "checkbox",
  "assurance_level": "L1",
  "failure_mode": "fail_closed",
  "consumer_econsent": false,
  "capture_mode": "standard",
  "receipts_enabled": true,
  "signer_certificates_enabled": false,
  "rules_version": "2026.11.3",
  "baseline": "bl_7Yc3",
  "prompt_id": null,
  "change_note": null,
  "created_at": "2026-11-21T15:01:40.207Z"
}
Field Description
id, version Profile ID and the version this object describes. created_at is the time this version was written.
jurisdictions Enabled pack codes, normalized to upper case.
rules_version Guidance release in force when this version was written.
baseline ID of the profile baseline: the pack versions whose record conditions this profile has adopted. See "Baselines" below.
prompt_id ID of the generated prompt that created the profile, when there is one. Read-only.

All other fields are request fields and are described in the next section.

Create a profile

POST /v1/profiles

Key: secret key with full_access. Idempotent with Idempotency-Key.

Request fields

Field Type Default Description
name string, 1 to 120 characters Required Your name for the profile.
jurisdictions array of pack codes, up to 24 ["US-FED"] Packs this profile enables, in any combination. Any US-xx state pack adds US-FED. A code that is not in the catalogue returns jurisdiction_unknown.
jurisdiction_mode auto, strictest, explicit auto How packs are selected per session. auto: by signer location, governing law and your organization's state. strictest: every enabled pack, in full. explicit: each session must send jurisdictions.packs.
on_unknown_region strictest, base_only, reject strictest What to do for a U.S. signer with no signer.region when state packs are enabled. strictest applies every enabled state pack, base_only applies US-FED alone, reject returns signer_region_required.
governing_law string or null null Pack code or ISO 3166 code named as governing law in your documents, for example US-NY. Fires the governing-law rules of that pack. Asserted by you.
allow_session_packs boolean false Lets a session add a pack this profile does not enable. Its record conditions run in advise.
strict_jurisdictions boolean false When true, a session that names a pack this profile does not enable returns jurisdiction_not_enabled instead of a warning.
pack_versions "latest" or object "latest" Map of pack code to version, for Enterprise contracts that pin pack versions. Leave as "latest" otherwise.
signer_class string or null null Class to assume when the session does not send signer.class: consumer, business or employee.
document_type string or null null A document type that is added to rule scope for every session on this profile.
purpose string or null null Purpose to assume when the session does not send context.purpose.
method click, checkbox, typed, drawn, passkey checkbox Signature method. Returned on sessions as signature_method.
assurance_level L1, L2, L3 L1 L1 recorded, L2 adds a one-time code to email or phone, L3 adds a passkey. All three are simple electronic signatures or recorded acceptances.
failure_mode fail_closed, fail_open_deferred fail_closed What your app does when Esign Comply cannot be reached at signing time.
consumer_econsent boolean false Adds the ESIGN consumer consent steps (disclosure, access demonstration, consent) for consumer signers. See the consumer consent guide.
capture_mode standard, eu_minimal standard eu_minimal drops optional markup, style, layout, network and device capture. It is applied automatically whenever an EU, UK or CH pack applies.
receipts_enabled boolean true Whether Esign Comply emails the signer a receipt when an email address is known.
signer_certificates_enabled boolean false Reserved for signer-requested certificates, which are Planned.
change_note string, up to 500 characters, or null null A note stored with this version.

Unknown fields are ignored and reported in warnings as unknown_field:<path>.

Validation

  • method must be one of the five values. passkey needs assurance_level: "L3".
  • fail_open_deferred is accepted only with assurance_level: "L1" and with document_type unset or terms.
  • governing_law must look like a pack code or an ISO 3166 code (US-NY, DE).
  • The plan is checked when a session is created, not here: a profile at L3 on a plan without L3 returns plan_feature_unavailable from POST /v1/sessions.

Example request

curl https://esigncomply.com/v1/profiles \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Signup",
    "jurisdictions": ["US-FED", "US-CA", "US-NY"],
    "jurisdiction_mode": "auto",
    "on_unknown_region": "strictest",
    "governing_law": "US-NY",
    "method": "checkbox",
    "assurance_level": "L1"
  }'

Example response

201 Created. The body is the profile object shown above, plus "warnings": [].

Errors

invalid_request with param naming the field, jurisdiction_unknown, insufficient_permission for a key without full_access.

Baselines

When a profile is created, its first baseline adopts every record condition of the latest version of each pack it enables. Only baseline record conditions can refuse to seal a live record, add a required step, or require a fact. A record condition that arrives later, from a newer pack version or from a pack you enable afterwards, runs in the advise state: it is evaluated, its result is stored and returned in advisories[], and it never returns an error and never adds to required_steps. You move pending conditions to enforce by adopting them. Test mode always evaluates the latest release with every condition enforced, so you can see what adoption would require before live traffic does. Adoption, rollback and the per-profile obligations and recommendations lists are in the Guidance API and the compatibility contract.

List profiles

GET /v1/profiles

Key: secret key with any permission.

Returns the latest version of every profile, newest first. The list is not paginated: has_more is always false.

Example request

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

Example response

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "profile",
      "id": "prof_signup_4f1a",
      "version": 1,
      "livemode": false,
      "name": "Signup",
      "jurisdictions": ["US-FED", "US-CA", "US-NY"],
      "jurisdiction_mode": "auto",
      "on_unknown_region": "strictest",
      "governing_law": "US-NY",
      "method": "checkbox",
      "assurance_level": "L1",
      "failure_mode": "fail_closed",
      "baseline": "bl_7Yc3",
      "created_at": "2026-11-21T15:01:40.207Z"
    }
  ],
  "has_more": false
}

The example is shortened. Each item is a full profile object.

Retrieve a profile

GET /v1/profiles/{id}

Key: secret key with any permission.

Returns the latest version of the profile with two extra arrays.

Field Description
pending_conditions[] Record conditions that are in advise for this profile and can be adopted. Each has rule (rule ID), pack (pack code), level (block or warn) and reason (new_rule, changed or new_pack). Empty when nothing is pending.
versions[] Version history, newest first. Each has version, created_at, change_note and baseline.

Example request

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

Example response

200 OK

{
  "object": "profile",
  "id": "prof_signup_4f1a",
  "version": 2,
  "livemode": false,
  "name": "Signup",
  "jurisdictions": ["US-FED", "US-CA", "US-NY", "US-TX"],
  "jurisdiction_mode": "auto",
  "on_unknown_region": "strictest",
  "governing_law": "US-NY",
  "method": "checkbox",
  "assurance_level": "L1",
  "failure_mode": "fail_closed",
  "baseline": "bl_7Yc3",
  "change_note": "Enabled Texas.",
  "created_at": "2026-12-02T10:14:09.551Z",
  "pending_conditions": [
    { "rule": "TX-04", "pack": "US-TX", "level": "block", "reason": "new_pack" }
  ],
  "versions": [
    { "version": 2, "created_at": "2026-12-02T10:14:09.551Z", "change_note": "Enabled Texas.", "baseline": "bl_7Yc3" },
    { "version": 1, "created_at": "2026-11-21T15:01:40.207Z", "change_note": null, "baseline": "bl_7Yc3" }
  ]
}

The example is shortened: the remaining profile fields are present as in the profile object.

Errors

not_found when the profile does not exist in this domain and environment.

Update a profile

POST /v1/profiles/{id} or PATCH /v1/profiles/{id}

Key: secret key with full_access.

Send only the fields you want to change. The API merges them with the latest version, validates the result as on create, and writes a new version. Sessions and records created earlier keep the version they pinned.

  • Adding a pack needs no code change to keep recording. The pack's obligations, recommendations and notices apply at once. Its record conditions start in advise and appear in pending_conditions until you adopt them.
  • Removing a pack never causes an error. A session whose signer is in that state, or that names the pack, proceeds under the remaining packs with the warning jurisdiction_not_enabled:<code>, unless strict_jurisdictions is true.
  • The baseline does not change on update. Only adoption and rollback change it.

Example request

curl -X PATCH https://esigncomply.com/v1/profiles/prof_signup_4f1a \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdictions": ["US-FED", "US-CA", "US-NY", "US-TX"],
    "change_note": "Enabled Texas."
  }'

Example response

200 OK. The body is the new version of the profile object, with "version": 2.

Errors

not_found, invalid_request, jurisdiction_unknown, insufficient_permission.

Signature methods and assurance levels

method Interface you build Notes
click Notice text with links directly beside a clearly labeled button Records assent or acknowledgment.
checkbox Unchecked checkbox with an explicit statement, then a button Default. Expected for consumer, purchase, trial and renewal ceremonies (CR-09).
typed Empty text field for the full legal name, plus a signing button Expected for nda and contract documents. The name is typed by the signer, never prefilled.
drawn Canvas that captures strokes Stroke data is stored only when drawn capture is switched on for the domain.
passkey Platform passkey prompt Needs assurance_level: "L3".
assurance_level What Esign Comply adds Plans
L1 Observes the act directly from the signer's device. Identity is asserted by you. All
L2 Verifies control of an email address or phone number with a one-time code or link inside the ceremony. See the L2 guide. All. The Free plan verifies by email: SMS codes need a paid plan.
L3 L2 plus a passkey assertion over a one-use challenge bound to the pre-signature payload. See the L3 guide. Unlimited and above

A verified channel or passkey does not establish legal identity, authority or sole control.