Signature requests

A signature request is one PDF sent to 1 to 10 signers. MyCLM invites them by email, authenticates them (email or SMS code), collects the signatures through the chosen vendor and produces the signed PDF.

• GET/v1/signature-requestsList signature requests
• POST/v1/signature-requestsCreate a signature request
• GET/v1/signature-requests/optionsRetrieve the signature options of an entity
• GET/v1/signature-requests/{id}Retrieve a signature request
• POST/v1/signature-requests/{id}/cancelCancel a signature request
• POST/v1/signature-requests/{id}/remindRemind the pending signers
• GET/v1/signature-requests/{id}/documentDownload the document

Lifecycle

 sent ──► completed      every signer signed
   ├────► declined       a signer declined
   ├────► canceled       sender or manager canceled
   └────► expired        expiresAt reached

Each signer has its own status: pending → signed or declined.

Check the options of the entity

Signature settings are configured per entity (vendor, eIDAS level, signer authentication, expiry, reminders, retention, quota). Read them before building your UI:

curl -s "$MLT_API_URL/v1/signature-requests/options?entityId=$ENTITY_ID" -H "Authorization: Bearer $MLT_TOKEN"

Every option you omit at creation takes the entity default; a value the entity does not allow answers 422 (vendor_not_allowed, eidas_level_not_allowed, auth_method_not_allowed, expiry_too_long…).

Create a request

POST /v1/signature-requests is multipart/form-data with the PDF in file and the options in data (JSON string):

Field of data	Description
entityId	Entity of the request (required).
title	Shown to the signers (required, 200 characters max).
message	Optional message in the invitation email.
signers	1 to 10 signers, in signing order: firstName, lastName, email, optional phone (E.164, required for sms_otp) and contactId to link an address book contact.
expiresInDays	1 to 365, default and maximum set by the entity.
vendor	yousign, when enabled for the entity (the only vendor).
level	eIDAS level SES, AES or QES, if the vendor supports it.
authMethod	none, email_otp or sms_otp, at least as strong as the entity requires.
signingOrder	parallel or sequential, only when the entity lets the sender choose.

curl

curl -s -X POST "$MLT_API_URL/v1/signature-requests" \
  -H "Authorization: Bearer $MLT_TOKEN" \
  -F 'data={
    "entityId": "0192f3a1-7c2e-7b4d-9a61-200000000002",
    "title": "Bail - Lot 12",
    "message": "Bonjour, voici le bail du lot 12 à signer. Merci !",
    "signers": [
      { "firstName": "Marie", "lastName": "Durand", "email": "marie.durand@example.fr" },
      { "firstName": "Paul", "lastName": "Martin", "email": "paul.martin@example.fr", "phone": "+33612345678" }
    ],
    "authMethod": "email_otp",
    "signingOrder": "sequential",
    "expiresInDays": 30
  }' \
  -F 'file=@bail-lot-12.pdf;type=application/pdf'

Node.js

import { openAsBlob } from 'node:fs';

const form = new FormData();
form.append('data', JSON.stringify({
  entityId,
  title: 'Bail - Lot 12',
  message: 'Bonjour, voici le bail du lot 12 à signer. Merci !',
  signers: [
    { firstName: 'Marie', lastName: 'Durand', email: 'marie.durand@example.fr' },
    { firstName: 'Paul', lastName: 'Martin', email: 'paul.martin@example.fr', phone: '+33612345678' },
  ],
  authMethod: 'email_otp',
  signingOrder: 'sequential',
  expiresInDays: 30,
}));
form.append('file', await openAsBlob('bail-lot-12.pdf', { type: 'application/pdf' }), 'bail-lot-12.pdf');

const response = await fetch(`${process.env.MLT_API_URL}/v1/signature-requests`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const request = await response.json();

Python

import json

options = {
    "entityId": entity_id,
    "title": "Bail - Lot 12",
    "message": "Bonjour, voici le bail du lot 12 à signer. Merci !",
    "signers": [
        {"firstName": "Marie", "lastName": "Durand", "email": "marie.durand@example.fr"},
        {"firstName": "Paul", "lastName": "Martin", "email": "paul.martin@example.fr", "phone": "+33612345678"},
    ],
    "authMethod": "email_otp",
    "signingOrder": "sequential",
    "expiresInDays": 30,
}
with open("bail-lot-12.pdf", "rb") as pdf:
    request = requests.post(
        f"{api}/v1/signature-requests",
        headers=headers,
        data={"data": json.dumps(options)},
        files={"file": ("bail-lot-12.pdf", pdf, "application/pdf")},
    ).json()

PHP

$options = [
    'entityId' => $entityId,
    'title' => 'Bail - Lot 12',
    'message' => 'Bonjour, voici le bail du lot 12 à signer. Merci !',
    'signers' => [
        ['firstName' => 'Marie', 'lastName' => 'Durand', 'email' => 'marie.durand@example.fr'],
        ['firstName' => 'Paul', 'lastName' => 'Martin', 'email' => 'paul.martin@example.fr', 'phone' => '+33612345678'],
    ],
    'authMethod' => 'email_otp',
    'signingOrder' => 'sequential',
    'expiresInDays' => 30,
];
$request = json_decode((string) $http->post("$api/v1/signature-requests", [
    'headers' => $headers,
    'multipart' => [
        ['name' => 'data', 'contents' => json_encode($options)],
        ['name' => 'file', 'contents' => fopen('bail-lot-12.pdf', 'r'), 'filename' => 'bail-lot-12.pdf', 'headers' => ['Content-Type' => 'application/pdf']],
    ],
])->getBody(), true);

With sequential order, Marie is invited first and Paul once she signed (invitedAt stays null until then). With parallel, everyone is invited at once.

Follow the progress

Subscribe to the webhooks signature.signed (each signer), signature.completed (everyone signed) and signature.declined, then read the request with GET /v1/signature-requests/{id} if you need the details. Avoid polling; if you must, poll no more than every few minutes.

Automatic reminders follow the entity settings (reminders: every n days, at most m per signer). POST …/remind sends a reminder now to the signers who were invited and have not signed.

Download the documents

• GET …/document (or ?variant=original): the uploaded PDF.
• GET …/document?variant=signed: the signed PDF, once the request is completed (document.signedAvailable). Before that: 409 signature_request_not_completed.

Cancel

POST …/cancel stops a sent request: pending signers can no longer sign. Allowed to the sender and to signature.manage.

Retention

When a request is finished, its files are kept for the retention period of the entity (retention.years), then archived or deleted (retention.action). The request, its signers and the proof of signature remain readable; downloads then answer 409 document_purged or document_archived.