PUBLIC API

FactuON API Reference

Integrate FactuON's invoicing and contact management directly into your application. Create invoices and manage organizations programmatically via our REST API.

Base URLhttps://api.factuon.com/api/v1.0.1/public

Quickstart

Get your first API call running in under 5 minutes.

Generate an API Key

Go to Settings → API Keys inside your FactuON dashboard. Only privileged company users can create or revoke keys. Copy the full secret immediately — it is shown only once.

Make your first request

Send the API key in the X-API-Key header and hit the health-check endpoint to verify connectivity.

cURL

curl https://api.factuon.com/api/v1.0.1/public \
  -H "X-API-Key: fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy"

Create your first invoice

Your key must have the invoice.create scope. Pass the request body shown in the Create Invoice endpoint below.

Handle the response

Check success: true and read data.id for the newly created resource. On error, inspect error.code for details.

Authentication

Every request to a protected endpoint must carry a valid API key.

fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy

fct_ → product prefixlive_ → environmentxxxxxxxx_ → lookup prefixyyy… → random secret

🔑

X-API-Key Header

Pass the key directly in the custom header:

HTTP

X-API-Key: fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy

🛡

Authorization: Bearer

Alternatively, use the standard Authorization header:

HTTP

Authorization: Bearer fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy

⚠️

Security notice: Never expose your API key in client-side code or public repositories. The raw key is never stored by FactuON — only a secure hash and short prefix are retained.

Scopes

API keys are granted fine-grained permissions using dot-notation scopes.

Scope	Description	Required for
◆invoice.create	Allows creating new sales invoices	POST /invoice
◆organization.create	Allows creating new organizations	POST /organization

✅

A missing or insufficient scope returns HTTP 403 Forbidden with error code FORBIDDEN.

Request IDs

Every API request is assigned a unique identifier for tracing and support.

HTTP

# Optional: send your own ID
X-Request-Id: req_client_abc123

# If omitted, FactuON generates: req_<uuid>

The request ID is echoed back in the response header X-Request-Id and body under meta.requestId. Always share it with support when reporting an issue.

Response Format

All API responses follow a consistent JSON envelope.

Success

{
  "success": true,
  "message": "...",
  "data": { /* resource */ },
  "meta": {
    "requestId": "req_...",
    "requestTime": "2026-...",
    "apiVersion": "v1",
    "timestamp": "2026-..."
  }
}

Error

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "req_...",
    "apiVersion": "v1"
  }
}

Error Codes

Machine-readable codes returned in error.code

HTTP	Code	Description
400	NAME_REQUIRED	Required field name is missing
400	NAME_FIELDS_REQUIRED	firstName and lastName required when typeCode is F
400	ORG_TYPE_REQUIRED	At least one organization type flag must be true
401	INVALID_API_KEY	API key is missing, invalid, revoked, or expired
403	FORBIDDEN	API key lacks the required scope
409	NAME_CONFLICT	Organization name already exists for this company
429	RATE_LIMITED	Too many requests — back off and retry
500	INTERNAL_SERVER_ERROR	Unexpected server error — contact support with requestId

Endpoints

Health Check

Create Invoice

Create Organization