---
title: "List People"
method: POST
path: "/v2/people"
tags: ["People"]
---

# List People

`POST /v2/people`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/people`
- Auth: HTTP bearer

Get your network contacts ranked by connection strength. Returns a paginated list with enrichment data for each person. Supports cursor-based pagination and optional connection degree filtering.

## Request body

- ListPeopleBody: Request body for listing network people with cursor pagination
  - `cursor` string: Opaque cursor for pagination (from previous response)
  - `limit` integer: Number of results per page (default 25, max 100)
  - `connection_degrees` integer[]: Filter by connection degree (1=direct, 2=second-degree, 3=third-degree)
  - `company_domain` string: Filter by current company domain (exact match)

## Response `200`

People list retrieved successfully

- object
  - `data` PersonListItem[], required: Paginated list of network people ranked by connection strength
    - `linkedin_identifier` string, required
    - `full_name` string, required
    - `linkedin_url` string, nullable, required
    - `avatar` string, nullable, required
    - `headline` string, nullable, required
    - `location` string, nullable, required
    - `work_relevant` object, nullable, required
      - `title` string, nullable, required
      - `start_date` string, nullable, required
      - `end_date` string, nullable, required
      - `company` object, nullable, required
        - `name` string, nullable, required
        - `linkedin_url` string, nullable, required
        - `domain` string, nullable, required
        - `image_url` string, nullable, required
    - `score` number, required
    - `score_label` string, required
  - `metadata` object, required
    - `request_id` string, required
  - `pagination` PaginationInfo, required: Cursor-based pagination metadata
    - `cursor` string, nullable, required: Opaque cursor for fetching the next page (null if no more results)
    - `has_next_page` boolean, required: Whether more results are available
    - `count` integer, required: Total number of results or count of items in current page

## Other responses

- `400`: User profile incomplete
- `401`: Unauthorized - missing or invalid authentication

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)