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
methodmust be one of the five values.passkeyneedsassurance_level: "L3".fail_open_deferredis accepted only withassurance_level: "L1"and withdocument_typeunset orterms.governing_lawmust 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_unavailablefromPOST /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_conditionsuntil 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>, unlessstrict_jurisdictionsistrue. - 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.
Related
- Jurisdictions: preview what a profile would apply with
POST /v1/jurisdictions/resolve. - Sessions: run a ceremony under a profile.
- Jurisdictions guide: choosing packs and modes.