### Finalize Domain Setup Response Source: https://docs.firma.dev/api-reference/v01.16.00/email-domains/finalize-domain-setup This is an example of a successful response when finalizing a domain setup. It confirms the domain is finalized and provides the DNS records required for email sending. ```json { "message": "Domain finalized. Add the following DNS records to enable email sending.", "domain": { "id": "123e4567-e89b-12d3-a456-426614174000", "domain": "acme.com", "verification_status": 2, "domain_status": 0 }, "dns_records": [ { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" }, { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" }, { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" } ], "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification" } ``` -------------------------------- ### Template User Response Example Source: https://docs.firma.dev/guides/api-changelog Example JSON response for the GET /templates/{id}/users endpoint, showing recipient details and readiness indicators. ```json { "results": [ { "id": "uuid", "name": "John Doe", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "designation": "Signer", "order": 1, "required_fields": ["email", "first_name"], "missing_fields": [], "ready_to_send": true } ] } ``` -------------------------------- ### HR Onboarding Email Template Source: https://docs.firma.dev/guides/workspace-settings Example email header and body for HR onboarding, guiding new hires to complete necessary documents. ```plaintext Header: "Welcome to [Company]! Complete Your Onboarding Documents" Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!" ``` -------------------------------- ### List Workspaces Response Example Source: https://docs.firma.dev/api-reference This is an example of a successful JSON response when listing workspaces. It includes a list of workspace objects and pagination details. ```json { "results": [ { "id": "789e4567-e89b-12d3-a456-426614174000", "name": "Sales Workspace", "protected": false, "api_key": "fk_a1b2c3d4e5f6g7h8i9j0", "created_date": "2024-01-20T09:00:00Z", "updated_date": "2024-01-20T09:00:00Z" }, { "id": "456e4567-e89b-12d3-a456-426614174000", "name": "Default Workspace", "protected": true, "api_key": "fk_z9y8x7w6v5u4t3s2r1q0", "created_date": "2024-01-15T10:30:00Z", "updated_date": "2024-01-15T10:30:00Z" } ], "pagination": { "current_page": 1, "page_size": 20, "total_count": 2, "total_pages": 1 } } ``` -------------------------------- ### Get Workspace Settings with Python (Flask) Source: https://docs.firma.dev/guides/workspace-settings Retrieve workspace settings using a Flask application. This example demonstrates making a GET request to the Firma API. Ensure FIRMA_API_BASE and FIRMA_API_KEY environment variables are set. ```python from flask import Flask, jsonify import os import requests app = Flask(__name__) FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api') API_KEY = os.getenv('FIRMA_API_KEY') @app.route('/api/workspace//settings', methods=['GET']) def get_workspace_settings(workspace_id): try: response = requests.get( f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings', headers={ 'Authorization': f'Bearer {API_KEY}' } ) response.raise_for_status() return jsonify(response.json()) except requests.exceptions.RequestException as e: return jsonify({'error': 'Failed to retrieve settings'}), 500 if __name__ == '__main__': app.run(port=3000) ``` -------------------------------- ### Download Signing Request Response Example Source: https://docs.firma.dev/api-reference/v01.16.00/signing-requests/download-signing-request This is an example of a successful JSON response when downloading a signing request document. It includes the status, whether it's a partial download, the download URL, and expiry information. ```json { "status": "finished", "is_partial": true, "download_url": "", "expires_at": "2023-11-07T05:31:56Z", "generated_at": "2023-11-07T05:31:56Z" } ``` -------------------------------- ### Finalize Domain Setup Source: https://docs.firma.dev/api-reference/v01.16.00/email-domains/finalize-domain-setup Finalizes the setup for a given domain ID and returns DNS records needed for email sending. ```APIDOC ## POST /company/domains/{id}/finalize ### Description Finalizes the setup for a given domain ID and returns DNS records needed for email sending. ### Method POST ### Endpoint https://api.firma.dev/functions/v1/signing-request-api/company/domains/{id}/finalize ### Parameters #### Path Parameters - **id** (string) - Required - Domain ID #### Headers - **Authorization** (string) - Required - API key for authentication. ### Request Example ```json { "example": "request body" } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message. - **domain** (object) - Email domain configuration. - **id** (string) - Domain ID. - **domain** (string) - Domain name. - **verification_status** (integer) - Verification status code. - **domain_status** (integer) - Domain status code. - **dns_records** (object[]) - DNS records to add for email sending. - **type** (string) - Type of DNS record (e.g., TXT, CNAME). - **name** (string) - Name of the DNS record. - **value** (string) - Value of the DNS record. - **ttl** (string) - Time to live for the DNS record. - **status** (string) - Status of the DNS record. - **next_step** (string) - Instructions for the next step in the process. #### Response Example ```json { "message": "Domain finalized. Add the following DNS records to enable email sending.", "domain": { "id": "123e4567-e89b-12d3-a456-426614174000", "domain": "acme.com", "verification_status": 2, "domain_status": 0 }, "dns_records": [ { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" }, { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" }, { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" } ], "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification" } ``` ``` -------------------------------- ### Migration Guide: v01.01.00 to v01.02.00 Source: https://docs.firma.dev/guides/api-changelog This guide covers the migration from API version v01.01.00 to v01.02.00. It states there are no breaking changes and notes enhancements to template and signing request user data, along with the addition of the `ready_to_send` boolean for recipient readiness checks. ```APIDOC ## Migration Guide: v01.01.00 to v01.02.00 ### Changes - No breaking changes. - Template and signing request users now include additional fields. - A `ready_to_send` boolean is available to check recipient readiness. ``` -------------------------------- ### Migration Guide: v01.00.02 to v01.01.00 Source: https://docs.firma.dev/guides/api-changelog This migration guide details the transition from API version v01.00.02 to v01.01.00. It confirms no breaking changes and highlights the introduction of new template management endpoints and API key regeneration capabilities. ```APIDOC ## Migration Guide: v01.00.02 to v01.01.00 ### Changes - No breaking changes. - New template management endpoints are available. - API key regeneration endpoints are available. ``` -------------------------------- ### API Response Example Source: https://docs.firma.dev/api-reference/v01.16.00/email-domains/list-company-domains This is an example of a successful JSON response when listing company domains. It includes details such as domain ID, domain name, verification status, and creation/change dates. ```json { "results": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "domain": "acme.com", "verification_status": 2, "domain_status": 1, "is_primary": true, "date_created": "2024-01-15T10:30:00Z", "date_changed": "2024-01-16T14:00:00Z" } ], "workspace_id": "456e4567-e89b-12d3-a456-426614174000" } ``` -------------------------------- ### List Webhooks Response Example Source: https://docs.firma.dev/api-reference/v01.16.00/webhooks/list-webhooks This is an example of a successful JSON response when listing webhooks. It includes a list of webhook objects and pagination details. ```json { "results": [ { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "url": "", "description": "", "events": [ "" ], "enabled": true, "consecutive_failures": 123, "auto_disabled_at": "2023-11-07T05:31:56Z", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } ], "pagination": { "current_page": 123, "page_size": 123, "total_count": 123, "total_pages": 123 } } ``` -------------------------------- ### Workspace Update Response Example Source: https://docs.firma.dev/api-reference/v01.16.00/workspaces/partially-update-a-workspace This is an example of the JSON response received after successfully partially updating a workspace. It includes all workspace details, with updated fields reflecting the changes made in the request. ```json { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "", "protected": true, "api_key": "", "created_date": "2023-11-07T05:31:56Z", "updated_date": "2023-11-07T05:31:56Z", "webhook_enabled": true, "webhook_secret": "", "webhook_secret_rotated_at": "2023-11-07T05:31:56Z", "webhook_secret_created_at": "2023-11-07T05:31:56Z", "ignore_company_webhooks": true } ``` -------------------------------- ### Finalize Domain Setup - API Request Source: https://docs.firma.dev/guides/white-labeling Once domain ownership is verified, call this API endpoint to finalize the domain setup. This will provide you with the necessary DNS records for enabling email sending. ```bash curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \ -H "Authorization: YOUR_API_KEY" ``` -------------------------------- ### Finalize Domain Setup Request (cURL) Source: https://docs.firma.dev/api-reference/v01.16.00/email-domains/finalize-domain-setup Use this cURL command to finalize the setup of an email domain. Replace `{id}` with your domain ID and `` with your actual API key. ```curl curl --request POST \ --url https://api.firma.dev/functions/v1/signing-request-api/company/domains/{id}/finalize \ --header 'Authorization: ' ``` -------------------------------- ### Migration Guide: v01.05.00 to v01.06.00 Source: https://docs.firma.dev/guides/api-changelog This guide details the migration from API version v01.05.00 to v01.06.00. It confirms no breaking changes and highlights the availability of split PDF download URLs on completed signing requests, and automatic normalization for `initials`/`initial` and `textarea`/`text_area` field type inputs. ```APIDOC ## Migration Guide: v01.05.00 to v01.06.00 ### Changes - No breaking changes. - Split PDF download URLs are available on completed signing requests. - Field type inputs `initials`/`initial` and `textarea`/`text_area` are both accepted with automatic normalization. ``` -------------------------------- ### Signing Request Response Example Source: https://docs.firma.dev/api-reference/v01.16.00/signing-requests/create-and-send-signing-request-atomic This is an example of a successful response when creating and sending a signing request. It includes the signing request ID, status, document URL, and details about the first signer. ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Employment Contract - John Doe", "description": "Full-time employment contract", "status": "sent", "document_url": "https://storage.supabase.co/...", "page_count": 3, "expiration_hours": 168, "settings": { "use_signing_order": true, "allow_download": true, "attach_pdf_on_finish": true, "send_signing_email": true, "send_finish_email": true, "send_expiration_email": true, "send_cancellation_email": true, "hand_drawn_only": false }, "created_date": "2026-01-12T10:30:00Z", "sent_date": "2026-01-12T10:30:00Z", "template_id": null, "first_signer": { "id": "rec456-e89b-12d3-a456-426614174000", "name": "John Doe", "email": "john.doe@example.com", "signing_link": "https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000" }, "recipients": [ { "id": "rec456-e89b-12d3-a456-426614174000", "first_name": "John", "last_name": "Doe", "name": "John Doe", "email": "john.doe@example.com", "designation": "Signer", "order": 1 } ], "fields": [ { "id": "field123-e89b-12d3-a456-426614174000", "type": "signature", "page": 1, "x": 100, "y": 500, "width": 200, "height": 50, "required": true, "recipient_id": "rec456-e89b-12d3-a456-426614174000" } ], "credits_remaining": 99 } ``` -------------------------------- ### Migration Guide: v01.02.00 to v01.03.00 Source: https://docs.firma.dev/guides/api-changelog This migration guide explains the changes from API version v01.02.00 to v01.03.00. It confirms no breaking changes and introduces email domain configuration for custom sending domains, a `declined` status for signing requests, and credit cost tracking for templates and signing requests. ```APIDOC ## Migration Guide: v01.02.00 to v01.03.00 ### Changes - No breaking changes. - Email domain configuration is available for custom sending domains. - A `declined` status has been added to the signing request status enum. - Credit cost tracking is available on templates and signing requests. ``` -------------------------------- ### Company Update Response Example Source: https://docs.firma.dev/api-reference/v01.16.00/company/partially-update-company-information This is an example of a successful response (200 OK) after partially updating company information. It includes the company's ID, name, language, account owner details, website, icon URL, credit count, and timestamps for creation and last update. ```json { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "", "language": "en", "account_owner": "", "account_owner_email": "jsmith@example.com", "website": "", "icon_url": "", "credits": 1, "created_date": "2023-11-07T05:31:56Z", "updated_date": "2023-11-07T05:31:56Z" } ``` -------------------------------- ### Finalize Workspace Domain Setup Source: https://docs.firma.dev/api-reference/v01.16.00/openapi-v01.16.00.json Finalizes the domain setup process by registering with the email provider. This action returns the necessary DNS records (SPF, DKIM, DMARC) that must be configured to enable email sending. This endpoint can only be invoked after the domain ownership has been successfully verified. ```APIDOC ## POST /workspace/{workspace_id}/domains/{id}/finalize ### Description Finalize domain setup by registering with the email provider. This returns the DNS records (SPF, DKIM, DMARC) that must be added to enable email sending. Can only be called after domain ownership is verified. ### Method POST ### Endpoint /workspace/{workspace_id}/domains/{id}/finalize ### Parameters #### Path Parameters - **workspace_id** (string) - Required - Workspace ID - **id** (string) - Required - Domain ID ### Response #### Success Response (200) - **message** (string) - Confirmation message. - **domain** (object) - The finalized domain object. - **id** (string) - Domain ID. - **domain** (string) - The domain name. - **verification_status** (integer) - The verification status of the domain. - **domain_status** (integer) - The status of the domain. - **dns_records** (array) - DNS records to add for email sending. - **type** (string) - The type of DNS record (e.g., TXT, CNAME). - **name** (string) - The name of the DNS record. - **value** (string) - The value of the DNS record. - **ttl** (string) - The Time To Live for the DNS record. - **status** (string) - The status of the DNS record. - **next_step** (string) - Instructions for the next action required. #### Response Example (200) { "message": "Domain finalized. Add the following DNS records to enable email sending.", "domain": { "id": "123e4567-e89b-12d3-a456-426614174000", "domain": "sales.acme.com", "verification_status": 2, "domain_status": 0 }, "dns_records": [ { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" }, { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" }, { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" } ], "next_step": "Add these DNS records, then call POST /workspace/{workspace_id}/domains/{id}/verify-dns to complete verification" } #### Error Response (400) - **error** (string) - Error type. - **message** (string) - Error description. #### Error Response Example (400) { "error": "Ownership not verified", "message": "Please verify domain ownership first by calling POST /workspace/{workspace_id}/domains/{id}/verify-ownership" } #### Error Response Example (400) { "error": "Already finalized", "message": "Domain has already been finalized" } #### Error Response (401) UnauthorizedError #### Error Response (404) NotFoundError #### Error Response (429) RateLimitError ``` -------------------------------- ### Create a Workspace using Python requests Source: https://docs.firma.dev/guides/creating-workspaces Server-side example for creating a workspace using Python and the requests library. Requires the FIRMA_API_KEY to be set in environment variables. ```python import os import requests def create_workspace(name): url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces' resp = requests.post(url, headers={ 'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}", 'Content-Type': 'application/json' }, json={ 'name': name }) resp.raise_for_status() return resp.json() ``` -------------------------------- ### Set up Cloudflare Pages Project Source: https://docs.firma.dev/guides/cloudflare-integration Initialize a new Cloudflare Pages project by creating a directory, initializing npm, and setting up basic public and functions directories. This serves as the foundation for your Pages Functions integration. ```bash mkdir firma-app && cd firma-app npm init -y mkdir public functions echo "

Firma App

" > public/index.html ``` -------------------------------- ### Create a Workspace using Node.js fetch Source: https://docs.firma.dev/guides/creating-workspaces Server-side example for creating a workspace using Node.js and the fetch API. Requires the FIRMA_API_KEY to be set in environment variables. ```javascript import fetch from 'node-fetch' export async function createWorkspace(name) { const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ name }) }) if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`) return resp.json() } ``` -------------------------------- ### Create Signing Request from Template (Python requests) Source: https://docs.firma.dev/guides/sending-signing-request Server-side example using Python and the requests library to create a signing request from a template. Requires setting the FIRMA_API_KEY environment variable. ```python import os import requests def create_from_template(template_id): url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests' resp = requests.post(url, headers={ 'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}", 'Content-Type': 'application/json' }, json={ 'template_id': template_id, 'name': 'NDA - Acme Corp', 'recipients': [ { 'first_name': 'Alice', 'last_name': 'Johnson', 'email': 'alice@example.com', 'designation': 'Signer', 'order': 1 } ] }) resp.raise_for_status() return resp.json() ``` -------------------------------- ### Get Workspace Settings cURL Example Source: https://docs.firma.dev/api-reference/v01.16.00/workspace-settings/get-workspace-settings Use this cURL command to retrieve the settings for a given workspace. Replace `{workspace_id}` with the actual workspace ID and `` with your API key. ```curl curl --request GET \ --url https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \ --header 'Authorization: ' ``` -------------------------------- ### Default Settings on Workspace Creation Example Source: https://docs.firma.dev/guides/workspace-settings When creating a new workspace, ensure sensible default settings are applied, such as default email content and timezone. ```javascript async function createWorkspace(name, ownerId) { const workspace = await db.workspaces.create({ name, owner_id: ownerId }) // Set default settings await updateWorkspaceSettings(workspace.id, { email_header: "You've been invited to sign a document", email_body: "Please review and sign the document at your earliest convenience.", team_email: "support@yourcompany.com", timezone: "America/New_York" }) return workspace } ``` -------------------------------- ### Get Webhook by ID Source: https://docs.firma.dev/api-reference/v01.16.00/webhooks/get-webhook This snippet shows how to retrieve a webhook's details using its unique identifier. It includes the necessary cURL command and an example of the expected JSON response. ```APIDOC ## GET /webhooks/{id} ### Description Retrieves the details of a specific webhook. ### Method GET ### Endpoint https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id} ### Parameters #### Path Parameters - **id** (string) - Required - Unique identifier for the webhook. #### Request Headers - **Authorization** (string) - Required - API key for authentication. ### Response #### Success Response (200) - **id** (string) - Unique identifier for the webhook. - **url** (string) - Webhook URL. - **description** (string | null) - Webhook description. - **events** (string[]) - Events that trigger this webhook. - **enabled** (boolean) - Whether the webhook is enabled. - **consecutive_failures** (integer) - Number of consecutive delivery failures. - **auto_disabled_at** (string | null) - Timestamp when the webhook was auto-disabled due to failures. - **created_at** (string) - Webhook creation timestamp. - **updated_at** (string) - Webhook last update timestamp. ### Response Example ```json { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "url": "", "description": "", "events": [ "" ], "enabled": true, "consecutive_failures": 123, "auto_disabled_at": "2023-11-07T05:31:56Z", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } ``` ``` -------------------------------- ### Update Workspace Request Body Example Source: https://docs.firma.dev/api-reference/v01.16.00/openapi-v01.16.00.json Example of a request body for updating a workspace, requiring the 'name' field. ```json { "name": "Enterprise Sales Workspace" } ``` -------------------------------- ### 404 Not Found Error Example Source: https://docs.firma.dev/guides/workspace-settings This response is returned if the workspace does not exist or the user lacks access. ```json { "error": "Not Found", "message": "Workspace not found" } ``` -------------------------------- ### Finalize Workspace Domain Setup Source: https://docs.firma.dev/api-reference/v01.16.00/email-domains/finalize-workspace-domain-setup Finalizes the workspace domain setup and returns DNS records required for email sending. ```APIDOC ## POST /workspace/{workspace_id}/domains/{id}/finalize ### Description Finalizes the workspace domain setup and returns DNS records required for email sending. ### Method POST ### Endpoint https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains/{id}/finalize ### Parameters #### Path Parameters - **workspace_id** (string) - Required - Workspace ID - **id** (string) - Required - Domain ID #### Request Body This endpoint does not require a request body. ### Response #### Success Response (200) - **message** (string) - Confirmation message indicating domain finalization. - **domain** (object) - Configuration details of the finalized email domain. - **id** (string) - The unique identifier for the domain. - **domain** (string) - The domain name. - **verification_status** (integer) - The verification status of the domain. - **domain_status** (integer) - The status of the domain. - **dns_records** (object[]) - An array of DNS records required for email sending. - **type** (string) - The type of DNS record (e.g., TXT, CNAME). - **name** (string) - The name or host for the DNS record. - **value** (string) - The value of the DNS record. - **ttl** (string) - The Time To Live for the DNS record. - **status** (string) - The current status of the DNS record. - **next_step** (string) - Instructions for the next action required, such as verifying DNS records. ### Request Example ```json { "message": "Domain finalized. Add the following DNS records to enable email sending.", "domain": { "id": "123e4567-e89b-12d3-a456-426614174000", "domain": "sales.acme.com", "verification_status": 2, "domain_status": 0 }, "dns_records": [ { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" }, { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" }, { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" } ], "next_step": "Add these DNS records, then call POST /workspace/{workspace_id}/domains/{id}/verify-dns to complete verification" } ``` ``` -------------------------------- ### Create Signing Request from Template (Node.js fetch) Source: https://docs.firma.dev/guides/sending-signing-request Server-side example using Node.js and the fetch API to create a signing request from a template. Requires setting the FIRMA_API_KEY environment variable. ```javascript const fetch = require('node-fetch') async function createFromTemplate(templateId) { const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ template_id: templateId, name: 'NDA - Acme Corp', recipients: [ { first_name: 'Alice', last_name: 'Johnson', email: 'alice@example.com', designation: 'Signer', order: 1 } ] }) }) if (!resp.ok) throw new Error('failed to create') const body = await resp.json() return body // contains id, document_url, recipients, etc. ``` -------------------------------- ### Partial Workspace Update Request Body Example Source: https://docs.firma.dev/api-reference/v01.16.00/openapi-v01.16.00.json Example of a request body for partially updating a workspace. Only the 'name' field can be modified via the API. ```json { "name": "Updated Workspace Name" } ``` -------------------------------- ### Configure Firma MCP Server in OpenAI Codex Source: https://docs.firma.dev/guides/mcp Add the Firma MCP server to your `config.toml` file for OpenAI Codex. Sign in with your Firma account on first use. ```toml [mcp.firma-api] type = "url" url = "https://mcp.firma.dev/mcp" ``` -------------------------------- ### Get Company Information (cURL) Source: https://docs.firma.dev/api-reference/v01.16.00/company/get-company-information Use this cURL command to make a GET request to the company information endpoint. Ensure you replace `` with your actual API key for authentication. ```bash curl --request GET \ --url https://api.firma.dev/functions/v1/signing-request-api/company \ --header 'Authorization: ' ``` -------------------------------- ### Migration Guide: v01.04.00 to v01.05.00 Source: https://docs.firma.dev/guides/api-changelog This migration guide covers the transition from API version v01.04.00 to v01.05.00. It states there are no breaking changes and that email validation warnings are now purely additive. ```APIDOC ## Migration Guide: v01.04.00 to v01.05.00 ### Changes - No breaking changes. - Email validation warnings are purely additive. ``` -------------------------------- ### Configure Firma Docs MCP Server Source: https://docs.firma.dev/guides/cursor-integration Add this configuration alongside the Data MCP server to give Cursor's AI access to Firma's documentation for generating accurate integration code. ```json { "mcpServers": { "firma-api": { "url": "https://mcp.firma.dev/mcp" }, "firma-docs": { "url": "https://docs.firma.dev/mcp" } } } ``` -------------------------------- ### Create Template using cURL Source: https://docs.firma.dev/api-reference/v01.16.00/templates/create-template Use this cURL command to create a new template. Ensure you replace `` with your actual API key and provide the document content or URL. ```bash curl --request POST \ --url https://api.firma.dev/functions/v1/signing-request-api/templates \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data \ '{ "name": "Employment Contract Template", "document": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...", "description": "Standard employment contract for new hires", "expiration_hours": 168, "settings": { "allow_editing_before_sending": false, "attach_pdf_on_finish": true, "allow_download": true, "hand_drawn_only": false, "require_otp_verification": null } }' ``` -------------------------------- ### Migration Guide: v01.00.01 to v01.00.02 Source: https://docs.firma.dev/guides/api-changelog This migration guide outlines the changes from API version v01.00.01 to v01.00.02. It notes that there are no breaking changes and introduces the availability of the Custom Fields API. ```APIDOC ## Migration Guide: v01.00.01 to v01.00.02 ### Changes - No breaking changes. - Custom Fields API is now available. ``` -------------------------------- ### Workspace Resource Structure Source: https://docs.firma.dev/guides/creating-workspaces This is an example of the JSON structure returned upon successful workspace creation. ```json { "id": "workspace_123", "name": "Acme Corp Workspace", "protected": false, "date_created": "2025-09-04T12:00:00Z", "date_changed": "2025-09-04T12:00:00Z" } ``` -------------------------------- ### Initialize React Signing Request Editor Source: https://docs.firma.dev/guides/embeddable-signing-request-editor Use this React component to load the Firma Signing Request Editor library and initialize it with your signing request details. Ensure the script is loaded before initialization and clean up the editor instance when the component unmounts. ```jsx import { useEffect, useRef, useState } from 'react'; function SigningRequestEditorComponent({ signingRequestId, jwt }) { const containerRef = useRef(null); const editorRef = useRef(null); const [isLoaded, setIsLoaded] = useState(false); // Load the Firma Signing Request Editor library useEffect(() => { const script = document.createElement('script'); script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js'; script.async = true; script.onload = () => setIsLoaded(true); document.body.appendChild(script); return () => { if (document.body.contains(script)) { document.body.removeChild(script); } }; }, []); // Initialize the editor when library and JWT are ready useEffect(() => { if (!isLoaded || !containerRef.current || !jwt) return; editorRef.current = new window.FirmaSigningRequestEditor({ container: containerRef.current, jwt: jwt, signingRequestId: signingRequestId, showCloseButton: true, // Show close button in header onSave: (data) => console.log('Saved:', data), onSend: (data) => console.log('Sent:', data), onClose: (data) => { if (data.hasUnsavedChanges) { // Prompt user to save before leaving } }, onError: (error) => console.error('Error:', error), onLoad: (signingRequest) => console.log('Loaded:', signingRequest) }); return () => { if (editorRef.current?.destroy) { editorRef.current.destroy(); } }; }, [isLoaded, jwt, signingRequestId]); return
; } export default SigningRequestEditorComponent; ``` -------------------------------- ### Get Signing Request Users (cURL) Source: https://docs.firma.dev/api-reference/v01.16.00/signing-requests/get-signing-request-users Use this cURL command to make a GET request to the API endpoint. Replace `{id}` with the actual signing request ID and `` with your API key. ```curl curl --request GET \ --url https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{id}/users \ --header 'Authorization: ' ``` -------------------------------- ### Update a Workspace using Node.js fetch Source: https://docs.firma.dev/guides/creating-workspaces Server-side example for updating a workspace using Node.js and the fetch API. Requires the FIRMA_API_KEY to be set in environment variables. ```javascript export async function updateWorkspace(workspaceId, name) { const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, { method: 'PUT', headers: { 'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ name }) }) if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`) return resp.json() } ``` -------------------------------- ### Get Email Template Placeholders (cURL) Source: https://docs.firma.dev/api-reference/v01.16.00/email-templates/get-email-template-placeholders Use this cURL command to make a GET request to retrieve all available placeholders for email templates. Ensure you replace '' with your actual API key. ```bash curl --request GET \ --url https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \ --header 'Authorization: ' ``` -------------------------------- ### Signing Request Response with Split PDF Downloads Source: https://docs.firma.dev/guides/api-changelog Example response showing new fields for downloading signed documents and certificates separately. These fields are only available if the split PDF feature is enabled for the signing request. URLs expire after 1 hour. ```json { "id": "sr-uuid", "status": "finished", "final_document_download_url": "https://storage.example.com/combined.pdf", "document_only_download_url": "https://storage.example.com/document.pdf", "document_only_download_error": null, "certificate_only_download_url": "https://storage.example.com/certificate.pdf", "certificate_only_download_error": null } ```