---
title: "List contacts"
method: GET
path: "/v1/workspaces/{workspace_id}/contacts"
tags: ["Contacts"]
---

# List contacts

`GET /v1/workspaces/{workspace_id}/contacts`

## Request

- Base URL: `https://api.blinq.me`
- URL: `https://api.blinq.me/v1/workspaces/{workspace_id}/contacts`
- Auth: HTTP bearer

Returns a paginated list of contact summaries from your personal workspace or a business workspace you own or administer. Business members receive an empty list. The workspace path segment only narrows which accessible contacts are returned; it never grants additional access.

Deleted contacts, hidden contacts, and company-directory entries are excluded.

Contacts are sorted by creation time, newest first, with the contact ID as a tie-breaker, so pages are deterministic.

Use a contact's `id` to retrieve its full details from the same workspace.

Requires the `blinq:contacts:read` scope.

## Path parameters

- `workspace_id` string, required

## Query parameters

- `cursor` string
- `search` string
- `updated_at_gte` string, date-time
- `created_at_gte` string, date-time
- `created_at_lte` string, date-time
- `limit` integer

## Response `200`

One page of contact summaries.

- object: One page of contact summaries.
  - `contacts` object[], required: Contact summaries for this page. Empty when no contacts match the request.
    - `id` string, required: The contact ID.
    - `type` 'personal' | 'business', required: Whether the contact belongs to a personal workspace (`personal`) or a team workspace (`business`).
    - `full_name` string, nullable, required: The contact's full name from the card, or `null` when no name is available.
    - `job_title` string, nullable, required: The contact's job title.
    - `company_name` string, nullable, required: The name of the contact's company.
    - `created_at` string, date-time, required: When the contact record was created, as an ISO 8601 timestamp.
    - `updated_at` string, date-time, required: When the contact record was last updated.
    - `workspace_id` string, required: The ID of the workspace containing this contact.
  - `has_more` boolean, required: Whether another page of contacts is available.
  - `next_cursor` string, nullable, required: The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`.
  - `total_count` integer, nullable, required: The total number of contacts matching the filters across all pages. Returned on the first page; `null` on subsequent pages.

## Other responses

- `400`: Bad request - Invalid query parameters or body. See `details` for each failing field
- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
- `404`: Not found - The workspace was not found or access was denied

---

[API](https://skmtc.dev/blinq/apis/blinq-public-api.md) - [All operations](https://skmtc.dev/blinq/apis/blinq-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/blinq/apis/blinq-public-api/revisions/2dedf4b14340?raw)