Modèles

Listez vos modèles de signature électronique et lisez les rôles d'un modèle précis — le point de départ pour envoyer une enveloppe depuis l'API.

Les modèles sont les documents réutilisables que votre équipe a déjà configurés dans l'app, avec leurs champs et leurs rôles de signataire disposés. Pour envoyer une enveloppe via l'API, vous partez de l'un d'eux ; les deux endpoints de lecture ci-dessous sont donc généralement les premiers appels après l'authentification.

Les deux requièrent le scope templates:read, et une clé ne voit que les modèles que son propriétaire peut voir dans l'app.

Lister les modèles

Endpoint

GET https://api2.bunnydoc.com/v1/templates

Paramètres de requête

Paramètre	Type	Description
`page`	integer	Numéro de page, à partir de `1`. Par défaut `1`.
`per_page`	integer	Résultats par page, `1`–`100`. Par défaut `25`.
`search`	string	Facultatif. Filtre par nom de modèle, jusqu'à 200 caractères.

Exemple de requête

Lister les modèles

curl "https://api2.bunnydoc.com/v1/templates?per_page=25&search=nda" \
  -H "Authorization: Bearer <access_token>"

Lister les modèles

GET /v1/templates?per_page=25&search=nda HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>

Réponse

200 OK

{
  "data": [
    {
      "id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Mutual NDA",
      "description": "Standard two-way non-disclosure agreement",
      "file_count": 1,
      "role_count": 2,
      "created_at": "2026-06-01T09:30:00.000Z",
      "updated_at": "2026-07-10T14:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Champ	Type	Description
`id`	string	L'id du modèle — passez-le à `POST /v1/envelopes/from-template`.
`name`	string	Nom du modèle.
`description`	string \| null	Description facultative.
`file_count`	integer	Nombre de documents dans le modèle.
`role_count`	integer	Nombre de rôles de signataire.
`created_at` / `updated_at`	string	Horodatages ISO 8601.

Obtenir un modèle

Renvoie un modèle avec ses rôles. Appelez cet endpoint avant d'envoyer : le tableau roles vous indique exactement quels noms de rôle fournir, et lesquels sont verrouillés.

Endpoint

GET https://api2.bunnydoc.com/v1/templates/{id}

Exemple de requête

Obtenir un modèle

curl https://api2.bunnydoc.com/v1/templates/018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer <access_token>"

Obtenir un modèle

GET /v1/templates/018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>

Réponse

200 OK

{
  "id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Mutual NDA",
  "description": "Standard two-way non-disclosure agreement",
  "file_count": 1,
  "role_count": 2,
  "created_at": "2026-06-01T09:30:00.000Z",
  "updated_at": "2026-07-10T14:12:00.000Z",
  "roles": [
    {
      "role": "Client",
      "recipient_type": "need-to-sign",
      "signing_order": 1,
      "locked": false
    },
    {
      "role": "Account manager",
      "recipient_type": "need-to-sign",
      "signing_order": 2,
      "locked": true,
      "name": "Dana Lee",
      "email": "dana@yourco.com"
    }
  ],
  "fields": [
    {
      "id": "018f2c3d-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
      "role": "Client",
      "file_id": "018f2c3d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "page_number": 1,
      "type": "signature",
      "label": "Client signature",
      "required": true,
      "locked": false,
      "position": { "x": 72, "y": 540, "width": 180, "height": 48 }
    }
  ],
  "files": [
    { "file_id": "018f2c3d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "order": 1, "excluded_pages": [] }
  ],
  "settings": {
    "signing_order": true,
    "email_subject": "Please sign: Mutual NDA",
    "email_message": "<p>Please review and sign the enclosed NDA.</p>",
    "expiry_date": "2026-12-31T23:59:59.000Z",
    "timezone": "Australia/Sydney",
    "signed_date_format": "DD/MM/YYYY",
    "envelope_date_time_format": "DD/MM/YYYY HH:mm",
    "brand_id": "018f2c3d-9c0d-7e1f-8a2b-3c4d5e6f7a8b"
  }
}

`roles`

Champ de rôle	Type	Description
`role`	string	Le nom du rôle. Fournissez-le dans `recipients[].role` lors de l'envoi.
`recipient_type`	string	Comment le destinataire participe, p. ex. `need-to-sign`, `receives-a-copy`.
`signing_order`	integer	L'ordre dans lequel ce rôle signe.
`locked`	boolean	Si `true`, le nom et l'e-mail sont figés sur le modèle — omettez ce rôle dans votre requête d'envoi.
`name` / `email`	string \| null	Présents uniquement pour les rôles verrouillés — le destinataire figé.

Les rôles verrouillés ne peuvent pas être réattribués

Un rôle verrouillé a déjà une personne attachée (ou c'est l'expéditeur propre du modèle). Envoyer un destinataire pour un rôle verrouillé est rejeté avec unknown_signer_role. Ne fournissez des destinataires que pour les rôles dont locked vaut false.

`fields`

Tous les champs placés sur le modèle, pour que vous puissiez montrer à vos utilisateurs ce que le document demandera avant de l'envoyer.

Champ	Type	Description
`id`	string \| null	L'identifiant du champ.
`role`	string	Le rôle de signataire auquel le champ appartient — à joindre à `roles[].role`.
`file_id`	string	Sur lequel des `files` du modèle le champ se trouve.
`page_number`	integer	Page (à partir de 1) dans ce fichier.
`type`	string	Type de champ — `signature`, `initials`, `text`, `date`, `date_signed`, `checkbox`, `radio`, `dropdown`, `multi_select`, `email`, `phone`, `number`, `amount`, `address`, `company`, `job_title`, `title`, `full_name`, `first_name`, `last_name`, `masked_text`, `image` ou `file_attachment`.
`label`	string \| null	Le libellé du champ.
`required`	boolean	Si un signataire doit le remplir.
`locked`	boolean	Si la valeur est figée sur le modèle.
`position`	object	`x`, `y`, `width`, `height` sur la page.

Les valeurs préparées ne sont pas exposées

La géométrie des champs est lisible ; les valeurs préparées par l'expéditeur ne le sont pas. Une valeur côté expéditeur peut être une référence de signature ou du texte sensible prérempli : elle ne quitte donc jamais l'application via cette API.

`files`

Métadonnées uniquement, dans l'ordre du document.

Champ	Type	Description
`file_id`	string	L'identifiant du fichier. Servez-vous-en pour joindre `fields[].file_id`.
`order`	integer	Position dans l'ensemble de documents.
`excluded_pages`	integer[]	Pages retirées du modèle, s'il y en a.

Les fichiers de modèle ne sont pas téléchargeables

Il n'y a ici aucune URL de téléchargement ni chemin de stockage, et aucun endpoint pour récupérer le document d'un modèle. Cela vous indique quels fichiers sont attachés et dans quel ordre, rien de plus. Le PDF final signé est livré via le webhook envelope.document_ready.

`settings`

Ce que l'enveloppe héritera lorsque vous enverrez depuis ce modèle. Le lire est le moyen fiable de savoir ce que vous n'avez pas besoin de transmettre.

Champ	Type	Description
`signing_order`	boolean	Si les destinataires signent séquentiellement.
`email_subject`	string \| null	Objet par défaut. Remplaçable à chaque envoi via `email_subject`.
`email_message`	string \| null	Message par défaut, en HTML sûr. Remplaçable à chaque envoi via `email_message`.
`expiry_date`	string \| null	ISO 8601. Hérité par l'enveloppe ; non paramétrable depuis l'API.
`timezone`	string	Fuseau IANA utilisé pour les dates du document et des e-mails.
`signed_date_format`	string	Format des dates de signature dans le PDF.
`envelope_date_time_format`	string	Format des dates et heures.
`brand_id`	string \| null	La marque appliquée aux e-mails et à la page de signature.

Erreurs

Statut	`error.code`	Quand cela se produit
`404`	`template_not_found`	Aucun modèle avec cet id n'existe dans votre entreprise.

Étape suivante

Envoyer depuis un modèle

Affectez des destinataires aux rôles déverrouillés et envoyez l'enveloppe.

Envoyer depuis un modèle

Sur cette page