Skip to main content
POST
/
templates
Create Template
curl --request POST \
  --url https://api.firma.dev/functions/v1/signing-request-api/templates \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Employment Contract Template",
  "document": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...",
  "description": "Standard employment contract for new hires",
  "expiration_hours": 168,
  "settings": {
    "allow_editing_before_sending": false,
    "attach_pdf_on_finish": true,
    "allow_download": true,
    "hand_drawn_only": false,
    "require_otp_verification": null
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "document_url": "<string>",
  "document_url_expires_at": "2023-11-07T05:31:56Z",
  "page_count": 2,
  "expiration_hours": 168,
  "credit_cost": 1,
  "settings": {
    "allow_download": true,
    "attach_pdf_on_finish": true,
    "allow_editing_before_sending": false,
    "use_signing_order": false,
    "hand_drawn_only": false,
    "send_signing_email": true,
    "send_finish_email": true,
    "send_expiration_email": true,
    "send_cancellation_email": true,
    "require_otp_verification": null
  },
  "recipients": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "email": "jsmith@example.com",
      "first_name": "<string>",
      "last_name": "<string>",
      "designation": "Signer",
      "order": 2,
      "phone_number": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state_province": "<string>",
      "postal_code": "<string>",
      "country": "<string>",
      "title": "<string>",
      "company": "<string>",
      "required_fields": [
        "<string>"
      ],
      "missing_fields": [
        "<string>"
      ],
      "required_read_only_fields": [
        {
          "variable_name": "<string>",
          "field_type": "<string>"
        }
      ],
      "ready_to_send": true
    }
  ],
  "fields": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "text",
      "required": true,
      "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "variable_name": "<string>",
      "position": {
        "x": 50,
        "y": 50,
        "width": 50,
        "height": 50
      },
      "page_number": 2,
      "dropdown_options": [
        "<string>"
      ],
      "multi_group_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "date_default": "2023-12-25",
      "date_signing_default": true,
      "format_rules": {
        "dateFormat": "MMMM dd, yyyy"
      },
      "validation_rules": {},
      "read_only": false,
      "read_only_value": "<string>"
    }
  ],
  "created_date": "2023-11-07T05:31:56Z",
  "updated_date": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.firma.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

Template name

Maximum string length: 255
Example:

"Employment Contract Template"

document
string<byte>
required

Base64-encoded PDF or DOCX document. DOCX files are automatically converted to PDF. Maximum size: 20MB. The API will automatically extract the page count from the document.

Example:

"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c..."

description
string

Template description

Example:

"Standard employment contract for new hires"

expiration_hours
integer
default:168

Hours until signing request expires

Example:

168

settings
object

Response

Template created successfully

id
string<uuid>

Unique identifier for the template

name
string

Template name

Maximum string length: 255
description
string | null

Template description

document_url
string<uri>

Pre-signed URL to the PDF document. This is a time-limited signed URL for secure access - see document_url_expires_at for expiration time. Initial URLs are valid for 7 days; refreshed URLs are valid for 1 hour. Request a new template retrieval to get a fresh URL if expired.

document_url_expires_at
string<date-time> | null

ISO 8601 timestamp when the document_url will expire. After this time, the URL will return an access denied error. Fetch the template again to receive a fresh signed URL.

page_count
integer

Number of pages in the document

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

Hours until signing requests created from this template expire

Required range: x >= 1
credit_cost
integer
default:1

Number of credits consumed when a signing request is sent from this template. Minimum value is 1.

Required range: x >= 1
settings
object

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

recipients
object[]

Template recipients (included in GET single template)

fields
object[]

Template fields (included in GET single template)

created_date
string<date-time>

Template creation timestamp

updated_date
string<date-time>

Template last update timestamp