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

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 or DOCX document (mutually exclusive with template_id). DOCX files are automatically converted to PDF. 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)

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

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

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