@firma-dev/sdk

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });

const response = await firma.signingRequests.createAndSendSigningRequest({
    "name": "Employment Contract - John Doe",
    "description": "Full-time employment contract",
    "document": "JVBERi0xLjQKJeLjz9MK...",
    "expiration_hours": 168,
    "recipients": [
        {
            "id": "temp_signer_1",
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "designation": "Signer",
            "order": 1,
            "phone_number": "+1-555-0123",
            "company": "Acme Corp",
            "title": "Software Engineer"
        }
    ],
    "fields": [
        {
            "recipient_id": "temp_signer_1",
            "type": "signature",
            "page": 1,
            "x": 100,
            "y": 500,
            "width": 200,
            "height": 50
        },
        {
            "recipient_id": "temp_signer_1",
            "type": "text",
            "page": 1,
            "x": 100,
            "y": 400,
            "width": 150,
            "height": 30,
            "variable_name": "phone_number",
            "required": true,
            "read_only": true
        }
    ],
    "settings": {
        "use_signing_order": true,
        "send_signing_email": true
    }
});
console.log(response);

curl --request POST \
  --url https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Employment Contract - John Doe",
  "description": "Contrat de travail à temps plein",
  "document": "JVBERi0xLjQKJeLjz9MK...",
  "expiration_hours": 168,
  "recipients": [
    {
      "id": "temp_signer_1",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "designation": "Signer",
      "order": 1,
      "phone_number": "+1-555-0123",
      "company": "Acme Corp",
      "title": "Ingénieur logiciel"
    }
  ],
  "fields": [
    {
      "recipient_id": "temp_signer_1",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 500,
      "width": 200,
      "height": 50
    },
    {
      "recipient_id": "temp_signer_1",
      "type": "text",
      "page": 1,
      "x": 100,
      "y": 400,
      "width": 150,
      "height": 30,
      "variable_name": "phone_number",
      "required": true,
      "read_only": true
    }
  ],
  "settings": {
    "use_signing_order": true,
    "send_signing_email": true
  }
}
'

import requests

url = "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send"

payload = {
    "name": "Employment Contract - John Doe",
    "description": "Contrat de travail à temps plein",
    "document": "JVBERi0xLjQKJeLjz9MK...",
    "expiration_hours": 168,
    "recipients": [
        {
            "id": "temp_signer_1",
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "designation": "Signer",
            "order": 1,
            "phone_number": "+1-555-0123",
            "company": "Acme Corp",
            "title": "Ingénieur logiciel"
        }
    ],
    "fields": [
        {
            "recipient_id": "temp_signer_1",
            "type": "signature",
            "page": 1,
            "x": 100,
            "y": 500,
            "width": 200,
            "height": 50
        },
        {
            "recipient_id": "temp_signer_1",
            "type": "text",
            "page": 1,
            "x": 100,
            "y": 400,
            "width": 150,
            "height": 30,
            "variable_name": "phone_number",
            "required": True,
            "read_only": True
        }
    ],
    "settings": {
        "use_signing_order": True,
        "send_signing_email": True
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Employment Contract - John Doe',
    description: 'Contrat de travail à temps plein',
    document: 'JVBERi0xLjQKJeLjz9MK...',
    expiration_hours: 168,
    recipients: [
      {
        id: 'temp_signer_1',
        first_name: 'John',
        last_name: 'Doe',
        email: 'john.doe@example.com',
        designation: 'Signer',
        order: 1,
        phone_number: '+1-555-0123',
        company: 'Acme Corp',
        title: 'Ingénieur logiciel'
      }
    ],
    fields: [
      {
        recipient_id: 'temp_signer_1',
        type: 'signature',
        page: 1,
        x: 100,
        y: 500,
        width: 200,
        height: 50
      },
      {
        recipient_id: 'temp_signer_1',
        type: 'text',
        page: 1,
        x: 100,
        y: 400,
        width: 150,
        height: 30,
        variable_name: 'phone_number',
        required: true,
        read_only: true
      }
    ],
    settings: {use_signing_order: true, send_signing_email: true}
  })
};

fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Employment Contract - John Doe',
    'description' => 'Contrat de travail à temps plein',
    'document' => 'JVBERi0xLjQKJeLjz9MK...',
    'expiration_hours' => 168,
    'recipients' => [
        [
                'id' => 'temp_signer_1',
                'first_name' => 'John',
                'last_name' => 'Doe',
                'email' => 'john.doe@example.com',
                'designation' => 'Signer',
                'order' => 1,
                'phone_number' => '+1-555-0123',
                'company' => 'Acme Corp',
                'title' => 'Ingénieur logiciel'
        ]
    ],
    'fields' => [
        [
                'recipient_id' => 'temp_signer_1',
                'type' => 'signature',
                'page' => 1,
                'x' => 100,
                'y' => 500,
                'width' => 200,
                'height' => 50
        ],
        [
                'recipient_id' => 'temp_signer_1',
                'type' => 'text',
                'page' => 1,
                'x' => 100,
                'y' => 400,
                'width' => 150,
                'height' => 30,
                'variable_name' => 'phone_number',
                'required' => true,
                'read_only' => true
        ]
    ],
    'settings' => [
        'use_signing_order' => true,
        'send_signing_email' => true
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send"

	payload := strings.NewReader("{\n  \"name\": \"Employment Contract - John Doe\",\n  \"description\": \"Contrat de travail à temps plein\",\n  \"document\": \"JVBERi0xLjQKJeLjz9MK...\",\n  \"expiration_hours\": 168,\n  \"recipients\": [\n    {\n      \"id\": \"temp_signer_1\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"designation\": \"Signer\",\n      \"order\": 1,\n      \"phone_number\": \"+1-555-0123\",\n      \"company\": \"Acme Corp\",\n      \"title\": \"Ingénieur logiciel\"\n    }\n  ],\n  \"fields\": [\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"signature\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 500,\n      \"width\": 200,\n      \"height\": 50\n    },\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"text\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 400,\n      \"width\": 150,\n      \"height\": 30,\n      \"variable_name\": \"phone_number\",\n      \"required\": true,\n      \"read_only\": true\n    }\n  ],\n  \"settings\": {\n    \"use_signing_order\": true,\n    \"send_signing_email\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Employment Contract - John Doe\",\n  \"description\": \"Contrat de travail à temps plein\",\n  \"document\": \"JVBERi0xLjQKJeLjz9MK...\",\n  \"expiration_hours\": 168,\n  \"recipients\": [\n    {\n      \"id\": \"temp_signer_1\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"designation\": \"Signer\",\n      \"order\": 1,\n      \"phone_number\": \"+1-555-0123\",\n      \"company\": \"Acme Corp\",\n      \"title\": \"Ingénieur logiciel\"\n    }\n  ],\n  \"fields\": [\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"signature\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 500,\n      \"width\": 200,\n      \"height\": 50\n    },\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"text\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 400,\n      \"width\": 150,\n      \"height\": 30,\n      \"variable_name\": \"phone_number\",\n      \"required\": true,\n      \"read_only\": true\n    }\n  ],\n  \"settings\": {\n    \"use_signing_order\": true,\n    \"send_signing_email\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Employment Contract - John Doe\",\n  \"description\": \"Contrat de travail à temps plein\",\n  \"document\": \"JVBERi0xLjQKJeLjz9MK...\",\n  \"expiration_hours\": 168,\n  \"recipients\": [\n    {\n      \"id\": \"temp_signer_1\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"designation\": \"Signer\",\n      \"order\": 1,\n      \"phone_number\": \"+1-555-0123\",\n      \"company\": \"Acme Corp\",\n      \"title\": \"Ingénieur logiciel\"\n    }\n  ],\n  \"fields\": [\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"signature\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 500,\n      \"width\": 200,\n      \"height\": 50\n    },\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"text\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 400,\n      \"width\": 150,\n      \"height\": 30,\n      \"variable_name\": \"phone_number\",\n      \"required\": true,\n      \"read_only\": true\n    }\n  ],\n  \"settings\": {\n    \"use_signing_order\": true,\n    \"send_signing_email\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Employment Contract - John Doe",
  "description": "Contrat de travail à temps plein",
  "status": "sent",
  "document_url": "https://storage.supabase.co/...",
  "page_count": 3,
  "expiration_hours": 168,
  "settings": {
    "use_signing_order": true,
    "allow_download": true,
    "attach_pdf_on_finish": true,
    "send_signing_email": true,
    "send_finish_email": true,
    "send_expiration_email": true,
    "send_cancellation_email": true,
    "hand_drawn_only": false
  },
  "created_date": "2026-01-12T10:30:00Z",
  "sent_date": "2026-01-12T10:30:00Z",
  "template_id": null,
  "first_signer": {
    "id": "rec456-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "signing_link": "https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000"
  },
  "recipients": [
    {
      "id": "rec456-e89b-12d3-a456-426614174000",
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "id": "field123-e89b-12d3-a456-426614174000",
      "field_type": "signature",
      "seal_participant_id": null
    }
  ],
  "credits_remaining": 99
}

Demandes de Signature

Créer et Envoyer une Demande de Signature (Atomique)

Crée et envoie immédiatement une demande de signature en une seule opération atomique. Ce endpoint combine les fonctionnalités de POST /signing-requests et POST /signing-requests//send.

Avantages Clés :

Un seul appel API au lieu de deux requêtes séparées
Valide toutes les exigences d’envoi AVANT de créer la demande de signature
Déduction de crédit atomique - facture uniquement si tout réussit
Renvoie status: ‘sent’ immédiatement avec les détails du premier signataire
Plus efficace (économise 1 appel API + le temps d’aller-retour)

Validation :

Toutes les validations de création standard (document/modèle, destinataires, champs)
Validations d’envoi supplémentaires :
- Tous les signataires doivent avoir un first_name et un email valide
- Les champs en lecture seule requis doivent avoir un final_value renseigné
- Les champs de données prérempliées (variable_name) doivent avoir les données utilisateur correspondantes
- L’entreprise doit disposer de crédits suffisants (≥1)

Atomicité :

Si une validation échoue, rien n’est créé
Le crédit n’est déduit qu’après la création réussie et avant l’envoi de l’email
Si l’envoi de l’email échoue après la création, la demande de signature reste au statut ‘draft’ et le crédit N’est PAS déduit

Motif d’ID Temporaire : Pour une création basée sur un document, utilise des ID temporaires (format : ‘temp_X’) pour référencer les destinataires avant leur création. L’API valide toutes les références et fait automatiquement correspondre les ID temporaires aux vrais UUID.

Limite de Débit : 120 requêtes/minute (identique aux opérations d’écriture)

POST

signing-requests

create-and-send

@firma-dev/sdk

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });

const response = await firma.signingRequests.createAndSendSigningRequest({
    "name": "Employment Contract - John Doe",
    "description": "Full-time employment contract",
    "document": "JVBERi0xLjQKJeLjz9MK...",
    "expiration_hours": 168,
    "recipients": [
        {
            "id": "temp_signer_1",
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "designation": "Signer",
            "order": 1,
            "phone_number": "+1-555-0123",
            "company": "Acme Corp",
            "title": "Software Engineer"
        }
    ],
    "fields": [
        {
            "recipient_id": "temp_signer_1",
            "type": "signature",
            "page": 1,
            "x": 100,
            "y": 500,
            "width": 200,
            "height": 50
        },
        {
            "recipient_id": "temp_signer_1",
            "type": "text",
            "page": 1,
            "x": 100,
            "y": 400,
            "width": 150,
            "height": 30,
            "variable_name": "phone_number",
            "required": true,
            "read_only": true
        }
    ],
    "settings": {
        "use_signing_order": true,
        "send_signing_email": true
    }
});
console.log(response);

curl --request POST \
  --url https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Employment Contract - John Doe",
  "description": "Contrat de travail à temps plein",
  "document": "JVBERi0xLjQKJeLjz9MK...",
  "expiration_hours": 168,
  "recipients": [
    {
      "id": "temp_signer_1",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "designation": "Signer",
      "order": 1,
      "phone_number": "+1-555-0123",
      "company": "Acme Corp",
      "title": "Ingénieur logiciel"
    }
  ],
  "fields": [
    {
      "recipient_id": "temp_signer_1",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 500,
      "width": 200,
      "height": 50
    },
    {
      "recipient_id": "temp_signer_1",
      "type": "text",
      "page": 1,
      "x": 100,
      "y": 400,
      "width": 150,
      "height": 30,
      "variable_name": "phone_number",
      "required": true,
      "read_only": true
    }
  ],
  "settings": {
    "use_signing_order": true,
    "send_signing_email": true
  }
}
'

import requests

url = "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send"

payload = {
    "name": "Employment Contract - John Doe",
    "description": "Contrat de travail à temps plein",
    "document": "JVBERi0xLjQKJeLjz9MK...",
    "expiration_hours": 168,
    "recipients": [
        {
            "id": "temp_signer_1",
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "designation": "Signer",
            "order": 1,
            "phone_number": "+1-555-0123",
            "company": "Acme Corp",
            "title": "Ingénieur logiciel"
        }
    ],
    "fields": [
        {
            "recipient_id": "temp_signer_1",
            "type": "signature",
            "page": 1,
            "x": 100,
            "y": 500,
            "width": 200,
            "height": 50
        },
        {
            "recipient_id": "temp_signer_1",
            "type": "text",
            "page": 1,
            "x": 100,
            "y": 400,
            "width": 150,
            "height": 30,
            "variable_name": "phone_number",
            "required": True,
            "read_only": True
        }
    ],
    "settings": {
        "use_signing_order": True,
        "send_signing_email": True
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Employment Contract - John Doe',
    description: 'Contrat de travail à temps plein',
    document: 'JVBERi0xLjQKJeLjz9MK...',
    expiration_hours: 168,
    recipients: [
      {
        id: 'temp_signer_1',
        first_name: 'John',
        last_name: 'Doe',
        email: 'john.doe@example.com',
        designation: 'Signer',
        order: 1,
        phone_number: '+1-555-0123',
        company: 'Acme Corp',
        title: 'Ingénieur logiciel'
      }
    ],
    fields: [
      {
        recipient_id: 'temp_signer_1',
        type: 'signature',
        page: 1,
        x: 100,
        y: 500,
        width: 200,
        height: 50
      },
      {
        recipient_id: 'temp_signer_1',
        type: 'text',
        page: 1,
        x: 100,
        y: 400,
        width: 150,
        height: 30,
        variable_name: 'phone_number',
        required: true,
        read_only: true
      }
    ],
    settings: {use_signing_order: true, send_signing_email: true}
  })
};

fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Employment Contract - John Doe',
    'description' => 'Contrat de travail à temps plein',
    'document' => 'JVBERi0xLjQKJeLjz9MK...',
    'expiration_hours' => 168,
    'recipients' => [
        [
                'id' => 'temp_signer_1',
                'first_name' => 'John',
                'last_name' => 'Doe',
                'email' => 'john.doe@example.com',
                'designation' => 'Signer',
                'order' => 1,
                'phone_number' => '+1-555-0123',
                'company' => 'Acme Corp',
                'title' => 'Ingénieur logiciel'
        ]
    ],
    'fields' => [
        [
                'recipient_id' => 'temp_signer_1',
                'type' => 'signature',
                'page' => 1,
                'x' => 100,
                'y' => 500,
                'width' => 200,
                'height' => 50
        ],
        [
                'recipient_id' => 'temp_signer_1',
                'type' => 'text',
                'page' => 1,
                'x' => 100,
                'y' => 400,
                'width' => 150,
                'height' => 30,
                'variable_name' => 'phone_number',
                'required' => true,
                'read_only' => true
        ]
    ],
    'settings' => [
        'use_signing_order' => true,
        'send_signing_email' => true
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send"

	payload := strings.NewReader("{\n  \"name\": \"Employment Contract - John Doe\",\n  \"description\": \"Contrat de travail à temps plein\",\n  \"document\": \"JVBERi0xLjQKJeLjz9MK...\",\n  \"expiration_hours\": 168,\n  \"recipients\": [\n    {\n      \"id\": \"temp_signer_1\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"designation\": \"Signer\",\n      \"order\": 1,\n      \"phone_number\": \"+1-555-0123\",\n      \"company\": \"Acme Corp\",\n      \"title\": \"Ingénieur logiciel\"\n    }\n  ],\n  \"fields\": [\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"signature\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 500,\n      \"width\": 200,\n      \"height\": 50\n    },\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"text\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 400,\n      \"width\": 150,\n      \"height\": 30,\n      \"variable_name\": \"phone_number\",\n      \"required\": true,\n      \"read_only\": true\n    }\n  ],\n  \"settings\": {\n    \"use_signing_order\": true,\n    \"send_signing_email\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Employment Contract - John Doe\",\n  \"description\": \"Contrat de travail à temps plein\",\n  \"document\": \"JVBERi0xLjQKJeLjz9MK...\",\n  \"expiration_hours\": 168,\n  \"recipients\": [\n    {\n      \"id\": \"temp_signer_1\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"designation\": \"Signer\",\n      \"order\": 1,\n      \"phone_number\": \"+1-555-0123\",\n      \"company\": \"Acme Corp\",\n      \"title\": \"Ingénieur logiciel\"\n    }\n  ],\n  \"fields\": [\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"signature\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 500,\n      \"width\": 200,\n      \"height\": 50\n    },\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"text\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 400,\n      \"width\": 150,\n      \"height\": 30,\n      \"variable_name\": \"phone_number\",\n      \"required\": true,\n      \"read_only\": true\n    }\n  ],\n  \"settings\": {\n    \"use_signing_order\": true,\n    \"send_signing_email\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Employment Contract - John Doe\",\n  \"description\": \"Contrat de travail à temps plein\",\n  \"document\": \"JVBERi0xLjQKJeLjz9MK...\",\n  \"expiration_hours\": 168,\n  \"recipients\": [\n    {\n      \"id\": \"temp_signer_1\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"designation\": \"Signer\",\n      \"order\": 1,\n      \"phone_number\": \"+1-555-0123\",\n      \"company\": \"Acme Corp\",\n      \"title\": \"Ingénieur logiciel\"\n    }\n  ],\n  \"fields\": [\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"signature\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 500,\n      \"width\": 200,\n      \"height\": 50\n    },\n    {\n      \"recipient_id\": \"temp_signer_1\",\n      \"type\": \"text\",\n      \"page\": 1,\n      \"x\": 100,\n      \"y\": 400,\n      \"width\": 150,\n      \"height\": 30,\n      \"variable_name\": \"phone_number\",\n      \"required\": true,\n      \"read_only\": true\n    }\n  ],\n  \"settings\": {\n    \"use_signing_order\": true,\n    \"send_signing_email\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Employment Contract - John Doe",
  "description": "Contrat de travail à temps plein",
  "status": "sent",
  "document_url": "https://storage.supabase.co/...",
  "page_count": 3,
  "expiration_hours": 168,
  "settings": {
    "use_signing_order": true,
    "allow_download": true,
    "attach_pdf_on_finish": true,
    "send_signing_email": true,
    "send_finish_email": true,
    "send_expiration_email": true,
    "send_cancellation_email": true,
    "hand_drawn_only": false
  },
  "created_date": "2026-01-12T10:30:00Z",
  "sent_date": "2026-01-12T10:30:00Z",
  "template_id": null,
  "first_signer": {
    "id": "rec456-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "signing_link": "https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000"
  },
  "recipients": [
    {
      "id": "rec456-e89b-12d3-a456-426614174000",
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "id": "field123-e89b-12d3-a456-426614174000",
      "field_type": "signature",
      "seal_participant_id": null
    }
  ],
  "credits_remaining": 99
}

Autorisations

Authorization

string

header

requis

Clé API pour l'authentification. Utilisez votre clé API directement sans préfixe (par exemple, 'your-api-key'). Le préfixe Bearer est optionnel mais pas obligatoire.

Corps

application/json

Option 1
Option 2
Option 3

name

string

requis

Nom de la demande de signature

Maximum string length: 255

Exemple:

"Employment Contract - John Doe"

document

string<byte>

requis

Document PDF ou DOCX encodé en base64 (mutuellement exclusif avec template_id et document_id). Les fichiers DOCX sont automatiquement convertis en PDF. Pour les documents de plus de 5 Mo, utilisez POST /documents et transmettez le document_id à la place.

Exemple:

"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c..."

description

string

Description de la demande de signature

Exemple:

"Full-time employment contract for Software Engineer position"

template_id

string<uuid>

ID du modèle à utiliser (mutuellement exclusif avec document et document_id).

Cachets. Si le modèle a des participants de cachet et que seal_participants est absent ou vaut null, la demande les hérite, ainsi que les champs du modèle qui leur appartiennent. Un tableau, y compris [], les remplace : les participants de cachet du modèle et leurs champs ne sont pas copiés. Tout autre type répond 400 VALIDATION_ERROR. Un cachet conservé et les destinataires sont renumérotés ensemble en une seule séquence d'ordre contiguë qui garde l'ordre relatif du modèle. Lorsque le modèle n'a pas de destinataires propres, les cachets hérités sont placés après les destinataires de la demande. Un cachet de modèle suit la version courante de sa lignée : la demande rattache la version courante, et non la version vers laquelle pointe le modèle. Si cette version courante est révoquée ou supprimée, ou si la lignée n'a pas de version courante, l'appel répond 409 SEAL_UNAVAILABLE et ne crée rien. Un cachet de modèle que l'entreprise de la clé API ne peut pas voir, ou dont la version courante est limitée à un espace de travail autre que celui de la clé API, n'est pas copié, et ses champs non plus ; la demande est tout de même créée et seal_participants liste le cachet comme une entrée écartée (dropped: true). Si un cachet devait être conservé alors que les cachets d'organisation ne sont pas activés, l'appel répond 503 SEALS_DISABLED.

Exemple:

"123e4567-e89b-12d3-a456-426614174000"

expiration_hours

integer

défaut:168

Nombre d'heures avant l'expiration de la demande de signature (par défaut : 168 = 7 jours)

Plage requise: x >= 1

Exemple:

168

recipients

object[]

Tableau de destinataires. Au moins un doit être un Signataire. Pour une création basée sur un document : obligatoire. Pour une création basée sur un modèle : optionnel (utilise les destinataires du modèle si omis). Utilisez template_user_id (préféré) ou order (solution de repli) pour faire correspondre les utilisateurs du modèle. Les destinataires dont la designation est CC ne sont jamais associés aux utilisateurs du modèle ; ils sont ajoutés comme destinataires en copie (CC). Les destinataires en copie (CC) du modèle sont copiés dans la demande de signature, en ignorant ceux dont l'adresse e-mail correspond, sans distinction entre majuscules et minuscules, à celle d'un destinataire en copie (CC) de la demande.

Minimum array length: 1

Show child attributes

fields

object[]

Tableau de champs à remplir (basé sur un document uniquement)

Show child attributes

anchor_tags

object[]

Balises d'ancrage pour le placement automatique des champs. Les marqueurs de texte dans le PDF sont localisés puis convertis en champs positionnés. Le texte d'ancrage est supprimé du PDF après traitement. Les champs créés à partir des balises d'ancrage s'ajoutent aux champs spécifiés manuellement. Disponible uniquement pour la création basée sur un document (pas pour celle basée sur un modèle).

Maximum array length: 100

Show child attributes

reminders

object[]

Tableau de configurations de rappels

Show child attributes

settings

object

Paramètres de la demande de signature

Show child attributes

document_id

string<uuid>

ID d'un document précédemment téléversé (mutuellement exclusif avec document et template_id). À obtenir en appelant d'abord POST /documents.

Exemple:

"123e4567-e89b-12d3-a456-426614174000"

language

enum<string> | null

Langue facultative des e-mails pour cette demande de signature. Lorsqu'elle est définie, tous les e-mails destinés au signataire (et le format de date) l'utilisent. Omettez-la ou utilisez null pour revenir à la langue par défaut de l'espace de travail, puis de l'entreprise (comportement inchangé).

Options disponibles:

en,

es,

it,

pt,

fr,

de,

el,

ru,

pl,

cs,

sv,

nl,

ro,

nb,

ca

completion_title

string | null

Titre affiché sur la page de finalisation après la signature. Se rabat sur la valeur du modèle (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise.

Maximum string length: 200

Exemple:

"Thank you for signing"

completion_message

string | null

Texte principal affiché sur la page de finalisation après la signature. Se rabat sur la valeur du modèle (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise.

Maximum string length: 1000

Exemple:

"Your signed copy is on its way to your inbox."

completion_redirect_url

string<uri> | null

URL vers laquelle le signataire est redirigé depuis la page de finalisation. Doit utiliser https:// (http://localhost et http://127.0.0.1 sont également acceptés sur les demandes de signature en mode test). Se rabat sur la valeur du modèle (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise.

Maximum string length: 2000

Exemple:

"https://example.com/thank-you"

completion_redirect_delay

integer | null

Secondes d'attente de la page de finalisation avant redirection (0 redirige immédiatement). S'applique uniquement lorsqu'une URL de redirection est résolue ; la page utilise 5 secondes lorsqu'aucun niveau ne définit de délai. Se rabat sur la valeur du modèle (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise.

Plage requise: 0 <= x <= 30

Exemple:

5

seal_participants

object[] | null

Participants de cachet d'organisation pour la nouvelle demande de signature : avec template_id, omettez la clé ou envoyez null pour hériter des cachets du modèle, envoyez [] pour n'avoir aucun cachet, ou envoyez un tableau pour les remplacer. Un cachet de modèle remplacé et ses champs ne sont pas copiés. Tout autre type répond 400 VALIDATION_ERROR. Sur une demande basée sur un modèle, les ordres des cachets et les ordres des destinataires sont renumérotés ensemble en une seule séquence contiguë, que les cachets soient hérités ou envoyés dans le tableau. Un tableau non vide, ou un cachet hérité qui serait conservé, exige que les cachets d'organisation soient activés ; sinon l'appel répond 503 SEALS_DISABLED.

Show child attributes

document_ids

string<uuid>[]

Identifiants de téléversement temporaire de POST /documents, dans l'ordre des documents, pour créer une demande de signature multi-documents (activation requise). Exactement un parmi document, document_id, document_ids ou template_id (400 CONFLICTING_DOCUMENT_SOURCE) ; un identifiant répété répond 400 DUPLICATE_DOCUMENT_ID, plus de 20 400 MAX_DOCUMENTS_EXCEEDED, un téléversement inconnu ou expiré 400 DOCUMENT_UPLOAD_NOT_FOUND, un ensemble de plus de 100 Mo 413 DOCUMENT_SET_TOO_LARGE ; plus d'un identifiant pour une entreprise non activée répond 409 MULTI_DOCUMENT_READ_ONLY.

Required array length: 1 - 20 elements

Réponse

Demande de signature créée et envoyée avec succès. La réponse peut inclure des avertissements non bloquants liés aux balises d'ancrage.

Demande de signature créée et envoyée

string<uuid>

requis

ID de la demande de signature

name

string

requis

Nom de la demande de signature

status

enum<string>

requis

Toujours 'sent' pour ce endpoint

Options disponibles:

sent

description

string | null

Description de la demande de signature

document_url

string<uri>

URL signée pour accéder au document

page_count

integer

Nombre de pages du document

expiration_hours

integer

Nombre d'heures avant expiration

settings

object

Paramètres renvoyés par les endpoints de liste et de détail des demandes de signature. Les modèles utilisent le schéma TemplateSettings (sans champs d'identité).

Show child attributes

created_date

string<date-time>

sent_date

string<date-time>

Date d'envoi de la demande

template_id

string<uuid> | null

first_signer

object

Détails du premier signataire ayant reçu l'email

Show child attributes

recipients

object[]

Tous les destinataires avec leurs véritables UUID

Show child attributes

fields

object[]

Tous les champs actifs de la nouvelle demande de signature, y compris les champs détenus par des participants de cachet. Chaque élément est l'enregistrement de champ stocké, et non la forme Field utilisée dans les requêtes : par exemple, le type de champ se trouve dans field_type, et un champ propre à un cachet n'a pas de destinataire et nomme son participant de cachet dans seal_participant_id.

seal_participants

object[]

Participants de cachet d'organisation dans l'ordre de signature. Vide lorsque la demande n'a pas de cachet. Chaque élément est soit un participant de cachet persisté (dropped: false), soit, sur une demande basée sur un modèle, une entrée pour un cachet de modèle qui n'a pas été copié parce que l'entreprise de la clé API ne peut pas voir le cachet ou parce que le cachet est limité à un autre espace de travail (dropped: true, id et order null, seal_out_of_scope: true). Les entrées écartées viennent après les entrées persistées, dans l'ordre du modèle. Les cachets de modèle qu'un tableau seal_participants explicite a remplacés ne sont pas listés.

Un participant de cachet persisté du nouveau document : toutes les clés de SealParticipantApi, plus dropped: false.

Option 1
Option 2

Show child attributes

credits_remaining

integer

Crédits restants pour l'entreprise après déduction

warnings

string[]

Avertissements optionnels non bloquants, incluant des propriétés de balise d'ancrage inconnues pendant la fenêtre de compatibilité et des avertissements de traitement des ancrages.