TTeamSignAPI v1
API docs by Redocly

TeamSign API (1.0)

TeamSign: contact@teamsign.fr URL: https://teamsign.fr/solution-api.html Terms of Service

L'API TeamSign permet d'envoyer des documents à signer, de suivre leur statut, de récupérer l'exemplaire signé et son certificat de preuve, et d'être notifié par webhook — sans passer par l'interface TeamSign.

Environnements

Mode Préfixe de clé Comportement
Sandbox ts_test_… Gratuit, illimité, disponible immédiatement. Les documents apparaissent dans votre espace TeamSign préfixés « [SANDBOX] ». Les emails ne partent que vers les adresses de votre entreprise (même domaine que le porteur de la clé ou membre du compte) ; pour les autres, utilisez le signing_url renvoyé. Aucun SMS. Aucune valeur juridique.
Live ts_live_… Activation en self-service depuis Paramètres → Développeurs : coordonnées de facturation, puis mandat SEPA (à l'acte, 1,50 € HT par demande envoyée, 10 premières offertes) ou pack prépayé par carte (activation immédiate). Preuve eIDAS (SES) horodatée. Tant que le mode live n'est pas activé, un POST renvoie 402 et la demande reste en brouillon, envoyable ensuite via /send.

Les deux modes partagent la même URL de base ; c'est la clé qui détermine l'environnement.

Authentification

Toutes les requêtes portent l'en-tête Authorization: Bearer <clé>. Les clés se créent dans Réglages → Développeurs de votre espace TeamSign. Une clé est liée à une entreprise (et à son périmètre d'entités si vous êtes multi-entités).

Unité de facturation

1 demande de signature envoyée = 1 unité, quel que soit le nombre de documents (jusqu'à 10 PDF par dossier) et de signataires (jusqu'à 10). Les demandes annulées après envoi, expirées ou refusées sont facturées (l'envoi a eu lieu). Un brouillon (send: false) n'est jamais facturé. OTP par SMS : 0,15 € HT par SMS envoyé.

Ordre de signature

TeamSign fait signer séquentiellement : le signataire de rang 1 reçoit le lien, le suivant est invité automatiquement dès qu'il a signé. order trie les signataires ; à ordre égal, l'ordre de la liste s'applique.

Pages et coordonnées des champs

Coordonnées en points PDF (1/72 pouce), origine en haut à gauche, sauf unit: "ratio" (valeurs 0-1). page: -1 = dernière page du document (hors annexes ajoutées par TeamSign), page: "all" = toutes les pages du document ; une page positive est absolue dans le PDF final (document + annexes). Sans champ signature pour un signataire, TeamSign place sa signature en bas de la dernière page du premier document.

Limites

  • 60 requêtes / minute par clé (en-têtes X-RateLimit-Limit, X-RateLimit-Remaining).
  • 10 documents et 25 Mo par demande. PDF uniquement (non chiffrés).
  • Les réponses 429 incluent Retry-After.
  • Webhooks : 10 par compte ; les événements sont détectés chaque minute (latence ≤ 60 s).

Idempotence

Envoyez un en-tête Idempotency-Key (UUID) sur les POST : une requête rejouée avec la même clé dans les 24 h renvoie la réponse d'origine sans créer de doublon.

Erreurs

Toutes les erreurs suivent le même format JSON (type, title, status, detail, errors[]).

Compte

Informations sur la clé, le mode et la consommation.

Vérifier la clé et lire la consommation

Authorizations:
bearerAuth

Responses

Response Schema: application/json
object
mode
string
Enum: "sandbox" "live"
object
object
object

null en paiement à l'acte (facturation mensuelle).

Response samples

Content type
application/json
{
  • "company": {
    },
  • "mode": "live",
  • "key": {
    },
  • "usage": {
    },
  • "credits": {
    }
}

Demandes de signature

Créer, envoyer, suivre, relancer, annuler.

Lister les demandes

Authorizations:
bearerAuth
query Parameters
status
string (RequestStatus)
Enum: "draft" "sent" "in_progress" "completed" "refused" "expired" "cancelled"
  • draft — créée, non envoyée
  • sent — envoyée, aucun signataire n'a encore signé
  • in_progress — au moins un signataire a signé, d'autres attendent
  • completed — tous ont signé ; exemplaire signé et certificat disponibles
  • refused / expired / cancelled — terminée sans signature complète
created_after
string <date-time>
external_id
string

Votre identifiant métier (numéro de devis, id CRM…).

page
integer >= 1
Default: 1
per_page
integer [ 1 .. 100 ]
Default: 25

Responses

Response Schema: application/json
Array of objects (SignatureRequest)
object (Pagination)

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Créer et envoyer une demande de signature

Crée un dossier (1 à 10 PDF), y place les signataires et leurs champs, puis l'envoie immédiatement — sauf send: false, auquel cas la demande reste en brouillon et s'envoie via POST /signature-requests/{id}/send.

Les documents s'envoient soit en base64 (content), soit par URL publique (url, téléchargée une seule fois), soit en multipart (multipart/form-data, champ documents[] + champ payload contenant le JSON).

Si aucun fields n'est fourni pour un signataire, TeamSign ajoute automatiquement un champ signature en bas de la dernière page du premier document (comportement « signature simple »). Un template_id (modèle variable) applique ses champs, annexes et réglages par défaut ; un modèle fixe fournit lui-même le PDF (documents[].template_id).

Réponse 402 (mode live non activé ou crédits épuisés) : la demande est conservée en brouillon (request_id dans l'erreur) et pourra être envoyée avec POST /signature-requests/{id}/send.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
string <uuid>
Request Body schema:
required
required
Array of objects (DocumentInput) [ 1 .. 10 ] items
required
Array of objects (SignerInput) [ 1 .. 10 ] items
title
string <= 200 characters

Affiché au signataire et dans TeamSign. Défaut = nom du premier document.

external_id
string <= 100 characters

Votre identifiant métier, retrouvable ensuite via ext:.

Array of objects (FieldInput)
template_id
string

Modèle variable (tpl_…, cf. GET /templates) — applique ses champs, annexes et réglages par défaut ; vos signers remplissent les rôles dans l'ordre.

attachments
Array of strings

Identifiants d'annexes (att_…, ex. CGV) ajoutées en dernière page du premier document. Nécessite la bibliothèque PDF serveur (sinon 422).

message
string <= 2000 characters

Texte de l'email. Variables : {{prénom}}, {{nom}}, {{société}}, {{document}}.

object

Membre TeamSign au nom duquel la demande est envoyée (défaut = propriétaire de la clé).

expires_in_days
integer [ 1 .. 90 ]
Default: 30
object
send
boolean
Default: true
object <= 20 properties

Vos données libres, renvoyées telles quelles dans les webhooks.

Responses

Response Schema: application/json
id
string
object
string
Value: "signature_request"
mode
string
Enum: "sandbox" "live"
status
string (RequestStatus)
Enum: "draft" "sent" "in_progress" "completed" "refused" "expired" "cancelled"
  • draft — créée, non envoyée
  • sent — envoyée, aucun signataire n'a encore signé
  • in_progress — au moins un signataire a signé, d'autres attendent
  • completed — tous ont signé ; exemplaire signé et certificat disponibles
  • refused / expired / cancelled — terminée sans signature complète
title
string
external_id
string
created_at
string <date-time>
sent_at
string <date-time>
completed_at
string <date-time>
expires_at
string <date-time>
Array of objects (Document)
Array of objects (Signer)
object

Renseigné quand completed.

object
object

Request samples

Content type
Example
{
  • "title": "Devis n° D-2026-4582",
  • "external_id": "D-2026-4582",
  • "documents": [
    ],
  • "signers": [
    ],
  • "message": "Bonjour {{prénom}}, merci de signer votre devis {{document}}.",
  • "expires_in_days": 15,
  • "reminders": {
    },
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "sr_01J9K3…",
  • "object": "signature_request",
  • "mode": "sandbox",
  • "status": "draft",
  • "title": "string",
  • "external_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "documents": [],
  • "signers": [
    ],
  • "proof": {},
  • "metadata": {
    },
  • "billing": {
    }
}

Lire une demande et son statut

Authorizations:
bearerAuth
path Parameters
id
required
string

Identifiant TeamSign (sr_…) ou votre external_id préfixé ext: (ex. ext:D-2026-4582).

Responses

Response Schema: application/json
id
string
object
string
Value: "signature_request"
mode
string
Enum: "sandbox" "live"
status
string (RequestStatus)
Enum: "draft" "sent" "in_progress" "completed" "refused" "expired" "cancelled"
  • draft — créée, non envoyée
  • sent — envoyée, aucun signataire n'a encore signé
  • in_progress — au moins un signataire a signé, d'autres attendent
  • completed — tous ont signé ; exemplaire signé et certificat disponibles
  • refused / expired / cancelled — terminée sans signature complète
title
string
external_id
string
created_at
string <date-time>
sent_at
string <date-time>
completed_at
string <date-time>
expires_at
string <date-time>
Array of objects (Document)
Array of objects (Signer)
object

Renseigné quand completed.

object
object

Response samples

Content type
application/json
{
  • "id": "sr_01J9K3…",
  • "object": "signature_request",
  • "mode": "sandbox",
  • "status": "draft",
  • "title": "string",
  • "external_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "documents": [],
  • "signers": [
    ],
  • "proof": {},
  • "metadata": {
    },
  • "billing": {
    }
}

Supprimer un brouillon

Uniquement pour une demande en statut draft. Une demande envoyée s'annule (/cancel).

Authorizations:
bearerAuth
path Parameters
id
required
string

Identifiant TeamSign (sr_…) ou votre external_id préfixé ext: (ex. ext:D-2026-4582).

Responses

Envoyer un brouillon

Authorizations:
bearerAuth
path Parameters
id
required
string

Identifiant TeamSign (sr_…) ou votre external_id préfixé ext: (ex. ext:D-2026-4582).

header Parameters
Idempotency-Key
string <uuid>

Responses

Response Schema: application/json
id
string
object
string
Value: "signature_request"
mode
string
Enum: "sandbox" "live"
status
string (RequestStatus)
Enum: "draft" "sent" "in_progress" "completed" "refused" "expired" "cancelled"
  • draft — créée, non envoyée
  • sent — envoyée, aucun signataire n'a encore signé
  • in_progress — au moins un signataire a signé, d'autres attendent
  • completed — tous ont signé ; exemplaire signé et certificat disponibles
  • refused / expired / cancelled — terminée sans signature complète
title
string
external_id
string
created_at
string <date-time>
sent_at
string <date-time>
completed_at
string <date-time>
expires_at
string <date-time>
Array of objects (Document)
Array of objects (Signer)
object

Renseigné quand completed.

object
object

Response samples

Content type
application/json
{
  • "id": "sr_01J9K3…",
  • "object": "signature_request",
  • "mode": "sandbox",
  • "status": "draft",
  • "title": "string",
  • "external_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "documents": [],
  • "signers": [
    ],
  • "proof": {},
  • "metadata": {
    },
  • "billing": {
    }
}

Relancer les signataires en attente

Renvoie l'email au signataire dont c'est le tour et prolonge l'expiration de 7 jours si elle est à moins de 48 h (ou dépassée). Limité à 1 relance / 24 h / signataire.

Authorizations:
bearerAuth
path Parameters
id
required
string

Identifiant TeamSign (sr_…) ou votre external_id préfixé ext: (ex. ext:D-2026-4582).

Responses

Response Schema: application/json
reminded
Array of strings <email> [ items <email > ]
mail_sent
boolean
signing_url
string <uri>
expires_at
string <date-time>

Response samples

Content type
application/json
{
  • "reminded": [
    ],
  • "mail_sent": true,
  • "signing_url": "http://example.com",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Annuler une demande en cours

Invalide tous les liens de signature du dossier. Les signataires déjà passés sont informés. Irréversible.

Authorizations:
bearerAuth
path Parameters
id
required
string

Identifiant TeamSign (sr_…) ou votre external_id préfixé ext: (ex. ext:D-2026-4582).

Request Body schema: application/json
reason
string <= 500 characters

Motif transmis aux signataires (facultatif).

Responses

Response Schema: application/json
id
string
object
string
Value: "signature_request"
mode
string
Enum: "sandbox" "live"
status
string (RequestStatus)
Enum: "draft" "sent" "in_progress" "completed" "refused" "expired" "cancelled"
  • draft — créée, non envoyée
  • sent — envoyée, aucun signataire n'a encore signé
  • in_progress — au moins un signataire a signé, d'autres attendent
  • completed — tous ont signé ; exemplaire signé et certificat disponibles
  • refused / expired / cancelled — terminée sans signature complète
title
string
external_id
string
created_at
string <date-time>
sent_at
string <date-time>
completed_at
string <date-time>
expires_at
string <date-time>
Array of objects (Document)
Array of objects (Signer)
object

Renseigné quand completed.

object
object

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "sr_01J9K3…",
  • "object": "signature_request",
  • "mode": "sandbox",
  • "status": "draft",
  • "title": "string",
  • "external_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "documents": [],
  • "signers": [
    ],
  • "proof": {},
  • "metadata": {
    },
  • "billing": {
    }
}

Journal des événements (piste d'audit)

Authorizations:
bearerAuth
path Parameters
id
required
string

Identifiant TeamSign (sr_…) ou votre external_id préfixé ext: (ex. ext:D-2026-4582).

Responses

Response Schema: application/json
Array of objects (Event)

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Documents

Télécharger l'original, l'exemplaire signé et le certificat.

Télécharger un document

kind=signed et kind=certificate ne sont disponibles qu'une fois la demande completed. L'exemplaire signé contient les signatures, paraphes et mentions ; le certificat est le PDF de preuve séparé (identité des signataires, OTP, horodatage qualifié, empreinte SHA-256).

Authorizations:
bearerAuth
path Parameters
id
required
string

Identifiant TeamSign (sr_…) ou votre external_id préfixé ext: (ex. ext:D-2026-4582).

document_id
required
string
query Parameters
kind
required
string
Enum: "original" "signed" "certificate"

Responses

Response Schema: application/pdf
string <binary>

Response samples

Content type
application/json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "errors": [
    ]
}

Modèles

Réutiliser les modèles et annexes définis dans TeamSign.

Lister les modèles et annexes disponibles

Les modèles (doc_templates) et annexes (doc_attachments, ex. CGV) créés dans TeamSign. Un modèle fixe embarque son PDF ; un modèle variable attend un PDF fourni à la création.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array of objects (Template)
Array of objects (Attachment)

Response samples

Content type
application/json
{
  • "templates": [
    ],
  • "attachments": [
    ]
}

Webhooks

Être notifié en temps réel des événements.

Lister les webhooks

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array of objects (Webhook)

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Créer un webhook

TeamSign envoie un POST JSON à votre URL pour chaque événement souscrit, signé par l'en-tête X-TeamSign-Signature: t=<timestamp>,v1=<hmac_sha256(secret, timestamp + "." + body)> (+ X-TeamSign-Event et X-TeamSign-Delivery). Réponse attendue : 2xx sous 10 s. Sinon, nouvelle tentative à 1 min, 10 min, 1 h, 6 h, 24 h. Le secret n'est renvoyé qu'à la création. Un webhook créé avec une clé sandbox ne reçoit que les événements sandbox (et inversement) ; depuis Réglages → Développeurs vous pouvez créer un webhook « sandbox et live ». events: ["*"] = tous.

Authorizations:
bearerAuth
Request Body schema: application/json
required
url
required
string <uri> ^https://
events
required
Array of strings non-empty
Items Enum: "request.opened" "request.signer_signed" "request.completed" "request.refused" "request.expired" "request.cancelled"
description
string <= 120 characters

Responses

Response Schema: application/json
url
required
string <uri> ^https://
events
required
Array of strings non-empty
Items Enum: "request.opened" "request.signer_signed" "request.completed" "request.refused" "request.expired" "request.cancelled"
description
string <= 120 characters
id
string
secret
string

Renvoyé uniquement à la création.

active
boolean
created_at
string <date-time>
object

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "url": "http://example.com",
  • "events": [
    ],
  • "description": "string",
  • "id": "wh_3",
  • "secret": "string",
  • "active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_delivery": {
    }
}

Supprimer un webhook

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "errors": [
    ]
}

Envoyer un événement de test

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response Schema: application/json
delivered
boolean
http_status
integer
duration_ms
integer

Response samples

Content type
application/json
{
  • "delivered": true,
  • "http_status": 0,
  • "duration_ms": 0
}

Tous les signataires ont signé Webhook

Authorizations:
bearerAuth
Request Body schema: application/json
id
string
type
string
created_at
string <date-time>
mode
string
Enum: "sandbox" "live"
object

Responses

Request samples

Content type
application/json
{}

Un signataire a signé (dossier multi-signataires) Webhook

Authorizations:
bearerAuth
Request Body schema: application/json
id
string
type
string
created_at
string <date-time>
mode
string
Enum: "sandbox" "live"
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "mode": "sandbox",
  • "data": {
    }
}

Un signataire a ouvert le document Webhook

Authorizations:
bearerAuth
Request Body schema: application/json
id
string
type
string
created_at
string <date-time>
mode
string
Enum: "sandbox" "live"
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "mode": "sandbox",
  • "data": {
    }
}

Un signataire a refusé (le dossier entier est refusé) Webhook

Authorizations:
bearerAuth
Request Body schema: application/json
id
string
type
string
created_at
string <date-time>
mode
string
Enum: "sandbox" "live"
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "mode": "sandbox",
  • "data": {
    }
}

Délai dépassé sans signature complète Webhook

Authorizations:
bearerAuth
Request Body schema: application/json
id
string
type
string
created_at
string <date-time>
mode
string
Enum: "sandbox" "live"
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "mode": "sandbox",
  • "data": {
    }
}

Demande annulée par l'émetteur Webhook

Authorizations:
bearerAuth
Request Body schema: application/json
id
string
type
string
created_at
string <date-time>
mode
string
Enum: "sandbox" "live"
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "mode": "sandbox",
  • "data": {
    }
}