# Profiles

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

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

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](https://esigncomply.com/docs/api/guidance.md).

## The profile object

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/guides/consumer-econsent.md). |
| `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`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) from `POST /v1/sessions`.

**Example request**

```bash
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`](https://esigncomply.com/docs/api/errors.md#invalid_request) with `param` naming the field, [`jurisdiction_unknown`](https://esigncomply.com/docs/api/errors.md#jurisdiction_unknown), [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/api/guidance.md) and the [compatibility contract](https://esigncomply.com/docs/concepts/compatibility.md).

## 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**

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

**Example response**

`200 OK`

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

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

**Example response**

`200 OK`

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

```bash
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`](https://esigncomply.com/docs/api/errors.md#not_found), [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request), [`jurisdiction_unknown`](https://esigncomply.com/docs/api/errors.md#jurisdiction_unknown), [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/conformance.md#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](https://esigncomply.com/docs/guides/l2-verification.md). | 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](https://esigncomply.com/docs/guides/l3-passkeys.md). | Unlimited and above |

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

## Related

- [Jurisdictions](https://esigncomply.com/docs/api/jurisdictions.md): preview what a profile would apply with `POST /v1/jurisdictions/resolve`.
- [Sessions](https://esigncomply.com/docs/api/sessions.md): run a ceremony under a profile.
- [Jurisdictions guide](https://esigncomply.com/docs/guides/jurisdictions.md): choosing packs and modes.
