The Electronic Signature Check Object

An electronic_signature check collects a legally binding signature from one individual on one
document. The document is generated from a document template held in the workspace and populated
with the case's data; it is not uploaded with the request.

The check targets individuals only. One check corresponds to one signer and one template.

Product documentation: Electronic signature.

Create an electronic signature check

POST /v1/checks/electronic_signature — the path segment uses an underscore. See
Create an electronic signature check.

curl -X POST https://api.dotfile.com/v1/checks/electronic_signature \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "individual_id": "01234567-89ab-cdef-0123-456789abcdef",
    "settings": {
      "document_template_key": "power_of_attorney"
    }
  }'

Field	Type	Required	Description
`individual_id`	`uuid`	yes	the signer
`settings.document_template_key`	string	yes	key of the document template to send
`settings.automatic_approval`	boolean	no, default `true`	approves the check when the signature completes

settings.document_template_key is mandatory, unlike the optional settings object on every other
check type. The referenced template must exist in the workspace, be of the electronic-signature
kind, and have a published version; a draft-only template returns 400. 400 is also returned
when the workspace check limit is reached.

Signature requests are initiated from the client portal

Creation returns a check in status in_progress with data.vendor.signature_link set to null.
No signature request has been sent at this point.

The signature request — rendering the document, registering the signer and producing the signature
link — is initiated when the signer reaches the client portal. No API endpoint triggers it, and no
API endpoint refreshes an expired signature_link.

The corresponding sequence is to create the check, then issue a portal link with
Share a client portal link:

curl -X POST https://api.dotfile.com/v1/cases/$CASE_ID/share-client-portal-link \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_contact_id": "'$INDIVIDUAL_ID'"}'

The individual must have an email address and be marked is_business_contact. See
Client portal.

Response

Field	Description
`data.result`	`approved`, `rejected` or `error`
`data.vendor.name`	the signature provider, `yousign`
`data.vendor.status`	the provider's own status string
`data.vendor.signature_request_ref`	provider identifier for the request
`data.vendor.signer_ref`	provider identifier for the signer
`data.vendor.document_ref`	provider identifier for the document
`data.vendor.signature_link`	URL the signer opens; `null` until the request is active
`data.vendor.signature_link_expiration_date`	expiry of that URL
`data.vendor.started_at`, `data.vendor.ended_at`	request open and close timestamps
`data.information.file_id`	the document that was sent
`data.information.signed_file_id`	the signed document
`data.information.audit_trail_id`	the provider's audit trail
`data.settings`	`document_template_key`, `automatic_approval`
`data.review`	`comment`, `reviewed_at`, `reviewer_type`, `user`

data.information is populated once the signature completes. Its three fields are file
identifiers, not files; each is retrieved with Download a file:

curl https://api.dotfile.com/v1/files/$SIGNED_FILE_ID \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY"

See Files for the response format.

Subtype

subtype is never null on an electronic_signature check. It holds
document_template:{document_template_key}, echoing the key passed at creation, and distinguishes
two signature checks on the same individual from the envelope alone. document is the only other
check type that populates subtype.

Review

PATCH /v1/checks/electronic_signature/{id}/review —
Review an electronic signature check.

curl -X PATCH https://api.dotfile.com/v1/checks/electronic_signature/$CHECK_ID/review \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "comment": "Signature and audit trail verified"}'

Field	Type	Required	Description
`action`	`approve` \| `reject`	yes	the decision
`comment`	string	no	recorded on `data.review`
`override`	boolean	no	permits changing a check already in `approved` or `rejected`

data.review.reviewer_type is set to api.

Retrieval

Retrieve an electronic signature check returns the full object,
data included.

Retrieve a case and List checks return the check envelope
only, without data — so without signature_link and without the file identifiers.

The Check.Started, Check.Approved, Check.Rejected and Check.ReviewNeeded
webhook events carry the complete check object, data.information included.

The Check object — the shared envelope, statuses and review mechanics
Files — retrieving the signed document and the audit trail
Templates — creating the check from a verification policy rather than per call