Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

Create vs. create-and-send

POST /signing-requests creates a draft only - it never sends an email, no matter what settings you pass. To notify recipients immediately, use POST /signing-requests/create-and-send instead, or call .../send on the draft afterward. This is the most common cause of “I created a signing request but nothing was sent” reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

	`POST /signing-requests` (create)	`POST /signing-requests/create-and-send`
Result	A draft (`status: "draft"`). Nothing is sent.	The request is created and sent, atomically, in one call.
Recipients notified?	Never - regardless of `send_signing_email` or any other setting.	By default, yes. See `send_signing_email` below.
Credit charged / `sent_on` set?	No	Yes, immediately.
Still editable via PATCH/PUT?	Yes, until you call `/send`	No - the request is already in a sent state.
Best for	A draft-then-edit workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready.	A fire-and-forget call when you already have everything you need.

Use create when your workflow needs a review or editing step before anything reaches a recipient. Use create-and-send when you want the request live and recipients notified in a single call.

The `send_signing_email` flag

This flag lives in settings.send_signing_email, but it means something different depending on which endpoint you call:

Endpoint	Effect of `send_signing_email: false`
`POST /signing-requests` (create)	None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent.
`POST /signing-requests/create-and-send`	The request is still created and sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification email is suppressed.

send_signing_email: false on create-and-send is not a silent draft - it’s a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use create (the draft endpoint) instead.

The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

If you set it explicitly in settings, that value is stored on the signing request.
If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to disallowed if none of those are set.
When creating from a template and omitting it, the request inherits the template’s own allow_presigning_download value.

The public OpenAPI schema for create-and-send doesn’t currently list allow_presigning_download under its settings object, but the endpoint accepts and applies it identically to POST /signing-requests.

Steps

Create or select a template
Create a signing request referencing the template
Add recipients with required information (first name, last name, email)
Optionally add form fields with percentage-based positioning
Send the request via email or embed the signing view

Recipient Schema (Required Fields)

Recipients require first_name and last_name as separate fields - there is no single name field.

Each recipient must include:

first_name (required) - Recipient’s first name
last_name (optional) - Recipient’s last name (required only when creating via POST /signing-requests with a raw document)
email (required) - Email address (create warns on invalid format; create-and-send and /send reject it)
designation (required) - Role: "Signer", "CC", or "Approver". Approvers review and approve the document (no signature) via the approval_* field types below
order (optional) - Signing order for sequential workflows

Optional fields:

phone_number, street_address, city, state_province, postal_code, country, title, company
custom_fields - Object with custom key-value pairs

Create a signing request from a template (API)

Endpoint: POST /signing-requests

Example curl (create request from template):

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'

Successful response (201) returns a Document resource including id (the signing_request_id) and document_url where appropriate.

Create a signing request (server example) - Node (fetch)

const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}

Create a signing request (server example) - Python (requests)

import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()

Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

Inline base64 (document) works for small files, but sending a large document this way can fail with a 502 before your request ever reaches application validation - the payload hits a platform-level size limit, not an error you can catch and retry cleanly. If a document is anywhere near 5MB, use the two-step upload flow (document_id) below instead of inline base64, even though it’s more code to write.

Small files (under 5MB)
Large files (up to 50MB)

For documents under 5MB, include the base64-encoded file directly in the request body:

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'

For documents over 5MB, use the two-step upload flow:Step 1: Request an upload URL

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'

Response:

{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}

Step 2: Upload the file

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf

Step 3: Create the signing request

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'

The upload URL expires after 1 hour and can only be used once. Each document_id can only be used in one signing request.

You must provide exactly one of document, document_id, or template_id. They are mutually exclusive.

Adding form fields (percentage-based positioning)

Critical: All field position coordinates (x, y, width, height) must be percentages (0-100) relative to page dimensions, not pixels. The page_number field is required.

Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient’s own profile data? See the Field Prefilling guide. variable_name alone does not do this.

When creating a signing request directly (POST /signing-requests) or updating one, you can add form fields:

Field positioning example

{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}

Field types

signature - Signature field
text - Single-line text input
date - Date picker
checkbox - Checkbox
dropdown - Dropdown selector (requires dropdown_options)
initial - Initials field (also accepts initials as an alias)
approval_signature - APPROVED stamp (Approver only)
approval_checkmark - Approval checkmark (Approver only)
approval_date - Approval date (Approver only)

The approval_* field types can only be assigned to a recipient whose designation is "Approver" (assigning one to a Signer returns a 400). Their value is authored server-side when the approver completes their review, so you don’t submit a value for them, and the approval stamp is rendered onto the completion certificate.

Positioning guidelines

The coordinate system uses percentages for responsive scaling:

x: 0 (left edge) to 100 (right edge)
y: 0 (top edge) to 100 (bottom edge)
width: percentage of page width (e.g., 30 = 30% width)
height: percentage of page height (e.g., 8 = 8% height)

For a US Letter page (8.5” × 11”), use these rough conversions:

1 inch ≈ 11.76% width
1 inch ≈ 9.09% height

Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

Cannot update after sending: Once a signing request is sent, it cannot be modified. Updates only work for requests with status not_sent.

Comprehensive update (PUT)

Use comprehensive-update-signing-request for complex updates involving multiple sections. When to use:

Updating multiple recipients at once
Deleting recipients (with field reassignment/deletion)
Updating fields and reminders together
Making coordinated changes across multiple sections

Structure: All sections are optional, but at least one must be provided:

signing_request_properties - Update name, description, document, expiration, settings
recipients - Upsert recipients (include id to update, omit to create)
deleted_recipients - Delete recipients with field_action (delete or reassign fields)
fields - Upsert fields (include id to update, omit to create)
reminders - Upsert reminders (include id to update, omit to create)

Requirements:

✅ Can update multiple sections in one request
✅ Supports recipient deletion with field handling
✅ Only works before the request is sent

Example (Node.js):

const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    fields: [
      {
        id: 'field1-e89b-12d3-a456-426614174000',
        type: 'signature',
        position: { x: 15, y: 85, width: 30, height: 10 },
        page_number: 1,
        required: true,
        recipient_id: 'rec1-e89b-12d3-a456-426614174000'
      }
    ]
  })
});

const updatedRequest = await response.json();

Partial update (PATCH)

Use partially-update-signing-request when updating specific properties or a single recipient. When to use:

Updating name, description, or settings
Adding or updating one recipient at a time
Making targeted changes without affecting other data

Important: Cannot update both properties AND a recipient in the same request. Choose one:

Update properties only (name, description, document, expiration_hours, settings)
OR update/create a single recipient

Benefits:

✅ Only send the fields you want to change
✅ More efficient for small changes
✅ Other fields remain unchanged
✅ Safer for concurrent edits

Example (Node.js):

// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();

Example (Python):

import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()

Choosing between PUT and PATCH

Scenario	Use	Reason
Complete signing request rebuild	PUT	Full replacement with all sections (properties, recipients, fields, reminders)
Update name or settings only	PATCH	More efficient, preserves recipients and fields
Add/update one recipient	PATCH	Single recipient mode, other recipients unchanged
Update multiple recipients	PUT	Can upsert multiple recipients in one request
Delete recipients with field reassignment	PUT	Supports deleted_recipients with field_action
Change document and all fields	PUT	Major structural changes
Update custom fields	PATCH	Preserves core signing request
Replace all recipients	PUT	Clean slate approach

Important: Both update methods only work before the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

Best practices:

Update signing requests before calling /send
Validate recipient data before updating
Use PATCH for incremental changes
Implement retry logic with exponential backoff

Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST /signing-requests/{signing_request_id}/send to send emails to all recipients.

Example

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'

The /send endpoint validates that all recipients have required information (first_name and email - last_name is optional) and that any prefilled fields have the corresponding recipient data present.

Embedding the signing view

To embed the signing experience in your own app, fetch the recipient’s id from GET /signing-requests/{id}/users and build the signing URL:

https://app.firma.dev/signing/{recipient_id}

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the Embeddable Signing guide.

Edge cases & tips

Signing order: Ensure recipients have sequential order values (1, 2, 3…) for sequential signing workflows
Audit trail: Download the audit trail via GET /signing-requests/{id}/tracking to see all user actions
Download completed PDF: Use GET /signing-requests/{id}/download after completion
Webhooks: Subscribe to events like signing_request.completed instead of polling (see Webhooks guide)

Next steps

Prefill fields with recipient or static data before you send
Set up webhooks to receive real-time event notifications
Add automated reminders for pending recipients
Embed the template editor with JWT authentication (120 req/min)
Configure workspace settings for custom email templates (100-200 req/min)
Embeddable template editor with JWT authentication for secure embedded workflows

For sequential signing workflows with multiple signers, ensure each recipient has a sequential order value (1, 2, 3…).
For audit and compliance, download the final PDF via GET /signing-requests/signing_request_id/download after completion.
Use webhooks (see Webhooks Guide) to react to signing events instead of polling.

Starter guides

Advanced guides

Sending a signing request

Sending a signing request

Create vs. create-and-send

The `send_signing_email` flag

The `allow_presigning_download` flag

Steps

Recipient Schema (Required Fields)

Create a signing request from a template (API)

Create a signing request (server example) - Node (fetch)

Create a signing request (server example) - Python (requests)

Create a signing request from a document

Adding form fields (percentage-based positioning)

Field positioning example

Field types

Positioning guidelines

Updating signing requests

Comprehensive update (PUT)

Partial update (PATCH)

Choosing between PUT and PATCH

Sending (email invites)

Example

Embedding the signing view

Edge cases & tips

Next steps

​Sending a signing request

​Create vs. create-and-send

​The send_signing_email flag

​The allow_presigning_download flag

​Steps

​Recipient Schema (Required Fields)

​Create a signing request from a template (API)

​Create a signing request (server example) - Node (fetch)

​Create a signing request (server example) - Python (requests)

​Create a signing request from a document

​Adding form fields (percentage-based positioning)

​Field positioning example

​Field types

​Positioning guidelines

​Updating signing requests

​Comprehensive update (PUT)

​Partial update (PATCH)

​Choosing between PUT and PATCH

​Sending (email invites)

​Example

​Embedding the signing view

​Edge cases & tips

​Next steps

Sending a signing request

Create vs. create-and-send

The `send_signing_email` flag

The `allow_presigning_download` flag

Steps

Recipient Schema (Required Fields)

Create a signing request from a template (API)

Create a signing request (server example) - Node (fetch)

Create a signing request (server example) - Python (requests)

Create a signing request from a document

Adding form fields (percentage-based positioning)

Field positioning example

Field types

Positioning guidelines

Updating signing requests

Comprehensive update (PUT)

Partial update (PATCH)

Choosing between PUT and PATCH

Sending (email invites)

Example

Embedding the signing view

Edge cases & tips

Next steps