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": false,
    "send_signing_email": true
  }
}
'

{
  "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": false,
    "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
}

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

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": false,
    "send_signing_email": true
  }
}
'

{
  "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": false,
    "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
}

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

name

string

required

Signing request name

Maximum string length: 255

Example:

"Employment Contract - John Doe"

document

string<byte>

required

Base64-encoded PDF document (mutually exclusive with template_id). Maximum size: 20MB.

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)

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.

Minimum array length: 1

Show child attributes

fields

object[]

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

Show child attributes

reminders

object[]

Array of reminder configurations

Show child attributes

settings

object

Signing request settings

Show child attributes

Response

Signing request created and sent successfully

id

string<uuid>

Signing request ID

name

string

Signing request name

description

string | null

Signing request description

status

enum<string>

Always 'sent' for this endpoint

Available options:

sent

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

Signing request and template settings. All 9 fields are returned by every endpoint that includes settings.

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 fields with real recipient UUIDs

Show child attributes

credits_remaining

integer

Company credits remaining after deduction

Create Signing Request Get Signing Request

⌘I