Firma
API integration

list_all_firma_companies

Retrieve information about the authenticated firma company. Returns: id, company_name, account_owner, account_owner_email, website, icon_url, credits, date_created, date_changed, name, language, created_date, updated_date.

update_a_firma_company_by_id

Fully replace all firma company details in a single PUT operation. Returns: id, company_name, account_owner, account_owner_email, website, icon_url, credits, date_created, date_changed, name, language, created_date, updated_date. Required: name, account_owner, account_owner_email, website.

firma_companies_partial_update

Partially update specific firma company fields via PATCH; only the provided fields are changed. At least one field must be supplied. Returns: id, company_name, account_owner, account_owner_email, website, icon_url, credits, date_created, date_changed, name, language, created_date, updated_date.

list_all_firma_workspaces

List firma workspaces for the authenticated company. Returns: id, name, protected, date_created, date_changed. Supports optional filtering by name, protected status, and creation date range, and sorting by name, protected, or created_on.

create_a_firma_workspace

Create a new firma workspace for the authenticated company. Returns: id, name, protected, date_created, date_changed, api_key, created_date, updated_date. Required: name. All workspaces are created as non-protected by default.

update_a_firma_workspace_by_id

Fully replace a firma workspace by id (full replacement operation requiring the name field). Returns: id, name, protected, date_created, date_changed, api_key, created_date, updated_date. Required: id, name.

firma_workspaces_partial_update

Partially update a firma workspace by id via PATCH. Returns: id, name, protected, date_created, date_changed, api_key, created_date, updated_date, results, pagination. Required: id. Only the name field can be updated; the protected field is read-only and cannot be changed via API.

get_single_firma_workspace_by_id

Get a specific workspace in Firma using id. Returns fields including id, name, api_key, protected, created_date, updated_date, webhook_enabled, and webhook_secret details.

list_all_firma_templates

List firma templates with optional filtering by name or date range. Returns: id, name, description, document_url, document_url_expires_at, date_created, date_changed, page_count, expiration_hours, credit_cost, settings, recipients, fields, created_date, updated_date.

create_a_firma_template

Create a new firma template from a base64-encoded PDF document. Returns: id, name, description, document_url, document_url_expires_at, date_created, date_changed, page_count, expiration_hours, credit_cost, settings, recipients, fields, created_date, updated_date. Required: name, document.

get_single_firma_template_by_id

Get a single firma template by id. Returns the full template object including id, name, description, document_url, document_url_expires_at, page_count, expiration_hours, credit_cost, settings, recipients, fields, created_date, and updated_date. Required: id.

update_a_firma_template_by_id

Comprehensively update a firma template including metadata, users, fields, and reminders. Returns the full updated template including id, name, description, document_url, document_url_expires_at, page_count, expiration_hours, credit_cost, settings, recipients, fields, created_date, and updated_date. Required: id. At least one body section must be provided.

delete_a_firma_template_by_id

Soft-delete a firma template by id. The template is marked as deleted but its data is retained. Returns: message, template_id. Required: id.

firma_templates_duplicate

Duplicate a firma template into a new signing request, copying all fields, recipients, reminders, and settings. Returns: message, signing_request. Required: id.

firma_templates_partial_update

Partially update a firma template by id. Supports updating template properties (name, description, document, expiration_hours, settings) OR a single user — cannot mix both in one request. Returns: message, updated_fields, user, template_id. Required: id.

list_all_firma_template_users

List all recipients/users associated with a specific firma template. Returns: id, name, email, designation, order. Required: template_id.

list_all_firma_template_fields

List all fields configured for a specific firma template. Returns each field's id, field_name, field_type, required, position_x, position_y, page_number, recipient_id, variable_name, dropdown_options, read_only, and format_rules. Required: template_id.

list_all_firma_template_reminders

List all reminders configured for a specific firma template. Returns: id, hours, subject, message, all_users, template_user_id, date_created, date_changed. Required: template_id.

list_all_firma_signing_requests

List signing requests in firma with optional filters by name, status, date range, signer email, and signer name. Returns each item including id, name, description, document_url, expiration_hours, created_date, recipients, and fields.

create_a_firma_signing_request

Create a new firma signing request from a base64-encoded PDF document or an existing template (provide either document or template_id, not both). For document-based creation, allow_editing_before_sending is automatically set to true. Returns: id, name, description, document_url, document_url_expires_at, document_page_count, status, expiration_hours, settings, template_id, date_created, date_sent,…

get_single_firma_signing_request_by_id

Get a specific firma signing request by id. Returns: id, name, description, document_url, document_url_expires_at, document_page_count, status, expiration_hours, settings, template_id, date_created, date_sent, date_finished, date_cancelled, expires_at, certificate, final_document_download_url, final_document_download_error, page_count, credit_cost, created_date, updated_date, sent_date,…

update_a_firma_signing_request_by_id

Comprehensively update a firma signing request's properties, recipients, fields, and reminders in a single call. Returns: signing_request, changes. Required: id. Cannot update after the request has been sent, completed, or cancelled.

firma_signing_requests_send

Send a firma signing request to all recipients via email, triggering email delivery and recording the sent timestamp. Returns: message, signing_request_id, recipients_notified, sent_date, expires_at. Required: id.

firma_signing_requests_cancel

Cancel a firma signing request that has been sent but not yet completed. Returns: message, signing_request_id, cancelled_on, notify_signers. Required: id. Cannot cancel requests that are already finished, cancelled, or not yet sent.

firma_signing_requests_partial_update

Partially update a firma signing request by id. Supports updating name, description, document, expiration_hours, and settings, OR a single recipient (add or update) — cannot combine both in one request, and updates are blocked after the request has been sent, completed, or cancelled. Returns the updated signing request including id, name, description, created_date, updated_date, recipients,…

list_all_firma_signing_request_users

List all recipients/users for a specific signing request in firma. Returns: id, name, email, designation, order, finished_date, signature_details. Required: signing_request_id.

list_all_firma_signing_request_fields

List all fields for a specific firma signing request, including their values and completion status. Returns: id, field_name, field_type, field_value, completed. Required: signing_request_id.

list_all_firma_signing_request_reminders

List all reminders scheduled for a specific signing request in firma. Returns: id, hours, subject, message, all_users, template_user_id, date_created, date_changed. Required: signing_request_id.

create_a_firma_signing_request_resend

Resend a firma signing request notification to one or more eligible recipients. Returns: message, signing_request_id, recipients_notified, recipients. Required: signing_request_id, recipient_ids. Cannot resend to recipients who have already signed; for requests with signing order enabled, only recipients at the current active order may be targeted.

list_all_firma_webhooks

List firma webhooks with optional filtering and sorting. Returns: id, url, events, enabled, date_created, date_changed, description, consecutive_failures, auto_disabled_at, created_at, updated_at. Supports filtering by enabled status, url, event type, and creation date range.

create_a_firma_webhook

Create a new firma webhook. Returns: id, url, events, enabled, date_created, date_changed, description, consecutive_failures, auto_disabled_at, created_at, updated_at. Required: url, events.

get_single_firma_webhook_by_id

Get a specific firma webhook by id. Returns: id, url, events, enabled, date_created, date_changed, description, consecutive_failures, auto_disabled_at, created_at, updated_at. Required: id.

update_a_firma_webhook_by_id

Update an existing firma webhook by id. Returns: id, url, events, enabled, date_created, date_changed, description, consecutive_failures, auto_disabled_at, created_at, updated_at. Required: id.

delete_a_firma_webhook_by_id

Soft-delete a firma webhook by id, retaining data but marking the webhook as deleted. Returns: message, webhook_id. Required: id.

create_a_firma_webhook_test

Send a test payload to a firma webhook URL to verify it is working correctly. Returns: message, webhook_id, test_payload, response_status, response_time_ms. Required: webhook_id.

create_a_firma_webhooks_rotate_secret

Rotate the webhook signing secret for the company in firma. Generates a new secret while keeping the old one valid for 7 days to allow graceful migration. Returns: message, new_secret, old_secret_expires_at, rotated_at. Rate limited to 1 request per hour.

list_all_firma_webhooks_secret_status

Get the current webhook secret rotation status in firma. Returns: has_secret, secret_created_at, last_rotated_at, old_secret_expires_at, old_secret_still_valid.

create_a_firma_generate_template_token

Generate a JWT token for embedding a firma template in your application. Returns: token, expires_at, jwt_record_id. Required: companies_workspaces_templates_id. Token expires after 24 hours.

create_a_firma_revoke_template_token

Revoke a previously generated JWT template token in firma, preventing it from being used for template embedding. Returns: message, jwt_id, revoked_at. Required: jwt_id.

create_a_firma_jwt_generate_signing_request

Generate a JWT token in firma for embedding a signing request editor. Returns: jwt, jwt_id, expires_at, signing_request_id. Required: companies_workspaces_signing_requests_id. The JWT expires after 7 days.

create_a_firma_jwt_revoke_signing_request

Revoke a previously generated signing request JWT token in firma, preventing it from being used for embedded editing. Returns: message, jwt_id, revoked_at. Required: jwt_id.

create_a_firma_save_embedded_signing_request

Save changes to an embedded signing request in firma. Returns a confirmation message. Required: companies_workspaces_signing_requests_id.

create_a_firma_send_embedded_signing_request

Send an embedded signing request in firma to notify recipients and trigger the signing workflow. Returns: message, signing_request_id. Required: companies_workspaces_signing_requests_id.

create_a_firma_get_embedded_signing_request

Retrieve embedded signing request data from firma for use in an embedded editor. Returns the complete signing request object including signing_request, fields, recipients, and reminders. Required: companies_workspaces_signing_requests_id.

list_all_firma_documents

List documents (signing requests) in firma via this deprecated legacy endpoint — use /signing-requests instead. Returns: id, name, description, document_url, document_url_expires_at, document_page_count, status, expiration_hours, settings, template_id, date_created, date_sent, date_finished, date_cancelled, expires_at, certificate, final_document_download_url, final_document_download_error,…

create_a_firma_document

Create a new document (signing request) in firma via this deprecated legacy endpoint — use /signing-requests instead. Returns the created signing request including id, name, description, document_url, page_count, expiration_hours, credit_cost, settings, recipients, fields, created_date, and related timestamp fields. Required: name.

list_all_firma_settings

Retrieve workspace settings for a firma workspace. Returns: workspace_id, signing_request_email_header, signing_request_email_body, team_email, timezone. Required: workspace_id.

update_a_firma_setting_by_id

Update workspace settings for a firma workspace. Returns: workspace_id, signing_request_email_header, signing_request_email_body, team_email, timezone. Required: workspace_id.