---
title: "List the people this Hive workspace has spoken to through DM automation, sequences, broadcasts and the Inbox. Names, handles and stored values follow the workspace Inbox privacy setting, so they may come back masked. The included-contact allowance comes back with every answer."
method: POST
path: "/api/v1/tools/read_contacts"
---

# List the people this Hive workspace has spoken to through DM automation, sequences, broadcasts and the Inbox. Names, handles and stored values follow the workspace Inbox privacy setting, so they may come back masked. The included-contact allowance comes back with every answer.

`POST /api/v1/tools/read_contacts`

## Request

- Base URL: `https://hivepublish.com`
- URL: `https://hivepublish.com/api/v1/tools/read_contacts`
- Auth: HTTP bearer

## Request body

- object
  - `segmentId` string: Only people in this Hive segment.
  - `search` string: Match a name, handle or provider id.
  - `accountId` string: Only people on this connected account’s platform.
  - `email` string: Find people by exact email address. Use only one of email, phone or fieldId.
  - `phone` string: Find people by exact phone number in international format, like +14155550123.
  - `fieldId` string: Find people whose contact field has exactly fieldValue. Field ids come from read_contact_fields.
  - `fieldName` string: The field’s key or name, instead of fieldId.
  - `fieldValue` union: The value to match in fieldId.
    - string
    - number
    - boolean
  - `limit` integer: How many people to return, 1 to 100. Defaults to 25.

## Response `200`

Tool result

- ToolResult
  - `data` unknown, required
  - `meta` object, required
    - `tool` string
    - `workspaceId` string, uuid

## Other responses

- `400`: Invalid input
- `401`: Missing or invalid credential
- `403`: Missing workspace scope, role permission, or plan entitlement
- `409`: Idempotency conflict, replay, or request still in progress
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/hivepublish/apis/hive-developer-api.md) · [All operations](https://skmtc.dev/hivepublish/apis/hive-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hivepublish/apis/hive-developer-api/revisions/b440c763583e?raw)