---
title: "List Companies"
method: POST
path: "/v2/companies"
tags: ["Companies"]
---

# List Companies

`POST /v2/companies`

## Request

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

Get your top-connected companies ranked by network strength. Use this to discover which companies you have the best access to through your professional network. Returns a paginated list with: connection score, score_label, LinkedIn URL, and domain for each company. Supports cursor-based pagination and optional connection degree filtering.

## Request body

- ListCompaniesBody: Request body for listing top companies 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)

## Response `200`

Top companies retrieved successfully

- object
  - `data` CompanyListItem[], required: Paginated list of top companies by connection strength
    - `score` number, required: Warmth score, open-ended (higher is warmer): Excellent 10+, Very Good 7.5+, Good 4+, Okay 1+, Maybe 0.1+, below that Not enough data.
    - `score_label` string, required: Human-readable score label
    - `linkedin_url` string, required: LinkedIn company URL
    - `domain_name` string: Company domain
    - `name` string, nullable, required: Company name
    - `image_url` string, nullable, required: Company logo URL
    - `industry` string, nullable, required: Company industry
    - `employee_count` number, nullable, required: Number of employees
    - `headquarters` string, nullable, required: Company headquarters location
  - `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)