---
title: "Get Outreach Candidates"
method: GET
path: "/api/outreach/candidates"
tags: ["outreach", "outreach"]
---

# Get Outreach Candidates

`GET /api/outreach/candidates`

## Request

- Base URL: `https://api.dialogbrain.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.dialogbrain.com/api/outreach/candidates`
- Auth: none declared

Unified outreach candidates endpoint.
Use type=dm for DM contacts, type=group for groups.
Default type=dm for backward compatibility.

## Query parameters

- `type` 'dm' | 'group'
- `segments` string, nullable: Comma-separated: strong,medium,low,noise
- `channels` string, nullable: Comma-separated: telegram,whatsapp,email
- `limit` integer
- `offset` integer
- `include_excluded` boolean
- `states` string, nullable: Comma-separated: new,follow_up,active,warm,cooling,dormant,low
- `min_signal_score` number
- `max_days_since_contact` integer, nullable
- `exclude_recent_days` integer, nullable
- `engagement_states` string, nullable
- `member_count_min` integer, nullable
- `member_count_max` integer, nullable
- `min_overall_score` integer, nullable
- `has_recent_activity` boolean, nullable
- `hide_contacted` boolean, nullable
- `show_ignored` boolean, nullable
- `folder_ids` string, nullable: Comma-separated inbox folder IDs
- `tag_ids` string, nullable: Comma-separated AI tag IDs
- `search` string, nullable: Search by contact name or phone number

## Response `200`

Successful Response

- CandidatesResponse: List response for DM or group outreach candidates.
  - `items` OutreachItem[], required
    - `type` 'dm' | 'group', required
    - `id` integer, required
    - `name` string, required
    - `avatar_url` string, nullable
    - `thread_id` integer, required
    - `thread_channel` string, nullable
    - `thread_channel_ref` string, nullable
    - `segment` string, nullable
    - `state` string, nullable
    - `score` number, nullable
    - `days_since_contact` integer, nullable
    - `key_topics` string[], nullable
    - `relationship_type` string, nullable
    - `last_interaction_at` string, nullable
    - `member_count` integer, nullable
    - `username` string, nullable
    - `messages_last_7d` integer, nullable
    - `last_message_at` string, nullable
    - `overall_score` number, nullable
    - `active_member_count` integer, nullable
  - `total` integer, required
  - `type` 'dm' | 'group', required
  - `filters` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/77bef09a9209?raw)