curl --request PUT \
  --url https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "signing_request_properties": {
    "name": "Updated Contract Name",
    "expiration_hours": 72
  },
  "recipients": [
    {
      "id": "rec1-e89b-12d3-a456-426614174000",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_recipients": [
    {
      "recipient_id": "rec2-e89b-12d3-a456-426614174000",
      "field_action": "reassign",
      "reassign_to_recipient_id": "rec1-e89b-12d3-a456-426614174000"
    }
  ],
  "fields": [
    {
      "id": "field1-e89b-12d3-a456-426614174000",
      "type": "signature",
      "position": {
        "x": 15,
        "y": 85,
        "width": 30,
        "height": 10
      },
      "page_number": 1,
      "required": true,
      "recipient_id": "rec1-e89b-12d3-a456-426614174000"
    }
  ],
  "reminders": [
    {
      "hours": 48,
      "all_users": true,
      "subject": "Reminder: Please sign the document",
      "message": "This is a reminder to complete your signature."
    }
  ]
}
'

{
  "signing_request": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "document_url": "<string>",
    "document_url_expires_at": "2023-11-07T05:31:56Z",
    "document_page_count": 2,
    "expiration_hours": 168,
    "settings": {
      "allow_download": true,
      "attach_pdf_on_finish": true,
      "allow_editing_before_sending": false,
      "send_signing_email": true,
      "send_finish_email": true,
      "send_expiration_email": true,
      "send_cancellation_email": true
    },
    "template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "date_created": "2023-11-07T05:31:56Z",
    "date_sent": "2023-11-07T05:31:56Z",
    "date_finished": "2023-11-07T05:31:56Z",
    "date_cancelled": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "certificate": {
      "generated": true,
      "generated_on": "2023-11-07T05:31:56Z",
      "has_error": true
    },
    "final_document_download_url": "<string>"
  },
  "changes": {
    "properties_updated": true,
    "recipients_created": 123,
    "recipients_updated": 123,
    "recipients_deleted": 123,
    "fields_created": 123,
    "fields_updated": 123,
    "fields_reassigned": 123,
    "reminders_created": 123,
    "reminders_updated": 123
  }
}

Signing Requests

Comprehensive Update Signing Request

Perform comprehensive updates to a signing request including properties, recipients, fields, and reminders. Cannot update after signing request has been sent, completed, or cancelled. All sections are optional but at least one must be provided.

Temporary ID Pattern for New Recipients: When adding new recipients in a comprehensive update, use the ‘temp_id’ field (format: ‘temp_X’) instead of ‘id’ to establish relationships with fields and reminders. This allows you to create new recipients and reference them in fields/reminders in a single request. Use the ‘id’ field to update existing recipients. Validation rules: (1) Temporary IDs must start with ‘temp’; (2) Each temporary ID must be unique within the request; (3) Fields and reminders can reference temporary IDs in their recipient_id property; (4) The API will automatically resolve temporary IDs to real UUIDs after recipient creation.

PUT

signing-requests

{id}

curl --request PUT \
  --url https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "signing_request_properties": {
    "name": "Updated Contract Name",
    "expiration_hours": 72
  },
  "recipients": [
    {
      "id": "rec1-e89b-12d3-a456-426614174000",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_recipients": [
    {
      "recipient_id": "rec2-e89b-12d3-a456-426614174000",
      "field_action": "reassign",
      "reassign_to_recipient_id": "rec1-e89b-12d3-a456-426614174000"
    }
  ],
  "fields": [
    {
      "id": "field1-e89b-12d3-a456-426614174000",
      "type": "signature",
      "position": {
        "x": 15,
        "y": 85,
        "width": 30,
        "height": 10
      },
      "page_number": 1,
      "required": true,
      "recipient_id": "rec1-e89b-12d3-a456-426614174000"
    }
  ],
  "reminders": [
    {
      "hours": 48,
      "all_users": true,
      "subject": "Reminder: Please sign the document",
      "message": "This is a reminder to complete your signature."
    }
  ]
}
'

{
  "signing_request": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "document_url": "<string>",
    "document_url_expires_at": "2023-11-07T05:31:56Z",
    "document_page_count": 2,
    "expiration_hours": 168,
    "settings": {
      "allow_download": true,
      "attach_pdf_on_finish": true,
      "allow_editing_before_sending": false,
      "send_signing_email": true,
      "send_finish_email": true,
      "send_expiration_email": true,
      "send_cancellation_email": true
    },
    "template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "date_created": "2023-11-07T05:31:56Z",
    "date_sent": "2023-11-07T05:31:56Z",
    "date_finished": "2023-11-07T05:31:56Z",
    "date_cancelled": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "certificate": {
      "generated": true,
      "generated_on": "2023-11-07T05:31:56Z",
      "has_error": true
    },
    "final_document_download_url": "<string>"
  },
  "changes": {
    "properties_updated": true,
    "recipients_created": 123,
    "recipients_updated": 123,
    "recipients_deleted": 123,
    "fields_created": 123,
    "fields_updated": 123,
    "fields_reassigned": 123,
    "reminders_created": 123,
    "reminders_updated": 123
  }
}

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.

Path Parameters

string<uuid>

required

Signing request ID

Body

application/json

signing_request_properties

object

Update signing request properties

Show child attributes

recipients

object[]

Upsert recipients - include 'id' to update existing recipients, use '_temp_id' (e.g., 'temp_1') for new recipients to reference them in fields and reminders within the same request

Show child attributes

deleted_recipients

object[]

Recipients to delete and how to handle their fields

Show child attributes

fields

object[]

Upsert fields - include id to update, omit id to create new

Show child attributes

reminders

object[]

Upsert reminders - include id to update, omit id to create new

Show child attributes

Response

Signing request updated successfully. Returns summary of changes made.

signing_request

object

Show child attributes

changes

object

Show child attributes

Get Signing Request Partially Update Signing Request

⌘I