Lists

Create persistent lists of companies, trigger bulk analysis, then query accounts with score filtering and sorting.

POST /v1/lists

Create a named list. Set analyze: true to immediately start researching (1 credit each).

Request body

{
  "name": "Q1 Targets",
  "company_urls": ["https://example.com", "https://acme.com"],
  "analyze": true
}

Response 201

{
  "object": "account_list",
  "list_id": 5,
  "name": "Q1 Targets",
  "status": "analyzing",
  "total_accounts": 2
}
POST /v1/lists/{list_id}/analyze

Trigger analysis on pending accounts. Use this if you created a list without analyze: true.

Response 202

{
  "object": "account_list",
  "list_id": 5,
  "status": "analyzing",
  "pending_accounts": 2
}
GET /v1/lists/{list_id}

Get list details and accounts with optional filtering and sorting.

Query parameters

ParameterDescription
min_pain_scoreFilter: pain score ≥ value
min_composite_scoreFilter: composite score ≥ value
sort_bypain_score, composite_score, fit_score, timing_score, company_name
orderasc or desc (default: desc)
limitMax accounts (1-500, default 100)
starting_afterCursor: account ID from previous page

Response

{
  "object": "account_list",
  "list_id": 5,
  "name": "Q1 Targets",
  "status": "completed",
  "total_accounts": 50,
  "analyzed_accounts": 48,
  "failed_accounts": 2,
  "accounts": {
    "object": "list",
    "data": [
      {
        "id": 1,
        "company_url": "https://example.com",
        "company_name": "Example Inc",
        "status": "completed",
        "document_id": 15,
        "pain_score": 85,
        "fit_score": 72,
        "timing_score": 80,
        "composite_score": 78,
        "analyzed_at": "2026-01-28T12:01:30"
      }
    ],
    "has_more": true
  }
}
GET /v1/lists

List your recent lists (summaries only). Supports cursor pagination.

Response

{
  "object": "list",
  "data": [
    {
      "object": "account_list",
      "list_id": 5,
      "name": "Q1 Targets",
      "status": "completed",
      "total_accounts": 50,
      "created_at": "2026-01-28T12:00:00"
    }
  ],
  "has_more": false
}
POST /v1/lists/{list_id}/push Deprecated

This endpoint always returns 410 Gone. The Instantly push integration has been deprecated.

Response 410

{
  "error": {
    "code": "provider_deprecated",
    "message": "Instantly push has been deprecated."
  }
}
DELETE /v1/lists/{list_id}

Delete a list and all its accounts. Returns 204 on success.