Signature Requests

POST `/api/v1/signature_requests`

Crée une signature request à partir de documents préalablement uploadés via POST /api/v1/documents.

Tous les champs sont wrappés sous une clé racine signature_request :

{ "signature_request": { /* champs ci-dessous */ } }

Body — champs racine

Champ	Type	Requis	Description
`mode`	string	✓	`"sequential"` ou `"parallel"`.
`validity_days`	int	✓	1 à 90.
`send_email`	bool		Défaut `false`. Si `true`, Signlift notifie le premier signataire (mode sequential) ou tous (mode parallel).
`identity_declaration_accepted`	bool	✓ si `send_email: true`	Atteste que vous avez collecté l'identité des signataires hors-Signlift (exigence eIDAS pour la signature simple). Sans ce flag avec `send_email: true`, l'API répond `422 validation_error`.
`initials_required`	bool		Paraphes par page. Plans Pro et Enterprise uniquement. Sinon `403 initials_not_available_on_plan`.
`notify_signers_on_completion`	bool		Défaut `false`. E-mail récapitulatif envoyé aux signataires à la complétion.
`branding_profile_id`	int		Applique une charte graphique personnalisée au parcours du signataire. Doit correspondre à un profil créé depuis votre organisation (dashboard → Charte). Plans Pro et Enterprise uniquement. Omis ou `null` → palette Signlift par défaut. Un id qui n'appartient pas à votre organisation est rejeté en `422 validation_error`.
`signers`	array	✓	Liste des signataires (cf. schéma ci-dessous).
`documents`	array	✓	Liste des documents à signer avec leurs placements de signature.

Les limites sur le nombre de signataires et de documents dépendent du plan : voir Limites et rate-limits.

Schéma d'un signer (entrée)

{
  "ref": "jeanne",
  "first_name": "Jeanne",
  "last_name": "Dupont",
  "email": "jeanne@example.com",
  "phone": "+33612345678",
  "order": 1,
  "otp_channel": "email"
}

ref : identifiant arbitraire choisi par votre code, utilisé pour lier le signataire à ses placements dans documents[].signers[].signer_ref. Non persisté.
phone : format E.164 (+CCXXXXXXXXX). Requis si otp_channel est sms.
order : ordre de signature en mode sequential (ignoré en parallel).
otp_channel : email ou sms. sms réservé aux plans Pro et Enterprise.

Les organisations sur les plans Pro et Enterprise peuvent personnaliser les couleurs du parcours de signature (fond, texte, accentuation). Les profils sont créés et gérés depuis le dashboard, dans Charte au niveau de l'organisation — il n'y a pas d'endpoint API pour le CRUD des profils. Limite : 2 profils sur Pro, 10 sur Enterprise.

Pour appliquer un profil à une demande, transmettez son identifiant dans branding_profile_id :

curl https://app.signlift.eu/api/v1/signature_requests \
  -H "X-Api-Key: $SIGNLIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signature_request": {
      "mode": "parallel",
      "validity_days": 30,
      "branding_profile_id": 7,
      "signers": [ /* … */ ],
      "documents": [ /* … */ ]
    }
  }'

Si l'identifiant n'appartient pas à votre organisation, l'API répond 422 validation_error. Les demandes créées sans branding_profile_id conservent l'apparence générique Signlift.

L'objet branding_profile est renvoyé dans la réponse de tous les endpoints qui retournent une signature_request (cf. ci-dessous), ou null quand la demande utilise la palette par défaut.

Exemple minimal

curl https://app.signlift.eu/api/v1/signature_requests \
  -H "X-Api-Key: $SIGNLIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signature_request": {
      "mode": "sequential",
      "validity_days": 30,
      "send_email": true,
      "identity_declaration_accepted": true,
      "signers": [
        {
          "ref": "jeanne",
          "first_name": "Jeanne",
          "last_name": "Dupont",
          "email": "jeanne@example.com",
          "order": 1
        }
      ],
      "documents": [
        {
          "id": 42,
          "signers": [
            {
              "signer_ref": "jeanne",
              "stamp": { "type": "magic_field", "value": { "tag": "[SIG_JEANNE]" } }
            }
          ]
        }
      ]
    }
  }'

Pour un payload complet (mode parallel, placements par coordonnées, paraphes), utilisez le playground interactif.

Réponse 201

{
  "id": 42,
  "mode": "sequential",
  "status": "pending",
  "validity_days": 30,
  "initials_required": false,
  "notify_signers_on_completion": false,
  "expires_at": "2026-06-16T15:00:00Z",
  "created_at": "2026-05-17T15:00:00Z",
  "document_ids": [42],
  "signers": [
    {
      "id": 1768,
      "first_name": "Jeanne",
      "last_name": "Dupont",
      "full_name": "Jeanne Dupont",
      "email": "jeanne@example.com",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "signing_url": "https://app.signlift.eu/sign/eyJhbGciOiJIUzI1NiJ9..."
    }
  ],
  "branding_profile": {
    "id": 7,
    "name": "Marque Acme",
    "background_color": "#f5f0e6",
    "text_color": "#173039",
    "accent_color": "#202c90"
  }
}

branding_profile vaut null quand la demande utilise la palette par défaut.

Le statut du signer est pending à la réponse synchrone — il passe à notified une fois l'e-mail envoyé (job asynchrone).

Le champ signing_url est l'URL absolue à transmettre au signataire — voir Authentification et Intégration iframe.

Le champ download_urls n'est pas présent à la création — il apparaît uniquement sur le GET ci-dessous, et uniquement lorsque la signature request est completed.

GET `/api/v1/signature_requests/{id}`

Récupère l'état actuel d'une signature request.

Statuts possibles

Status	Signification
`pending`	Au moins un signataire n'a pas encore signé.
`completed`	Tous les signataires ont signé. Documents signés et certificat disponibles.
`expired`	`validity_days` dépassé sans complétion.

Les signataires individuels ont leur propre cycle de statut (pending → notified → signed), exposé dans signers[].status.

Réponse 200 — signature complétée

{
  "id": 42,
  "mode": "sequential",
  "status": "completed",
  "validity_days": 30,
  "initials_required": false,
  "notify_signers_on_completion": false,
  "expires_at": "2026-06-16T15:00:00Z",
  "created_at": "2026-05-17T15:00:00Z",
  "document_ids": [42],
  "signers": [
    {
      "id": 1768,
      "first_name": "Jeanne",
      "last_name": "Dupont",
      "full_name": "Jeanne Dupont",
      "email": "jeanne@example.com",
      "order": 1,
      "status": "signed",
      "signed_at": "2026-05-17T15:12:43Z",
      "signing_url": null
    }
  ],
  "branding_profile": null,
  "download_urls": [
    {
      "document_id": 42,
      "signed_url": "https://s3.eu-west-1.amazonaws.com/...?X-Amz-Signature=...",
      "certificate_url": "https://s3.eu-west-1.amazonaws.com/...?X-Amz-Signature=...",
      "expires_in": 900
    }
  ]
}

Les URLs signed_url et certificate_url sont des URLs S3 présignées valides pendant expires_in secondes (900 = 15 minutes). Pour les récupérer à nouveau, rappelez ce même endpoint.