Lists

Api ReferenceUpdated February 18, 2025

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), and export the processed results as CSV or JSON.

List lists

GET /api/v1/lists

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

Parameter	Type	Required	Description
`campaign_id`	string (UUID)	No	Filter by campaign.
`status`	string	No	Filter by `processing_status`: e.g. `processing`, `completed`, `failed`.
`limit`	number	No	Max results (default 50, max 100).
`offset`	number	No	Pagination offset (default 0).

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"
    }
  ]
}

Field	Type	Description
`lists[].id`	string (UUID)	List ID (use for status and export).
`lists[].campaign_id`	string \| null	Campaign ID.
`lists[].custom_name`	string \| null	Display name.
`lists[].processing_status`	string	`pending`, `processing`, `completed`, or `failed`.
`lists[].created_at`	string \| null	Creation time (ISO 8601).
`lists[].completed_at`	string \| null	When processing completed (if done).

Get list status

GET /api/v1/lists/:id

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

Parameter	Type	Description
`id`	string (UUID)	List ID (e.g. `list_id` from generate-batch response).

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:

Field	Type	Description
`leads_count`	number \| null	Number of leads processed.
`emails_created`	number \| null	Total emails generated.
`processed_file_path`	string \| null	Internal path; use export endpoint to download.
`completed_at`	string \| null	When processing completed (ISO 8601).

When processing_status is failed:

Field	Type	Description
`failed_at`	string \| null	When processing failed (ISO 8601).

Error responses

Status	Error	Description
401	UNAUTHORIZED	Missing or invalid API key.
404	NOT_FOUND	List not found or not in this workspace.
500	INTERNAL_ERROR	Server error.

Export list results

GET /api/v1/lists/:id/export

Returns the processed output for a completed list. Call this only after GET /api/v1/lists/:id shows processing_status: "completed".

Path parameters

Parameter	Type	Description
`id`	string (UUID)	List ID.

Query parameters

Parameter	Type	Required	Description
`format`	string	No	`csv` (default) or `json`.

Example request (CSV)

curl -X GET "https://app.machfive.io/api/v1/lists/LIST_ID/export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o results.csv

Example request (JSON)

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

Response (200 OK)

format=csv: Response body is the processed CSV (same columns as UI download). Use Content-Disposition if present for filename.
format=json: Body is a JSON object:

{
  "leads": [
    {
      "email": "jane@acme.com",
      "name": "Jane Doe",
      "company": "Acme Inc",
      "title": "VP Marketing",
      "sequence": [
        { "step": 1, "subject": "...", "body": "..." },
        { "step": 2, "subject": "...", "body": "..." }
      ]
    }
  ]
}

Error responses

Status	Error	Description
409	NOT_READY	List not yet completed; poll GET /lists/:id first. Response includes `processing_status`.
401	UNAUTHORIZED	Missing or invalid API key.
404	NOT_FOUND	List not found or not in this workspace.
500	INTERNAL_ERROR	Export failed or no processed file available.