@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": "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
  }
}
'

import requests

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

payload = {
    "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
    }
}
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: '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}
  })
};

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' => '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
    ]
  ]),
  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\": \"Full-time employment contract\",\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\": \"Software Engineer\"\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\": \"Full-time employment contract\",\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\": \"Software Engineer\"\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\": \"Full-time employment contract\",\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\": \"Software Engineer\"\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": "Full-time employment contract",
  "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
}

Signing Requests

Create and Send Signing Request (Atomic)

Create and immediately send a signing request in a single atomic operation. This endpoint combines the functionality of POST /signing-requests and POST /signing-requests//send.

Key Benefits:

Single API call instead of two separate requests
Validates all send requirements BEFORE creating the signing request
Atomic credit deduction - only charges if everything succeeds
Returns status: ‘sent’ immediately with first signer details
More efficient (saves 1 API call + round-trip time)

Validation:

All standard creation validations (document/template, recipients, fields)
Additional send validations:
- All signers must have first_name and valid email
- Required read-only fields must have final_value populated
- Prefilled data fields (variable_name) must have corresponding user data
- Company must have sufficient credits (≥1)

Atomicity:

If any validation fails, nothing is created
Credit is only deducted after successful creation and before email send
If email send fails after creation, signing request remains in ‘draft’ status and credit is NOT deducted

Temporary ID Pattern: For document-based creation, use temporary IDs (format: ‘temp_X’) to reference recipients before creation. The API validates all references and automatically maps temporary IDs to real UUIDs.

Rate Limit: 120 requests/minute (same as write operations)

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": "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
  }
}
'

import requests

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

payload = {
    "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
    }
}
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: '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}
  })
};

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' => '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
    ]
  ]),
  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\": \"Full-time employment contract\",\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\": \"Software Engineer\"\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\": \"Full-time employment contract\",\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\": \"Software Engineer\"\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\": \"Full-time employment contract\",\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\": \"Software Engineer\"\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": "Full-time employment contract",
  "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
}

Authorizations

Authorization

string

header

required

API key for authentication. Use your API key directly without any prefix (e.g., 'your-api-key'). Bearer prefix is optional but not required.

Body

application/json

Option 1
Option 2
Option 3

name

string

required

Signing request name

Maximum string length: 255

Example:

"Employment Contract - John Doe"

document

string<byte>

required

Base64-encoded PDF or DOCX document (mutually exclusive with template_id and document_id). DOCX files are automatically converted to PDF. For documents larger than 5 MB, use POST /documents and pass the document_id instead.

Example:

"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c..."

description

string

Signing request description

Example:

"Full-time employment contract for Software Engineer position"

template_id

string<uuid>

Template ID to use (mutually exclusive with document and document_id).

Seals. If the template has seal participants and seal_participants is absent or null, the request inherits them and the template fields that belong to them. An array, including [], replaces them: the template's seal participants and their fields are not copied. Any other type answers 400 VALIDATION_ERROR. A kept seal and the recipients are renumbered together into one contiguous order sequence that keeps the template's relative order. When the template has no recipients of its own, inherited seals are placed after the request's recipients. A template seal follows the current version of its lineage: the request attaches the current version, not the version the template points at. If that current version is revoked or deleted, or the lineage has no current version, the call answers 409 SEAL_UNAVAILABLE and creates nothing. A template seal that the API key's company cannot see, or whose current version is limited to a workspace other than the API key's workspace, is not copied and neither are its fields; the request is still created and seal_participants lists the seal as a dropped entry (dropped: true). If a seal would be kept while organization seals are not enabled, the call answers 503 SEALS_DISABLED.

Example:

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

expiration_hours

integer

default:168

Hours until signing request expires (default: 168 = 7 days)

Required range: x >= 1

Example:

168

recipients

object[]

Array of recipients. At least one must be a Signer. For document-based: required. For template-based: optional (uses template recipients if omitted). Use template_user_id (preferred) or order (fallback) to match template users. Recipients with designation CC are never matched to template users; they are added as CC recipients. The template's CC recipients are copied to the signing request, skipping any whose email (case-insensitive) is already on a CC recipient of the request.

Minimum array length: 1

Show child attributes

fields

object[]

Array of fields to be filled (document-based only)

Show child attributes

anchor_tags

object[]

Anchor tags for automatic field placement. Text markers in the PDF are located and converted to positioned fields. The anchor text is removed from the PDF after processing. Fields created from anchor tags are added alongside any manually specified fields. Only available for document-based creation (not template-based).

Maximum array length: 100

Show child attributes

reminders

object[]

Array of reminder configurations

Show child attributes

settings

object

Signing request settings

Show child attributes

document_id

string<uuid>

ID of a previously uploaded document (mutually exclusive with document and template_id). Obtain by calling POST /documents first.

Example:

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

language

enum<string> | null

Opt-in email language for this signing request. When set, all signer-facing emails (and their date formatting) use it. Omit or null to fall back to the workspace, then company, default language (unchanged behavior).

Available options:

en,

es,

it,

pt,

fr,

de,

el,

ru,

pl,

cs,

sv,

nl,

ro,

nb,

ca

completion_title

string | null

Heading shown on the completion page after signing. Falls back to the template value (when template_id is used), then the workspace and company defaults.

Maximum string length: 200

Example:

"Thank you for signing"

completion_message

string | null

Body text shown on the completion page after signing. Falls back to the template value (when template_id is used), then the workspace and company defaults.

Maximum string length: 1000

Example:

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

completion_redirect_url

string<uri> | null

URL the signer is redirected to from the completion page. Must use https:// (http://localhost and http://127.0.0.1 are also accepted on test-mode signing requests). Falls back to the template value (when template_id is used), then the workspace and company defaults.

Maximum string length: 2000

Example:

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

completion_redirect_delay

integer | null

Seconds the completion page waits before redirecting (0 redirects immediately). Only applies when a redirect URL resolves; the page falls back to 5 seconds when no level sets a delay. Falls back to the template value (when template_id is used), then the workspace and company defaults.

Required range: 0 <= x <= 30

Example:

5

seal_participants

object[] | null

Organization seal participants for the new signing request: with template_id, omit the key or send null to inherit the template's seals, send [] for no seals, or send an array to replace them. A replaced template seal and its fields are not copied. Any other type answers 400 VALIDATION_ERROR. On a template-based request the seal orders and the recipients' orders are renumbered together into one contiguous sequence, whether the seals are inherited or sent in the array. A non-empty array, or an inherited seal that would be kept, requires organization seals to be enabled; otherwise the call answers 503 SEALS_DISABLED.

Show child attributes

document_ids

string<uuid>[]

Temporary upload ids from POST /documents, in document order, to create a multi-document signing request (enablement required). Exactly one of document, document_id or document_ids or template_id (400 CONFLICTING_DOCUMENT_SOURCE); a repeated id answers 400 DUPLICATE_DOCUMENT_ID, more than 20 400 MAX_DOCUMENTS_EXCEEDED, an unknown or expired upload 400 DOCUMENT_UPLOAD_NOT_FOUND, a set above 100 MB 413 DOCUMENT_SET_TOO_LARGE; more than one id for a company not enabled answers 409 MULTI_DOCUMENT_READ_ONLY.

Required array length: 1 - 20 elements

Response

Signing request created and sent successfully. The response may include non-blocking anchor-tag warnings.

Signing request created and sent

string<uuid>

required

Signing request ID

name

string

required

Signing request name

status

enum<string>

required

Always 'sent' for this endpoint

Available options:

sent

description

string | null

Signing request description

document_url

string<uri>

Signed URL to access document

page_count

integer

Number of pages in document

expiration_hours

integer

Hours until expiration

settings

object

Settings returned by the signing request list and detail endpoints. Templates use the TemplateSettings schema (no identity fields).

Show child attributes

created_date

string<date-time>

sent_date

string<date-time>

When request was sent

template_id

string<uuid> | null

first_signer

object

Details of the first signer who received the email

Show child attributes

recipients

object[]

All recipients with real UUIDs

Show child attributes

fields

object[]

All active fields of the new signing request, including the fields owned by seal participants. Each item is the stored field record, not the Field shape used in requests: for example the field type is in field_type, and a seal-owned field has no recipient and names its seal participant in seal_participant_id.

seal_participants

object[]

Organization seal participants in the signing order. Empty when the request has no seals. Each item is either a persisted seal participant (dropped: false) or, on a template-based request, an entry for a template seal that was not copied because the API key's company cannot see the seal or because the seal is limited to another workspace (dropped: true, id and order null, seal_out_of_scope: true). Dropped entries come after the persisted ones, in template order. Template seals that an explicit seal_participants array replaced are not listed.

A persisted seal participant of the new document: every key of SealParticipantApi, plus dropped: false.

Option 1
Option 2

Show child attributes

credits_remaining

integer

Company credits remaining after deduction

warnings

string[]

Optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.