API v1

Base URL: https://app.tracefixapp.com/api/v1/. Create a key in Settings → Integrations & API and send it as Authorization: Bearer tfx_…. Requests and responses are JSON. Dates are ISO 8601.

Create an intervention from a ticket

POST /api/v1/interventions
{
  "title": "AC unit in fault, server room",
  "description": "Customer reports alarm E5 since this morning.",
  "external_ref": "4821",
  "external_url": "https://helpdesk.example.com/tickets/4821",
  "customer": {"email": "facilities@clinic.example", "name": "St Mary's Clinic"},
  "site_id": 12,
  "equipment_serial": "SN-99812",
  "priority": "high",
  "kind": "corrective",
  "requester": {"name": "J. Lewis", "email": "j.lewis@clinic.example", "phone": "+44 20 0000 0000"}
}

The customer is matched by id, then email, then name, and created if none matches. If an open intervention already exists with the same external_ref, it is returned with status 200 instead of creating a duplicate. Otherwise the response is 201.

Field	Values
priority	low, normal, high, urgent
kind	corrective, preventive, installation, inspection, other
status (read only)	new, scheduled, in_progress, completed, cancelled

Other endpoints

GET /api/v1/interventions?external_ref=4821	Find interventions by ticket reference or status.
GET /api/v1/interventions/{id}	Read one intervention.
POST /api/v1/interventions/{id}/comments	Add a comment: {"message": "…"}.
POST /api/v1/interventions/{id}/cancel	Cancel: {"reason": "…"}.
GET/POST /api/v1/customers	Search by email or q, or create.
GET /api/v1/equipment?serial=…	Find equipment by serial number or site_id.

Intervention object

{
  "id": 142, "number": "INT-2026-00142", "title": "…", "status": "completed",
  "kind": "corrective", "priority": "high", "external_ref": "4821",
  "customer": {"id": 3, "name": "St Mary's Clinic"}, "site": {"id": 12, "name": "Building B"},
  "equipment": [{"id": 51, "name": "Rooftop unit 2", "serial_number": "SN-99812"}],
  "technicians": [{"id": 7, "name": "Sam", "email": "sam@company.example"}],
  "scheduled_start": "2026-10-12T09:00:00+02:00", "scheduled_end": null,
  "started_at": "…", "finished_at": "…",
  "work_done": "…", "follow_up": "…", "failed_checks": ["Leak check"],
  "signed": true, "signer_name": "J. Lewis",
  "report_url": "https://app.tracefixapp.com/p/r/…/", "app_url": "https://app.tracefixapp.com/app/interventions/142/"
}

Webhooks

Add an endpoint in Settings → Integrations & API. Events: intervention.created, intervention.scheduled, intervention.started, intervention.completed, intervention.cancelled. The body is {"event": "…", "created": 1760000000, "data": {intervention object}}.

Verify the X-Tracefix-Signature header, formatted t=<unix time>,v1=<hex>, where the hex value is the HMAC-SHA256 of "<t>.<raw body>" with your endpoint's signing secret:

import hmac, hashlib

def verify(secret, header, body):
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.{body}".encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Answer with any 2xx status. Failed deliveries are retried up to 6 times with growing delays (2, 4, 8, 16, 32 minutes).

Errors and limits

Errors return {"error": "…"} with status 400 (invalid input), 401 (bad key), 402 (subscription inactive) or 404 (not found).