Lists

A list represents one batch of leads (from a single generate or generate-batch request). You can list lists, get a list's status (to poll until completed), rename, delete, and reprocess. To download processed results, see Export.

List lists

GET /api/v1/lists · scope lists:read

Returns lead lists in the API key's workspace, with optional filters.

Headers

Authorization: Bearer <API_KEY> or X-API-Key: <API_KEY>.

Query parameters

Example request

curl -X GET "https://app.machfive.io/api/v1/lists?status=completed&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "lists": [
    {
      "id": "uuid",
      "campaign_id": "uuid",
      "custom_name": "API Batch Q1",
      "processing_status": "completed",
      "created_at": "2025-01-15T12:00:00.000Z",
      "completed_at": "2025-01-15T12:15:00.000Z"
    }
  ],
  "has_more": false,
  "total": 1
}

Get list status

GET /api/v1/lists/:id · scope lists:read

Returns status and metadata for one list. Use this to poll until processing_status is completed or failed after a generate-batch request.

Path parameters

Example request

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

Response (200 OK)

Base fields (always present):

{
  "id": "uuid",
  "campaign_id": "uuid",
  "custom_name": "API Batch Q1",
  "processing_status": "completed",
  "created_at": "2025-01-15T12:00:00.000Z",
  "updated_at": "2025-01-15T12:15:00.000Z"
}

When processing_status is completed:

When processing_status is failed:

Error responses

Rename a list

PATCH /api/v1/lists/:id · scope lists:write

Renames a list (updates its custom_name).

Path parameters

Request body

Example request

curl -X PATCH "https://app.machfive.io/api/v1/lists/LIST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_name": "Q1 Enterprise Outreach" }'

Response (200 OK)

{
  "id": "uuid",
  "campaign_id": "uuid",
  "custom_name": "Q1 Enterprise Outreach",
  "processing_status": "completed",
  "created_at": "2025-01-15T12:00:00.000Z",
  "updated_at": "2025-01-16T09:00:00.000Z"
}

Error responses

Delete a list

DELETE /api/v1/lists/:id · scope lists:write

Permanently deletes a list and cleans up its uploaded/processed CSV files in storage. A list that is currently processing (processing or in_progress) cannot be deleted (409 CONFLICT); wait until it completes or fails.

Deleting a list also removes its processing batches. Credit usage history is retained for auditing.

Path parameters

Example request

curl -X DELETE "https://app.machfive.io/api/v1/lists/LIST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{ "id": "uuid", "deleted": true }

Error responses

Reprocess a list

POST /api/v1/lists/:id · scope lists:write

Re-triggers processing for a list's pending batches via the same pipeline used in-app. Use this to resume a list that stalled with some batches still pending.

Pending-only: Only batches still in the pending state are re-triggered. Batches that already failed or completed are not reset by this endpoint. This is an async operation — poll GET /api/v1/lists/:id to follow progress.

Path parameters

Example request

curl -X POST "https://app.machfive.io/api/v1/lists/LIST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (202 Accepted)

{
  "list_id": "uuid",
  "status": "processing",
  "pending_batches": 3,
  "batches_total": 10,
  "message": "Triggered reprocessing for 3 pending batch(es)."
}

Error responses