curl -X POST https://api.firma.dev/v1/workspaces
curl -X POST https://api.firma.dev/v1/signing-requests/create-and-send

## Quick Example

    # Create a workspace
    curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
      -H "Authorization: your_api_key" \
      -H "Content-Type: application/json" \
      -d '{"name": "Harbor Lettings"}'

    # Send a signing request
    curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \

---
title: "Keep signing inside your app"
description: "Embedded e-signatures for SaaS: a workspace per customer, one call to create and send, and the signing view in an iframe in your product. No per envelope enterprise pricing."
---

Your customers have to leave your app to sign documents, and you want signing to feel like part of your product without building it yourself. This page is the whole path with Firma.dev: a workspace for each customer, one API call to create and send a signing request, and the signing view in an iframe inside your app. Most teams integrate in under a day.

## What your customers get

- Signers complete the signing flow without leaving your interface.
- White-labeled: your branding on the whole signing experience. Your users never see Firma.dev.
- Each of your customers gets an isolated workspace with its own templates, signing activity, usage tracking and scoped API key. Data never crosses between workspaces.
- Optional: your customers build their own templates, or set up a signing request, inside your app with the embeddable template editor and signing request editor.

## Before you start

1. Sign up at [app.firma.dev/signup](https://app.firma.dev/signup) (free, no credit card) and get your API key from the dashboard.
2. Build with test keys. Each workspace has a live key and a test key. Requests made with the test key do not consume credits, and the signing requests they create are watermarked as test.
3. Keep every key on your server. Your backend calls Firma.dev; your frontend only ever gets a signing link or a short-lived JWT.

All requests go to `https://api.firma.dev/functions/v1/signing-request-api` with your key in the `Authorization` header.

## Step 1: Create a workspace for each customer

```bash
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Harbor Lettings"}'
```

The response includes the workspace's live `api_key` and its `test_api_key`. Store them against that customer and use them for everything that customer sends.

## Step 2: Create a template, or let your customer build one in your app

Upload a PDF and create a template with signer roles and field placements through the API or the dashboard.

To let your customers design templates inside your product, embed the template editor. Your backend asks for a JWT, your frontend opens the editor with it:

```js
// Backend: never send the API key to the browser
const r = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
  method: 'POST',
  headers: { 'Authorization': process.env.FIRMA_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ companies_workspaces_templates_id: templateId })
})
const { jwt, expires_at } = await r.json() // template tokens last 24 hours
```

```html
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<div id="firma-editor-container" style="width:100%;height:600px;"></div>
<script>
  window.FirmaTemplateEditor.init({
    container: '#firma-editor-container',
    jwt: token,            // from your backend
    templateId: templateId
  })
</script>
```

The signing request editor works the same way with a signing request token, which lasts 7 days. See [API Authentication & JWT Tokens](https://docs.firma.dev/guides/authentication).

## Step 3: Create and send the signing request

One call creates the request and sends it. If you will show the signing view inside your app, turn off the signing email so your customer's signer is not also emailed a link:

```bash
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  -H "Authorization: WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl456",
    "name": "Contract for Jane Smith",
    "recipients": [
      { "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com", "designation": "Signer", "order": 1 }
    ],
    "settings": { "send_signing_email": false }
  }'
```

With `send_signing_email: false` the request is still created, sent and billed, and its signing link is live. Only the email is skipped. If you need a draft you can still edit or cancel, use `POST /signing-requests` and send it later.

## Step 4: Show the signing view inside your app

The response lists each recipient with an `id`, and you can fetch them again any time with `GET /signing-requests/{id}/users` from your backend. Each signer's link is:

```text
https://app.firma.dev/signing/{signing_request_user_id}
```

Put it in an iframe:

```html
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=en"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

`lang` sets the signing language (15 languages) and `zoom` sets the starting zoom (`1.0` is natural size). Camera and microphone are only used when identity or video verification is on.

## Step 5: Know when it is signed

The iframe posts events to your page. Check the origin first:

```js
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.firma.dev') return
  if (event.data.type === 'signing.completed') {
    // show your own success state
  }
})
```

Events: `signing.loaded`, `signing.started`, `signing.completed`, `signing.declined`, `signing.error`. For the record of truth, use webhooks: `signing_request.recipient.signed` when a signer finishes and `signing_request.completed` when everyone has. See [Webhooks](https://docs.firma.dev/guides/webhooks).

## What it costs, with no per envelope enterprise pricing

- €0.049 per envelope, around 5 cents USD, at any volume.
- No minimums, no contracts, no per-seat fees.
- One envelope is one document sent for signature, however many signers or pages it has.
- Testing mode is free, with real documents.
- Billed in your local currency, 30+ currencies, no conversion fees.

Full details: [firma.dev/pricing](https://firma.dev/pricing).

## GDPR and where the data lives

All data is hosted in the EU (AWS Paris region, CloudFront Stockholm). Firma.dev is designed to support GDPR, eIDAS (SES and AdES), UK eIDAS, the ESIGN Act and UETA. Each customer's documents stay inside that customer's workspace.

## Questions buyers ask

**Customers have to leave our app to sign documents. What tool could keep signing in our product?**
An embedded e-signature API. With Firma.dev you create the signing request from your backend and show the signing view in an iframe in your app, so the signer never leaves (steps 3 and 4).

**Customers want document signing that feels like part of our product. What could we offer without building it ourselves?**
White-labeled signing in an iframe, plus the embeddable template editor and signing request editor, so customers set up their own documents inside your product. Firma.dev hosts the signing flow.

**We need contracts signed inside our app, GDPR compliant, without enterprise per-envelope pricing. Which e-signature API fits?**
Firma.dev is hosted in the EU and charges €0.049 per envelope with no minimums, contracts or seats, so a small team pays for what it sends.

**Can each of our customers be kept separate?**
Yes. Create one workspace per customer (step 1). Each has its own templates, activity, usage and API key.

## Next steps

- [Embeddable signing](https://docs.firma.dev/guides/embeddable-signing): every iframe option, event and error code
- [Sending a signing request](https://docs.firma.dev/guides/sending-signing-request)
- [Workspaces](https://docs.firma.dev/guides/creating-workspaces)
- [Complete Setup Guide](https://docs.firma.dev/guides/complete-setup-guide)