--- title: Firma API Integration on Truto slug: firma category: E-Signature canonical: "https://truto.one/integrations/detail/firma/" --- # Firma API Integration on Truto **Category:** E-Signature **Status:** Generally available ## MCP-ready AI tools Truto exposes 48 tools for Firma that AI agents can call directly. - **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. ## How it works 1. **Link your customer's Firma account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Firma.** The Proxy API is a 1-to-1 mapping of the Firma API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed white-labeled e-signature in your SaaS** — Offer your customers a native signing experience inside your product without redirecting them to a third-party site. Use Firma's embedded JWT flows to keep contract creation and signing fully within your UI. - **Automate contract workflows per customer tenant** — Provision an isolated Firma workspace for every customer who signs up, keeping their templates, signing requests, and documents legally and operationally separated within your multi-tenant SaaS. - **Generate and dispatch contracts from your own data** — Pull template fields, inject data from your application database (tenant names, rent amounts, salary figures), and create signing requests programmatically so contracts always reflect the latest state of your records. - **Reconcile signed documents back into your system of record** — Subscribe to Firma webhooks to know the moment a document is signed, then pull the executed PDF and audit certificate to attach to the originating record in your CRM, ATS, or PropTech ledger. - **Ship a native template builder to your customers** — Let your end-users build their own contract templates inside your product using Firma's embedded template editor, authenticated with short-lived tokens you generate on demand. ## What you can build - **Per-tenant workspace provisioning** — Automatically create a dedicated Firma workspace when a new customer onboards, and update its timezone, email headers, and branding to match the tenant. - **Embedded template editor with JWT tokens** — Generate scoped template tokens and embed Firma's drag-and-drop PDF editor in an iframe so customers design contract templates without leaving your app. - **Embedded signing sessions inside your client portal** — Mint signing-request JWTs to render Firma's signing UI directly within your application, so signers complete documents in your native UX. - **Dynamic field-aware contract generation** — List a template's fields to discover variables, then create a signing request that pre-fills values pulled from your own database before sending. - **Webhook-driven document reconciliation** — Register webhooks for signing-request events, rotate signing secrets on a schedule, and trigger downstream automations (S3 archival, status updates) when documents complete. - **Resend and cancel controls for signing operations** — Expose buttons in your UI to send, resend, cancel, or partially update signing requests, plus configure automated reminder cadences per template. ## FAQs ### How does authentication work for embedded signing and template editing? Firma uses short-lived JWT tokens. You call the token-generation endpoints (template tokens for the editor, signing-request JWTs for signers) and embed the resulting URL in an iframe. Tokens can also be revoked programmatically if a session needs to be invalidated early. ### Can I keep each of my customers' data isolated? Yes. Firma is built around workspaces, and Truto exposes endpoints to create, list, update, and fetch workspaces. You can provision one workspace per tenant so templates, signing requests, and documents stay partitioned. ### How do I know when a document has been signed? Register a webhook through Truto using the webhook endpoints. You can test deliveries, rotate the signing secret, and check secret status. When events fire, your backend can fetch the signing request to retrieve the executed document and audit certificate. ### Can I pre-fill contract fields with data from my own system? Yes. Use the template fields endpoint to discover available variables and their constraints (coordinates, dropdown options, regex rules), then pass values when creating the signing request so the document is generated with your data already populated. ### Does Truto handle pagination and auth quirks for Firma? Yes. Truto normalizes pagination across list endpoints (companies, workspaces, templates, signing requests, documents, webhooks, settings) and manages credential storage and refresh, so you call a consistent interface regardless of the underlying API behavior. ### Can end-users edit a contract before it's sent? Yes. You can duplicate a template and use the partial-update endpoints to make one-off changes, or use the embedded save-and-send flow to let users adjust a signing request before dispatch.