Build on Furnace Card Studio

All requests go to https://your-furnace-domain/api/v1 over HTTPS and exchange JSON. Field names are snake_case, timestamps are ISO 8601 in UTC, money is in minor units (value_cents) with an ISO currency code.

curl https://your-furnace-domain/api/v1/me \
  -H "Authorization: Bearer fcs_your_key"

The machine-readable contract is the OpenAPI 3.1 document, generated from the same schemas that validate requests, so it can’t drift from behavior. Import it into Postman, Insomnia or a client generator.

Workspace admins create keys in Settings → API keys & webhooks. A key is shown once, stored only as a hash, belongs to exactly one workspace, and can be given an expiry and revoked at any time. Send it as a bearer token:

Authorization: Bearer fcs_…

Give each key only the scopes it needs. A request outside the key's scopes fails with 403 insufficient_scope.

The API is available from the Individual plan. A key whose workspace no longer includes API access receives 402 plan_limit.

Errors always use the same envelope and a stable machine-readable code. Include request_id (also the Request-Id header) when contacting support.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body.",
    "field_errors": { "email": "Invalid email address" },
    "request_id": "req_4f9a0c…"
  }
}

List endpoints return newest first in pages of limit (1–100, default 25). Pass the returned next_cursor as cursor to get the next page; it's null on the last page. Cursors are stable while records are created concurrently.

curl "https://your-furnace-domain/api/v1/contacts?limit=50&lifecycle_stage=qualified&cursor=eyJ0Ijoi…" \
  -H "Authorization: Bearer fcs_…"

{
  "object": "list",
  "data": [ { "object": "contact", "id": "…", "full_name": "Jordan Lee", … } ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wOVQxNDozMDowMC4xMjM0NTZaIiwiaWQiOiI…"
}

Every POST accepts an Idempotency-Key header (any unique string up to 255 characters, e.g. a UUID). Retrying with the same key and body within 24 hours returns the original response, including errors, with Idempotent-Replayed: true, and never creates a second record. Reusing a key with a different body is rejected with 422 idempotency_key_reused.

curl -X POST https://your-furnace-domain/api/v1/contacts \
  -H "Authorization: Bearer fcs_…" \
  -H "Idempotency-Key: 6b1f2c3e-badge-scan-0042" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Jordan Lee","email":"jordan@northwind.example","company_name":"Northwind"}'

Limits apply per key, per minute. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds); a 429 also includes Retry-After.

Required scopes are shown next to each endpoint. Full request and response schemas are in the OpenAPI document.

Add endpoints in Integrations → Webhooks (or POST /api/v1/webhooks) and choose events, or * for all. Each delivery is a POST with a JSON envelope; records referenced by the event are expanded with the same shape the REST API returns.

Content-Type: application/json
User-Agent: FurnaceCardStudio/1.0
Furnace-Event-Id: 1f0c6d1e-…            (same on every retry)
Furnace-Event-Type: contact.created
Furnace-Delivery-Id: 7a2b…
Furnace-Attempt: 1
Furnace-Signature: t=1760020200,v1=5d41402abc4b2a76b9719d911017c592…

{
  "id": "1f0c6d1e-…",
  "type": "contact.created",
  "created_at": "2026-10-09T14:30:00.000Z",
  "organization_id": "…",
  "data": {
    "contact_id": "…",
    "source": "exchange_form",
    "contact": { "object": "contact", "id": "…", "full_name": "Jordan Lee", "email": "jordan@northwind.example", … }
  }
}

• Acknowledge fast: return any 2xx within 10 seconds, then process asynchronously. Redirects aren't followed.
• Retries: failed attempts are retried with exponential backoff (about 30s, 1m, 2m, 4m, 8m, 16m, 32m; 8 attempts over roughly an hour).
• At-least-once: de-duplicate on the event id; deliveries can arrive out of order.
• Auto-disable: an endpoint is disabled after 10 consecutive deliveries fail every retry; admins are notified. Re-enable it and use Redeliver from the delivery log to replay missed events.
• Test & inspect: “Send test event” delivers a signed webhook.test; the log keeps request headers, body and response for 30 days.

Furnace-Signature is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw request body> keyed with your endpoint's signing secret (the full whsec_… string). Compute it over the exact bytes received, compare in constant time, and reject timestamps older than five minutes to stop replays.

import crypto from "node:crypto";

export function verifyFurnaceSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

// Express: verify against the raw bytes, before any JSON parsing.
app.post("/webhooks/furnace", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  if (!verifyFurnaceSignature(body, req.get("Furnace-Signature") ?? "", process.env.FURNACE_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(body);
  // De-duplicate on event.id (also sent as Furnace-Event-Id), queue the work, answer fast.
  res.sendStatus(200);
});

import hashlib, hmac, os, time
from flask import Flask, abort, request

def verify_furnace_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

app = Flask(__name__)

@app.post("/webhooks/furnace")
def furnace_webhook():
    if not verify_furnace_signature(request.get_data(), request.headers.get("Furnace-Signature", ""), os.environ["FURNACE_WEBHOOK_SECRET"]):
        abort(400)
    event = request.get_json()  # de-duplicate on event["id"]
    return "", 200

Rotating the secret takes effect immediately; deploy the new secret to your receiver before rotating, or accept both during the switch.

Automation platforms subscribe and unsubscribe programmatically. Create a key with the webhooks:write scope (choose the platform under “Used by” so the integration shows as connected). Subscriptions are signed and retried exactly like webhooks, and stop when the key is revoked.

POST https://your-furnace-domain/api/v1/hooks
{ "target_url": "https://hooks.zapier.com/hooks/catch/123/abc/", "event": "contact.created" }

201 Created
{ "object": "hook", "id": "8d3e…", "event": "contact.created", "target_url": "https://hooks.zapier.com/…", "active": true, "secret": "whsec_…" }

DELETE https://your-furnace-domain/api/v1/hooks/8d3e…            → 200 (also when already removed)
GET    https://your-furnace-domain/api/v1/hooks/samples/contact.created   → recent real payloads for building a Zap

There are no listings in the Zapier, Make or n8n directories yet. Their generic webhook and HTTP modules work today with these endpoints; see each platform's page under Integrations for step-by-step setup.

Every event below can be delivered to webhooks and REST hooks. data always includes the ids of the records involved.

Connectors that use OAuth need an app registered with the provider. Until both variables are set, the connector shows Requires configuration with the exact names. Register these redirect URIs:

• SALESFORCE_LOGIN_URL (optional): use https://test.salesforce.com for sandboxes.
• Square: SQUARE_ENVIRONMENT=sandbox uses Square’s sandbox. Register one app-level webhook at https://your-furnace-domain/api/webhooks/square (invoice and payment.updated events) and set SQUARE_WEBHOOK_SIGNATURE_KEY; SQUARE_WEBHOOK_URL overrides the signed URL behind proxies.
• WEBHOOK_AUTO_DISABLE_AFTER (optional, default 10): consecutive failed deliveries before an endpoint is disabled.
• Provider webhooks (Calendly, Mailchimp, Shopify) are only registered automatically when APP_URL is a public HTTPS URL.
• API-key connectors (Pipedrive, Mailchimp, Brevo, Stripe, Shopify, Calendly, Slack, Teams) need no operator setup; each workspace pastes its own credentials, which are encrypted with APP_SECRET.