🔑 Invoicing API

Create invoices & contracts programmatically from your saved templates — for integrations, portals, and automated onboarding.

The Invoicing API lets you create invoices & contract agreements from the templates you've built in Invoicing → Subscriptions → Contract. It's the same engine the app uses — same templates, same fill-in fields, same PDF.

1. Get an API key

Keys are generated in the app and shown exactly once — store them somewhere safe (a password manager, secret store, or environment variable).

Open Invoicing → Settings → 🔑 Invoicing API
Give the key a name (e.g. "Production server") and click Generate Key
Copy the key — it starts with saflio_sk_ — you won't see it again

Only the key's hash is stored on our servers. If you lose it, revoke it and generate a new one.

2. Authenticate

Send your key as a Bearer token in the Authorization header on every request:

Authorization: Bearer saflio_sk_<your-key>

The API lives on the same host as the app's API. Use the environment that matches your account:

Development: https://api.saflio.dev
Production: https://api.saflio.app

3. List your templates

Every contract is created from a template. List what's available — Saflio defaults plus templates you've saved:

GET/v1/templates

curl -H "Authorization: Bearer $SAFLIO_API_KEY" \
  https://api.saflio.dev/v1/templates

Response — each item includes the templateKey you'll use to create a contract, plus its sections and fill-in fields:

{
  "items": [
    {
      "templateKey": "managed-network",
      "name": "Managed Network Maintenance",
      "title": "MANAGED NETWORK MAINTENANCE AGREEMENT",
      "scope": "default",
      "sections": [ { "title": "1. SCOPE OF SERVICES", "body": "…", "subsections": […] } ],
      "fillables": { "businessHours": {"label": "Business Hours", "def": "Mon–Fri, 9:00–17:00 CT"} }
    }
  ]
}

4. Create a contract

Send the template key plus the details for this specific contract. You can pass an existing clientId, or include a client object and one will be created for you.

POST/v1/contracts

curl -X POST https://api.saflio.dev/v1/contracts \
  -H "Authorization: Bearer $SAFLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateKey": "managed-network",
    "client": { "name": "Big Air", "email": "[email protected]", "company": "Big Air LLC" },
    "fee": 1500,
    "currency": "USD",
    "effectiveDate": "2026-09-01",
    "title": "Big Air Maintenance Agreement",
    "fillables": { "governingLaw": "Illinois", "businessHours": "Mon–Fri, 8:00–17:00 CT" }
  }'

Request body

Field	Type	Required	Description
`templateKey`	string	✅	The template to build from (from `/v1/templates`)
`client` or `clientId`	object / string	✅	Client details to create, or the id of an existing client you own
`fee`	number	—	Monthly fee (defaults to 0)
`currency`	string	—	`USD`, `PHP`, or `JMD` (defaults to `USD`)
`effectiveDate`	string	—	YYYY-MM-DD effective date
`title`	string	—	Agreement title (defaults to the template's title)
`fillables`	object	—	Values for the template's fill-in fields (business hours, governing law, …)
`sections`	array	—	Optional: override the template's sections entirely
`subscriptionId`	string	—	Link to an existing subscription (starts billing on signature)

Response — the new contract (status draft):

{
  "ok": true,
  "id": "abc123…",
  "status": "draft",
  "title": "Big Air Maintenance Agreement",
  "templateKey": "managed-network",
  "client": "…client id…",
  "fee": 1500,
  "currency": "USD",
  "effectiveDate": "2026-09-01"
}

Contracts are created as drafts. To send one for e-signature, open it in the app (Invoicing → Subscriptions → Contract) and use Send for Signature — the customer gets the review link + PDF, and signing creates the first invoice automatically.

5. List & fetch contracts

GET/v1/contracts

curl -H "Authorization: Bearer $SAFLIO_API_KEY" \
  https://api.saflio.dev/v1/contracts

Returns your contracts, newest first, with status, fee, and template key for each.

GET/v1/contracts/:id

curl -H "Authorization: Bearer $SAFLIO_API_KEY" \
  https://api.saflio.dev/v1/contracts/abc123

Returns the full contract, including content with all sections, sub-sections, and applied fill-in values.

6. Errors

Code	Meaning
`400`	Bad request — missing or invalid fields (e.g. no `templateKey`)
`401`	Invalid or revoked API key
`403`	Not allowed — e.g. a `clientId` that isn't yours
`404`	Template or contract not found
`500`	Something went wrong on our side — retry with backoff

Errors return JSON: {"error": "message"}

7. Managing keys

Keys are per-user — each key acts as the account that generated it.
Revoke a key anytime in Invoicing → Settings → 🔑 Invoicing API; it stops working immediately.
Generate separate keys per integration so you can revoke them independently.

The Invoicing API is under active development — more endpoints (send for signature, subscriptions, portal links) are on the way. Questions? Contact support.