FIfirma
Signing Requests

Create and Send Signing Request (Atomic)

Changed on

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/{id}/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
  • If the send step fails before any part of the send has started, the signing request is removed and an error is returned: the send step's 400, 402 or 422, some 409 codes, otherwise 500. No draft is left behind
  • If the send had already started, the request is kept and the response is a 409 carrying its signing_request_id: code SEND_EFFECTS_EXIST, or ALREADY_SENT if the send completed. Recover that request instead of retrying the create. A 409 with code SEND_IN_PROGRESS also leaves the request in place

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

Request

Request body

OR
OR

Example request

{
  "name": "Employment Contract - John Doe",
  "description": "Full-time employment contract for Software Engineer position",
  "document": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...",
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "expiration_hours": 168,
  "fields": [
    {
      "recipient_id": "temp_signer_1",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 200,
      "width": 200,
      "height": 50,
      "variable_name": "phone_number",
      "final_value": "Software Engineer",
      "background_color": "#FFFDE7"
    }
  ],
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "background_color": "#FFFDE7",
      "font_size": 12
    }
  ],
  "reminders": [
    {
      "hours_before_expiration": 24
    }
  ],
  "settings": {
    "identity_editable_fields": [
      "name",
      "company"
    ]
  },
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "completion_title": "Thank you for signing",
  "completion_message": "Your signed copy is on its way to your inbox.",
  "completion_redirect_url": "https://example.com/thank-you",
  "completion_redirect_delay": 5
}

Response

Signing request created and sent successfully. The response may include non-blocking anchor-tag warnings.

idstring uuid required

Signing request ID

namestring required

Signing request name

descriptionstring nullable

Signing request description

status'sent' required

Always 'sent' for this endpoint

document_urlstring uri

Signed URL to access document

page_countinteger

Number of pages in document

expiration_hoursinteger

Hours until expiration

created_datestring date-time
sent_datestring date-time

When request was sent

template_idstring uuid nullable
fieldsobject[]

All active fields of the new signing request, including the fields owned by seal participants. Each item is the stored field record, not the Field shape used in requests: for example the field type is in field_type, and a seal-owned field has no recipient and names its seal participant in seal_participant_id.

credits_remaininginteger

Company credits remaining after deduction

warningsstring[]

Optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

Changes

  • a6525941bc28Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added to the response body anyOf list for the response status

  • 3a2cdde3a64fRevision changes
    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status