Skip to main content
POST
/
signing-requests
curl --request POST \
  --url https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Updated Contract Name",
  "expiration_hours": 72
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "status": "draft",
  "document_url": "<string>",
  "page_count": 2,
  "expiration_hours": 168,
  "template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "settings": {
    "allow_download": true,
    "attach_pdf_on_finish": true,
    "allow_editing_before_sending": false,
    "use_signing_order": true,
    "hand_drawn_only": false,
    "send_signing_email": true,
    "send_finish_email": true,
    "send_expiration_email": true,
    "send_cancellation_email": true,
    "require_otp_verification": null
  },
  "created_date": "2023-11-07T05:31:56Z",
  "updated_date": "2023-11-07T05:31:56Z",
  "sent_date": "2023-11-07T05:31:56Z",
  "finished_date": "2023-11-07T05:31:56Z",
  "cancelled_date": "2023-11-07T05:31:56Z",
  "recipients": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_name": "<string>",
      "last_name": "<string>",
      "name": "<string>",
      "email": "jsmith@example.com",
      "designation": "Signer",
      "order": 2,
      "phone_number": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state_province": "<string>",
      "postal_code": "<string>",
      "country": "<string>",
      "title": "<string>",
      "company": "<string>",
      "custom_fields": {},
      "finished_date": "2023-11-07T05:31:56Z"
    }
  ],
  "fields": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "text",
      "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "page_number": 2,
      "x_position": 123,
      "y_position": 123,
      "width": 123,
      "height": 123,
      "required": true,
      "read_only": true,
      "read_only_value": "<string>",
      "variable_name": "<string>",
      "dropdown_options": [
        "<string>"
      ],
      "format_rules": {},
      "validation_rules": {},
      "date_signing_default": true,
      "final_value": "<string>"
    }
  ],
  "warnings": [
    "<string>"
  ]
}

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

Create signing request from a PDF document

​
document
string<byte>
required

Base64-encoded PDF or DOCX document. DOCX files are automatically converted to PDF. Page count will be auto-extracted.

​
name
string

Name for the signing request

Maximum string length: 255
​
description
string

Description for the signing request

​
expiration_hours
integer
default:168

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

Required range: x >= 1
​
recipients
object[]

Recipients for the signing request. Use temporary IDs (e.g., 'temp_1') in the id field to reference recipients in fields/reminders.

​
fields
object[]

Fields to place on the document. Use recipient_id to assign fields to recipients.

​
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[]

Reminders to send to recipients

​
settings
object

Signing request settings

Response

Signing request created successfully. Response may include a 'warnings' array for email format validation warnings (non-blocking).

Signing request as returned by CREATE endpoints (POST /signing-requests, POST /documents)

​
id
string<uuid>

Unique identifier for the signing request

​
name
string

Signing request name

Maximum string length: 255
​
description
string | null

Signing request description

​
status
enum<string>

Status is always 'draft' for newly created signing requests

Available options:
draft
​
document_url
string<uri>

Pre-signed URL to the PDF document

​
page_count
integer

Number of pages in the document

Required range: x >= 1
​
expiration_hours
integer
default:168

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

Required range: x >= 1
​
template_id
string<uuid> | null

Template ID if created from a template

​
settings
object

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

​
created_date
string<date-time>

Creation timestamp

​
updated_date
string<date-time>

Last update timestamp

​
sent_date
string<date-time> | null

When the signing request was sent

​
finished_date
string<date-time> | null

When all signatures were completed

​
cancelled_date
string<date-time> | null

When the signing request was cancelled

​
recipients
object[]

Signing request recipients

​
fields
object[]

Signing request fields with flat position values

​
warnings
string[]

Optional email format validation warnings. Only present when recipient emails have unusual formats.