/docs

Firma API

A small, predictable REST API for creating and tracking signature requests. Authenticate with a workspace API key.

Authentication

All requests need a bearer token. Create one in Settings → API keys.

curl https://api.firma.app/v1/documents/doc_123 \
  -H "Authorization: Bearer fma_yourKeyHere"

Create a signature request

POST /api/public/v1/documents

curl -X POST https://your-app.lovable.app/api/public/v1/documents \
  -H "Authorization: Bearer fma_yourKeyHere" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mutual NDA",
    "file_url": "https://example.com/nda.pdf",
    "recipients": [
      { "email": "alex@acme.com", "name": "Alex Chen" },
      { "email": "sam@beta.co",  "name": "Sam Park" }
    ]
  }'

Response 201:

{
  "id": "8c4f...",
  "status": "draft",
  "recipients": [
    {
      "id": "rec_1",
      "email": "alex@acme.com",
      "signing_url": "https://your-app.lovable.app/sign/abcd-1234..."
    }
  ]
}

Get a document

GET /api/public/v1/documents/:id

{
  "id": "8c4f...",
  "title": "Mutual NDA",
  "status": "completed",
  "completed_at": "2026-06-13T10:42:00Z",
  "recipients": [
    { "id": "rec_1", "email": "alex@acme.com", "status": "signed", "signed_at": "..." }
  ]
}

Embed signing

Drop the signing experience into your own app with an iframe. You receive a window.postMessage when the recipient finishes.

<iframe
  src="https://your-app.lovable.app/sign/SHARE_TOKEN"
  width="100%" height="800"
  style="border: 0; border-radius: 12px;"
></iframe>

<script>
  window.addEventListener("message", (e) => {
    if (e.data?.type === "firma:signed") {
      console.log("signed", e.data.documentId);
    }
  });
</script>

Status values