Skip to main content
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
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
fields
object[]

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

reminders
object[]

Array of reminder configurations

settings
object

Signing request settings

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

recipients
object[]

All recipients with real UUIDs

fields
object[]

All fields with real recipient UUIDs

credits_remaining
integer

Company credits remaining after deduction