# The EspoCRM app

Send documents for signature from EspoCRM records with the dVellum app, and get the signed PDF back on the record.

The **dVellum for EspoCRM** app adds **Send for Signature** to the records you choose. The signed, sealed PDF comes
back to EspoCRM by itself, attached to a Document linked to the record.

> [!NOTE]
> dVellum was called S+M eSign until October 2026. Versions of the app before 2.6.0 still show that name (for
> example **Administration → S+M eSign** and *eSign URL*); install 2.6.0 over them to see the labels on this page.
> Under **Administration → Extensions** the app keeps its internal name, *S+M eSign*, so new versions replace it.

It works with EspoCRM 9 and 10 (PHP 8.1 or newer). It is free, but needs a dVellum workspace (see
[Getting started](https://docs.sapiensandmachines.com/en/dvellum/getting-started)). The app's screens are in English.

## Install

:::steps
1. In EspoCRM, open **Administration → Extensions**, upload the app's zip file and choose **Install**.
2. Check **Administration → Settings → Site URL**: it must be your CRM's public `https://` address, because dVellum
   sends its updates there.
3. Fill in **Administration → dVellum** (below).
4. On each PDF template you send for signature, tick **Use for signature**.
5. Optional: with the Layout Manager, add the dVellum fields to the Document layouts.
:::

To upgrade, install the new zip over the old one.

## Administration → dVellum

**Connection**

| Setting | What to enter |
|---|---|
| **Enabled** | Tick to turn the app on. |
| **dVellum URL** | Your dVellum address: `https://app.dvellum.com` (CRMs set up with `https://dvellum.sapiensandmachines.com` keep working). |
| **Notification URL (set automatically)** | Where dVellum sends updates; nothing to change. |
| **API key** | A key for your workspace, created in dVellum under **Settings → API keys**. |
| **Webhook secret** | The **Signing secret** shown in dVellum under **Settings → Webhooks**. |

Choose **Save & test connection**: you should see *Connected to dVellum.*

**Send for Signature**

Switch on the record types that can be sent for signature, and for each choose **Who signs**: *The record itself*
(for example a Contact) or *A contact of the record* (for example an Account's contact). Record types start off after
installing or upgrading.

> [!IMPORTANT]
> Switching on a record type that doesn't have Documents yet adds a Documents panel to it. On EspoCRM 9, only
> Accounts, Contacts, Leads and Opportunities can be switched on; on EspoCRM 10, any record type that can have
> Documents.

## PDF template settings

Each PDF template has a **Signature** panel:

- **Use for signature**: offer this template in Send for Signature. Templates without it are for Print to PDF only.
  Only active templates are offered.
- **On signature, set date field**: when a document from this template is fully signed, write the signing date into
  this field of the record it was sent from (for example *Agreement signed on*). Leave empty to change nothing.
- **Requires signed**: block sending this template until a document from another template is fully signed for this
  record or the record it belongs to (for example an agreement before a quote), or that template's date field is
  already filled in.

Mark where the client signs with [markers](https://docs.sapiensandmachines.com/en/dvellum/templates-and-markers).

### Values for templates

Besides the record's own fields, templates can use:

- `{{esign.sender.name}}` and the other `esign.sender` fields: the user who clicks Send.
- `{{esign.signer.name}}` and the other `esign.signer` fields: the person who signs.
- `{{dateFormat esign.today format='MMMM D, YYYY'}}`: today's date.

## Send for signature

:::steps
1. On the record, open the **⋯** menu and choose **Send for Signature**.
2. Choose the **Document template** and the **Signer**.
3. Choose the **Language** of the signing page and emails: *Company default*, *English* or *Español*.
4. Optional: write a **Message to the signer**.
5. Choose **Send**.
:::

dVellum emails the signer a personal link. A Document named *Template — Record* is created, linked to the record, and a
note is posted in the record's stream.

![The Send for Signature window on a contact](https://docs.sapiensandmachines.com/docs-media/3d56e06b1da43708ec5f.png)

To cancel a request, open the Document, then **⋯ → Void Signature Request**.

> [!NOTE]
> Documents sent from EspoCRM have one signer. To have several people sign, use the [API](https://docs.sapiensandmachines.com/en/dvellum/api-and-webhooks).

## What comes back to EspoCRM

The Document's **Signature Status** follows the request:

| When | Signature Status | Also |
|---|---|---|
| The signer opens it | Viewed | A note in the stream. |
| Everyone has signed | Completed | The sealed PDF is attached as *… - signed.pdf* and checked against its fingerprint; the template's date field is set on the record it was sent from. |
| The signer declines | Declined | The note includes their reason. |
| The link expires | Expired | |
| You void it | Voided | |

![A contact's stream with notes for the document sent, opened and signed](https://docs.sapiensandmachines.com/docs-media/1a583d41028454274fd4.png)

Other Document fields: **Signer**, **Sent for Signature**, **Viewed by Signer**, **Signed (Completed)**, **dVellum
Envelope ID**, **Signed PDF Fingerprint** (the sealed PDF's SHA-256), **Sent From** and **Template**.