API Reference

Programmatic control of Mach Five Magnet flows and data.

JavaScript API

Once the Mach Five Magnet snippet is installed, a global MachFiveMagnet object is available on the page.

Initialize

The snippet auto-initializes on load. To manually control initialization:

<script src="https://cdn.machfivemagnet.com/magnet.js"
        data-flow-id="your-flow-id"
        data-auto-init="false"
        async></script>

// Manual initialization
MachFiveMagnet.init({
  flowId: 'your-flow-id',
  format: 'chat-bubble',
  trigger: 'page-load'
});

Show / Hide

// Programmatically show the flow
MachFiveMagnet.show();

// Hide the flow
MachFiveMagnet.hide();

// Toggle visibility
MachFiveMagnet.toggle();

Events

Listen for flow lifecycle events:

MachFiveMagnet.on('flow:start', function (data) {
  console.log('Flow started', data.flowId);
});

MachFiveMagnet.on('flow:complete', function (data) {
  console.log('Flow completed', data.flowId, data.responses);
});

MachFiveMagnet.on('response:submit', function (data) {
  console.log('Response submitted', data.nodeId, data.value);
});

Available Events

Event	Payload	Description
`flow:start`	`{ flowId }`	Visitor began the flow
`flow:complete`	`{ flowId, responses }`	Visitor reached the final node
`flow:dismiss`	`{ flowId, lastNodeId }`	Visitor closed the flow
`response:submit`	`{ flowId, nodeId, value }`	A single response was submitted

REST API

Warning

The REST API is available on Pro plans and above. Starter and Free plans can use the JavaScript API and dashboard.

Authentication

All API requests require a Bearer token:

curl -H "Authorization: Bearer your-api-key" \
     https://api.machfivemagnet.com/v1/flows

Endpoints

List Flows

GET /v1/flows

Returns all flows in your account:

{
  "flows": [
    {
      "id": "flow_abc123",
      "name": "Lead Qualification",
      "status": "live",
      "created_at": "2026-01-15T10:30:00Z",
      "stats": {
        "views": 12450,
        "starts": 3200,
        "completions": 1856
      }
    }
  ]
}

Get Flow Responses

GET /v1/flows/:flow_id/responses

Returns captured responses for a flow:

{
  "responses": [
    {
      "id": "resp_xyz789",
      "flow_id": "flow_abc123",
      "completed": true,
      "created_at": "2026-03-20T14:22:00Z",
      "data": {
        "email": "visitor@example.com",
        "interest": "pricing",
        "company_size": "11-50"
      }
    }
  ]
}

Export Responses

GET /v1/flows/:flow_id/responses/export?format=csv

Tip

Use the format query parameter to choose between json (default) and csv exports.

Webhooks

Configure webhooks in the dashboard to receive real-time notifications when events occur:

{
  "event": "response:complete",
  "flow_id": "flow_abc123",
  "response_id": "resp_xyz789",
  "data": {
    "email": "visitor@example.com",
    "interest": "pricing"
  },
  "timestamp": "2026-03-20T14:22:00Z"
}

Webhook payloads are signed with HMAC-SHA256 for verification. Check the X-Magnet-Signature header against your webhook secret.