Guides/Firmify Public API — Developer Documentation

Firmify Public API — Developer Documentation

Overview

The Firmify Public API enables programmatic document generation, registry workflows, procurement doc-packs, and accounting integration. Build custom workflows and integrate Firmify into your existing systems.

Base URLs

https://firmify.bg/api/v1
https://firmify.bg/v1 # mirror (Next.js proxy)

Current version: v1. Authenticated responses include X-Api-Version: 2026-07.

Two access surfaces

Surface Auth Use for
/api/v1/* Bearer fmfy_... Programmatic document generation, billing, webhooks
/developer/* Session cookie (JWT) Developer portal UI — manage keys, billing, webhooks

Interactive docs: Scalar · Swagger · Redoc · Changelog


Quick Start

  1. Create an API key in the Developer Portal (or POST /api/v1/register for headless signup).
  2. Authenticate with Authorization: Bearer fmfy_....
  3. Generate a document — step by step:
# 1. Create an application (DRAFT status)
curl -X POST https://firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

# 2. Fill in company data
curl -X PUT https://firmify.bg/api/v1/legal-docs/{id} \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"companyName": "Acme OOD", "companyEik": "123456789"}'

# 3. Pay via Stripe checkout
curl -X POST https://firmify.bg/api/v1/legal-docs/{id}/checkout \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY"

# 4. Generate the document
curl -X POST https://firmify.bg/api/v1/legal-docs/{id}/generate \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY"

# 5. Download the PDF
curl https://firmify.bg/api/v1/legal-docs/{id}/download \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 -o document.pdf

See the step-by-step tutorial for webhooks, sandbox mode, and async jobs.


Authentication

All authenticated /api/v1/* requests require a Bearer token:

curl -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 https://firmify.bg/api/v1/pricing

API key format

Keys are prefixed with fmfy_ and shown only once at creation. Store them securely.

Scopes (permissions)

Permission Description
public_api:v1 Full public API v1 access (granted by default on new keys)
documents:generate Legacy alias for document generation (also accepted)
accounting:read Read-only accounting data for one company
accounting:multi Accounting data for all companies you can access

The accounting API lives at /accounting/api/* (not under /api/v1). Use X-Company-Id or ?companyId= to target a company.

Sandbox keys

Create a sandbox key in the Developer Portal to test integrations without real Stripe charges or document generation. Sandbox batch operations return mock IDs.


Document Generation

Lifecycle: DRAFT → READY → PAID → GENERATED.

Legal documents

Path: /api/v1/legal-docs

Types: GDPR_POLICY, TERMS_OF_SERVICE, COOKIE_POLICY, NDA, SERVICE_CONTRACT, PRIVACY_NOTICE, DATA_PROCESSING_AGREEMENT

curl -X POST https://firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

Then PUT /{id} → checkout/charge/quota → POST /{id}/generate → GET /{id}/download.

HR documents

Path: /api/v1/hr-docs

Types: EMPLOYMENT_CONTRACT, EMPLOYMENT_CONTRACT_REMOTE, NDA_EMPLOYEE, AMENDMENT_CONTRACT, TERMINATION_AGREEMENT, JOB_DESCRIPTION, PROBATION_NOTICE, LEAVE_REQUEST, PERFORMANCE_WARNING

Same CRUD + checkout + generate + download pattern as legal docs.

Other categories

Category Path
Business docs /api/v1/business-docs
VAT registration /api/v1/vat
BULSTAT /api/v1/bulstat
Bank onboarding /api/v1/bank
Amendments /api/v1/amendments
Share transfers /api/v1/share-transfers
Dissolution /api/v1/dissolution
Company registration /api/v1/company-reg/{orgId}
Procurement /api/v1/procurement

Discover all products, JSON schemas, and credit costs via GET /api/v1/catalog.


Payment

Option A: Stripe Checkout (end-user pays)

curl -X POST https://firmify.bg/api/v1/legal-docs/{id}/checkout \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY"

Redirect the user to the returned url. After payment, status becomes PAID — call /generate.

Every category has a /checkout endpoint.

Option B: Direct charge (automated)

  1. POST /api/v1/billing/setup → clientSecret for Stripe.js
  2. Collect card on your frontend
  3. POST /api/v1/{category}/{id}/charge → status PAID → call /generate

Or use monthly quota / credits — see Billing below.


Billing

Hybrid billing resolves payment in this order:

  1. API Pro — user-level subscription (€29/mo, 30 docs/month shared across keys)
  2. Key tier quota — per-key monthly doc limit (free/starter/pro/enterprise)
  3. Credit wallet — pre-paid credits (category-weighted costs)
  4. Stripe Checkout / charge — per-document payment
curl -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 https://firmify.bg/api/v1/billing

When payment is required and no quota/credits remain, generation returns 402 with checkoutUrl or chargeUrl.

Credit costs (examples): legal-docs 5, hr-docs 4, vat 15, company-reg 40 — full table in GET /catalog or GET /pricing.

Manage billing in the portal at /developer/billing (session) or via /api/v1/billing/* (Bearer).


Rate Limits

Per-key limits depend on your plan tier:

Plan Requests/min Docs/month Price
free 10 10 €0
starter 30 100 €19/mo
pro 100 500 €49/mo
enterprise 300 10,000 €99/mo

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1688301540

When exceeded: 429 with { "error": "...", "limit": 100, "window": "1m", "plan": "pro" }.

POST /api/v1/register is additionally limited to 5 requests per 15 minutes per IP.


Error Handling

Errors return flat JSON:

{
 "error": "Validation failed",
 "details": [{ "path": ["companyName"], "message": "Required" }]
}
Status Meaning
400 Validation error — check details
401 Missing or invalid API key
402 Payment required — use checkoutUrl / chargeUrl in response
403 Insufficient permissions or email not verified
404 Resource not found
429 Rate limit exceeded
500 Internal server error

Send X-Locale: en for English error messages (default is Bulgarian).


Idempotency

Send Idempotency-Key on mutating /api/v1/* requests to safely retry without duplicate side effects:

curl -X POST https://firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 -H "Idempotency-Key: order-2026-07-14-001" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

The server caches the response for 24 hours per key + method + path. Replays return the original status and body.


Webhooks

Register an HTTPS endpoint to receive real-time events:

curl -X POST https://firmify.bg/api/v1/webhooks \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"url": "https://myapp.com/webhook", "events": ["doc.generated", "payment.completed"]}'

Events: payment.completed, doc.generated, doc.failed, job.completed, job.failed

Verification: HMAC-SHA256 of the body in X-Firmify-Signature; event type in X-Firmify-Event.

Management: GET /api/v1/webhooks, DELETE /api/v1/webhooks/{id}

Alternatively, manage webhooks via session at /developer/webhooks when logged into the portal.


Async Jobs

Quick generate (legal/hr/business in one call):

curl -X POST https://firmify.bg/api/v1/docs/generate \
 -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY", "params": {"companyName": "Acme OOD", "companyEik": "123456789"}}'

Returns a job ID — poll status:

curl -H "Authorization: Bearer fmfy_YOUR_API_KEY" \
 https://firmify.bg/api/v1/jobs/{jobId}

Use the full per-category CRUD flow when you need checkout, partial updates, or registry-specific steps. Heavy flows (company registration ZIP, procurement doc-packs) always return a job ID.


Utility Endpoints

Method Path Purpose
GET /api/v1/pricing Plans, API Pro, credit packs (no auth)
GET /api/v1/catalog Products, schemas, credit costs (no auth)
POST /api/v1/register Headless signup + first API key
POST /api/v1/estimate Price estimate before placing an order
POST /api/v1/batch Batch document operations
GET /api/v1/analytics Usage analytics for your account

Registry Workflows

Amendments, share transfers, and dissolution support the full registry pipeline:

  1. Create order → fill data
  2. POST /{id}/validate — pre-flight validation
  3. Pay (checkout/charge/quota/credits)
  4. POST /{id}/generate
  5. GET /{id}/download/{docType} or GET /{id}/zip
  6. POST /{id}/upload-signed-pdf — upload signed PDF
  7. POST /{id}/mark-submitted — mark as submitted to the register

Company registration continuation uses org-scoped paths: /api/v1/company-reg/{orgId}/generate, /zip, /upload-signed.

Encrypted creates (RSA-4096 OAEP-SHA512 + AES-256-GCM) are under /api/v1/company-registration. Omitting an optional field keeps the previous behaviour.

Call Path
EOOD POST /company-registration/eood
OOD POST /company-registration/ood
Euro conversion POST /company-registration/euro-conversion
Amendment POST /company-registration/amendments
OOD euro + capital increase, one meeting POST /company-registration/amendments/batch
  • articlesVariant on EOOD and OOD: "short" (default) or "long". Document kinds and ZIP file names stay the same.
  • shareNominalCents on euro conversion, and on the batch euro object: integer euro cents, minimum 2. Omit it for the one-cent G1 conversion. Sending 1 is a validation error. A preserved-share-count result outside the 5% band is HTTP 422 (BLOCKED).
  • newData.unanimityOptIn on amendments: optional boolean. It is applied only with the long articles variant and ignored for "short".
  • A stand-alone euro conversion may return euroDeadlineWarning after 31 December 2028. Before that date the field is omitted. The call is not refused.

The batch creates two linked applications. The EURO row is generated in the same call and costs 0 credits. The CAPITAL row costs 20 credits and stays PAID with evidenceRequired: true until POST /api/v1/amendments/{capitalAppId}/contribution-evidence, then POST /api/v1/amendments/{capitalAppId}/generate (no second charge). EOOD is HTTP 422.

Signed ZIP

POST /api/v1/company-reg/{orgId}/upload-signed takes multipart field zip and moves the organization to SIGNED.

  • Every expected file must be in the archive. A file that is not a PDF is 400 with INVALID_SIGNED_ZIP / NOT_A_PDF.
  • MANAGER_SPECIMEN is the notarially certified signature sample, scanned to PDF. The API checks the %PDF header only. It does not require a qualified electronic signature, does not compare the text with the generated blank, and does not send the file to QSVS. Certification stays with you.
  • The A4 filing checklist is a helper and does not need a signature.
  • Every other expected PDF must contain a digital signature (/ByteRange or /Type /Sig) and its text must match the generated original. When the server has QSVS configured, those other PDFs are validated cryptographically. The specimen is not.
  • The same specimen rule applies to a single-file upload of MANAGER_SPECIMEN.

Procurement

The procurement API covers TED opportunities, saved cases, tasks, and doc-pack generation:

  • Profile: GET/PUT /api/v1/procurement/profile
  • Opportunities: list, detail, refresh, save, hide
  • Cases: CRUD, tasks, notes, AI checklist
  • Doc-packs: create, checkout, generate, download

See OpenAPI for the full endpoint list — procurement is the largest surface area.


Accounting API

Separate from public v1 — uses the same API keys with accounting:read or accounting:multi:

GET https://firmify.bg/accounting/api/companies
GET https://firmify.bg/accounting/api/companies/{id}/invoices

Requires X-Company-Id header (or ?companyId=). Rate limit: 100 req/min per key + company pair.


Sandbox Mode

Sandbox keys (created in the Developer Portal with the sandbox checkbox):

  • Skip real Stripe charges and document generation
  • Return mock responses for batch and quick-generate flows
  • Ideal for CI/CD and integration testing

Use a regular key with the free tier (10 docs/month) for end-to-end testing with real documents.


Code Examples

Node.js

const API_BASE = "https://firmify.bg/api/v1";
const API_KEY = process.env.FIRMIFY_API_KEY;

async function generateGdprPolicy(company) {
 const headers = {
 Authorization: `Bearer ${API_KEY}`,
 "Content-Type": "application/json",
 "Idempotency-Key": `gdpr-${company.eik}-${Date.now()}`,
 };

 const createRes = await fetch(`${API_BASE}/legal-docs`, {
 method: "POST",
 headers,
 body: JSON.stringify({ docType: "GDPR_POLICY" }),
 });
 if (!createRes.ok) {
 const err = await createRes.json();
 throw new Error(err.error);
 }
 const { id } = await createRes.json();

 const updateRes = await fetch(`${API_BASE}/legal-docs/${id}`, {
 method: "PUT",
 headers: { ...headers, "Idempotency-Key": undefined },
 body: JSON.stringify({ companyName: company.name, companyEik: company.eik }),
 });
 if (!updateRes.ok) throw new Error((await updateRes.json()).error);

 const genRes = await fetch(`${API_BASE}/legal-docs/${id}/generate`, {
 method: "POST",
 headers: { Authorization: headers.Authorization },
 });
 if (!genRes.ok) throw new Error((await genRes.json()).error);

 return { id, downloadUrl: `${API_BASE}/legal-docs/${id}/download` };
}

Python

import os
import requests

API_BASE = "https://firmify.bg/api/v1"
headers = {"Authorization": f"Bearer {os.environ['FIRMIFY_API_KEY']}"}

create = requests.post(
 f"{API_BASE}/legal-docs",
 json={"docType": "GDPR_POLICY"},
 headers={**headers, "Idempotency-Key": "order-001"},
)
create.raise_for_status()
doc_id = create.json()["id"]

update = requests.put(
 f"{API_BASE}/legal-docs/{doc_id}",
 json={"companyName": "Acme OOD", "companyEik": "123456789"},
 headers=headers,
)
update.raise_for_status()

gen = requests.post(f"{API_BASE}/legal-docs/{doc_id}/generate", headers=headers)
gen.raise_for_status()

API Reference

Resource URL
Scalar (interactive) https://firmify.bg/api/v1/docs
Swagger UI https://firmify.bg/api/v1/docs/swagger
Redoc https://firmify.bg/api/v1/docs/redoc
OpenAPI JSON https://firmify.bg/api/v1/openapi.json
OpenAPI YAML https://firmify.bg/api/v1/openapi.yaml
Postman collection https://firmify.bg/api/v1/postman.json
Developer portal https://firmify.bg/en/developer
Tutorial guide /en/guide/public-api-guide
Changelog /en/guide/api-changelog
Support api@firmify.bg

Generate a typed client:

npx @openapitools/openapi-generator-cli generate \
 -i https://firmify.bg/api/v1/openapi.json \
 -g typescript-axios \
 -o ./firmify-client

All guides

Was this article helpful?