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."
    }
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "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": 123,
    "status": "<string>",
    "expiration_hours": 123,
    "settings": {
      "allow_download": true,
      "attach_pdf_on_finish": true,
      "hand_drawn_only": true
    },
    "template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expires_at": "2023-11-07T05:31:56Z",
    "created_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": [
    {
      "first_name": "<string>",
      "email": "jsmith@example.com",
      "designation": "Signer",
      "id": "<string>",
      "_temp_id": "<string>",
      "template_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "last_name": "<string>",
      "order": 2,
      "phone_number": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state_province": "<string>",
      "postal_code": "<string>",
      "country": "<string>",
      "title": "<string>",
      "company": "<string>",
      "custom_fields": {}
    }
  ],
  "reminders": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "hours": 2,
      "subject": "<string>",
      "message": "<string>",
      "all_users": true,
      "template_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "sent_on": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "summary": {
    "properties_updated": true,
    "recipients_created": 123,
    "recipients_updated": 123,
    "recipients_deleted": 123,
    "fields_created": 123,
    "fields_updated": 123,
    "fields_reassigned": 123,
    "fields_deleted": 123,
    "reminders_created": 123,
    "reminders_updated": 123,
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": "Validation failed",
  "message": "Multiple validation errors occurred",
  "details": {
    "recipients": [
      "Recipient 1: email is invalid"
    ],
    "deleted_recipients": [
      "Cannot reassign: designations must match"
    ],
    "fields": [
      "Field 2: x coordinate must be between 0 and 100"
    ]
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Not Found",
  "message": "The requested resource was not found"
}

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please wait before retrying.",
  "details": {
    "retry_after": 45
  }
}

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."
    }
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "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": 123,
    "status": "<string>",
    "expiration_hours": 123,
    "settings": {
      "allow_download": true,
      "attach_pdf_on_finish": true,
      "hand_drawn_only": true
    },
    "template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expires_at": "2023-11-07T05:31:56Z",
    "created_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": [
    {
      "first_name": "<string>",
      "email": "jsmith@example.com",
      "designation": "Signer",
      "id": "<string>",
      "_temp_id": "<string>",
      "template_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "last_name": "<string>",
      "order": 2,
      "phone_number": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state_province": "<string>",
      "postal_code": "<string>",
      "country": "<string>",
      "title": "<string>",
      "company": "<string>",
      "custom_fields": {}
    }
  ],
  "reminders": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "hours": 2,
      "subject": "<string>",
      "message": "<string>",
      "all_users": true,
      "template_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "sent_on": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "summary": {
    "properties_updated": true,
    "recipients_created": 123,
    "recipients_updated": 123,
    "recipients_deleted": 123,
    "fields_created": 123,
    "fields_updated": 123,
    "fields_reassigned": 123,
    "fields_deleted": 123,
    "reminders_created": 123,
    "reminders_updated": 123,
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": "Validation failed",
  "message": "Multiple validation errors occurred",
  "details": {
    "recipients": [
      "Recipient 1: email is invalid"
    ],
    "deleted_recipients": [
      "Cannot reassign: designations must match"
    ],
    "fields": [
      "Field 2: x coordinate must be between 0 and 100"
    ]
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Not Found",
  "message": "The requested resource was not found"
}

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please wait before retrying.",
  "details": {
    "retry_after": 45
  }
}

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

force_remove_conditions

boolean

default:false

When deleting recipients whose fields are referenced by conditions in other fields: if true, automatically remove the condition references; if false (default), the request will be rejected with an error listing the dependent fields.

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 the updated signing request and summary of changes made.

string<uuid>

Signing request ID (for backward compatibility)

name

string

Signing request name (for backward compatibility)

signing_request

object

Summary of the updated signing request (subset of full SigningRequest schema)

Show child attributes

recipients

object[]

Updated recipients list

Show child attributes

reminders

object[]

Updated reminders list

Show child attributes

summary

object

Summary of all changes made in this update

Show child attributes

Get Signing Request Partially Update Signing Request

⌘I