@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",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 500,
      "width": 200,
      "height": 50,
      "required": true,
      "recipient_id": "rec456-e89b-12d3-a456-426614174000"
    }
  ],
  "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",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 500,
      "width": 200,
      "height": 50,
      "required": true,
      "recipient_id": "rec456-e89b-12d3-a456-426614174000"
    }
  ],
  "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

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)

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.

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

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[]

Participants de cachet d'organisation à inclure dans la séquence de signature

Show child attributes

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 avec les véritables UUID de destinataire

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.