Getting Started

Follow these steps to start using the MachFive API.

1. Create an API key

API keys are created in the MachFive app and are scoped to a workspace.

1. Log in at app.machfive.io.
2. Open Settings (or Workspace → API Keys).
3. Go to the API Keys section.
4. Click Create API Key.
5. Enter a name (e.g. "Production" or "OpenClaw") and create the key.
6. Copy the key and store it securely. It is shown only once and cannot be retrieved later.

Key format: mf_live_ followed by 32 characters (e.g. mf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx).

2. Base URL and headers

• Base URL: https://app.machfive.io
• Auth: Send your API key on every request (see Authorization).

Example:

curl -X GET "https://app.machfive.io/api/v1/campaigns" \
  -H "Authorization: Bearer mf_live_YOUR_KEY_HERE"

3. First request: list campaigns

To see which campaigns you can use for generation:

curl -X GET "https://app.machfive.io/api/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "campaigns": [
    { "id": "uuid", "name": "Q1 Outbound", "created_at": "2025-01-15T12:00:00.000Z" }
  ]
}

Use a campaign id in the generate or generate-batch endpoints.

4. Generate for one lead (sync)

To generate a sequence for a single lead (takes 3–10 minutes):

curl -X POST "https://app.machfive.io/api/v1/campaigns/CAMPAIGN_ID/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead": {
      "name": "Jane Doe",
      "title": "VP Marketing",
      "company": "Acme Inc",
      "email": "jane@acme.com"
    }
  }'

Important: Use a timeout of at least 300 seconds (5 minutes) or 600 seconds (10 minutes). Shorter timeouts will cut off the response.

5. Generate for multiple leads (async)

To process many leads without waiting:

1. POST to POST /api/v1/campaigns/:id/generate-batch with { "leads": [ {...}, ... ], "options": { ... } }.
2. You get 202 Accepted with list_id.
3. Poll GET /api/v1/lists/:list_id until processing_status is completed (or failed).
4. Export results with GET /api/v1/lists/:list_id/export?format=csv or ?format=json.

See Generate Batch and Lists for details.