Village API

https://docs.village.do
Admin
Village API provides a fast, cost-effective, and strategic way to implement relationship...
Tokens:64,752
Snippets:241
Trust Score:7.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Get Person Paths - JSON Response Example

Source: https://docs.village.do/api-reference/people

Sample JSON response from the Get Person Paths endpoint containing target profile, introduction paths with scoring, starter profiles, and introducer details including work history and LinkedIn connection metadata.

```json
{
  "target": {
    "profile": {
      "village_id": "vill_999abc",
      "first_name": "Gavin",
      "last_name": "Belson",
      "linkedin_url": "https://linkedin.com/in/gavin-belson",
      "headline": "CEO at Hooli"
    }
  },
  "count": 1,
  "summary": {
    "score": 8,
    "score_label": "Excellent",
    "description": "🟢 Erlich Bachman → Peter Gregory → Gavin Belson (CEO)"
  },
  "paths": [
    {
      "type": "intro",
      "summary": {
        "score": 8.5,
        "score_label": "Excellent",
        "description": "🟢 Erlich can intro via Peter Gregory (Lead investor)"
      },
      "starters": [
        {
          "profile": {
            "village_id": "vill_789xyz",
            "first_name": "Erlich",
            "last_name": "Bachman",
            "linkedin_url": "https://linkedin.com/in/erlich-bachman",
            "headline": "Founder at Aviato"
          },
          "score": 8.5,
          "score_label": "Excellent",
          "score_description": "🟢 Erlich can make a strong introduction",
          "score_meta": [
            {
              "title": "Work",
              "description": "Both worked at Pied Piper (12 employees) Jan '14 - Present"
            },
            {
              "title": "LinkedIn",
              "description": "Both are connected on LinkedIn"
            }
          ]
        }
      ],
      "introducer": {
        "profile": {
          "village_id": "vill_456def",
          "first_name": "Peter",
          "last_name": "Gregory",
          "linkedin_url": "https://linkedin.com/in/peter-gregory",
          "headline": "Founder at Raviga Capital"
        },
        "score": 8.5,
        "score_label": "Excellent",
        "score_meta": [
          {
            "title": "Work",
            "description": "Both worked at Raviga Capital (50 employees) Jan '13 - Dec '15"
          },
          {
            "title": "LinkedIn",
            "description": "Both are connected on LinkedIn"
          }
        ]
      }
    }
  ]
}
```

--------------------------------

### GET /websites/village_do

Source: https://docs.village.do/api-reference/companies

Retrieves detailed information about a company and its target people, including introduction paths.

```APIDOC
## GET /websites/village_do

### Description
This endpoint retrieves comprehensive data for a given company, including a summary score, target individuals within the company, and detailed paths for potential introductions to these individuals. It also provides information about the nature of the connection and previous interactions.

### Method
GET

### Endpoint
/websites/village_do

### Parameters
#### Header Parameters
- **user-identifier** (string) - Required - A unique identifier for the user.
- **x-access-token** (string) - Required - A JWT token obtained from the /users/authorization endpoint.

### Request Example
```bash
curl -X GET \
  'https://api.example.com/websites/village_do' \
  --header 'user-identifier: <user-identifier>' \
  --header 'x-access-token: <api-key>'
```

### Response
#### Success Response (200)
- **company** (object) - Information about the company.
  - **name** (string) - The name of the company.
  - **linkedin_url** (string) - The LinkedIn profile URL of the company.
- **summary** (object) - A summary of the company's score.
  - **score** (number) - The overall score for the company.
  - **score_label** (string) - A label describing the score (e.g., "Excellent").
- **target_people** (array) - A list of target individuals within the company.
  - **target** (object) - Information about the target individual.
    - **profile** (object) - The profile details of the target individual.
      - **village_id** (string) - The unique ID of the individual within the Village platform.
      - **first_name** (string) - The first name of the individual.
      - **last_name** (string) - The last name of the individual.
      - **linkedin_url** (string) - The LinkedIn profile URL of the individual.
      - **headline** (string) - The current job title or headline of the individual.
  - **count** (integer) - The number of times this target has been encountered.
  - **summary** (object) - A summary of the target person's score and connection path.
    - **score** (number) - The score for this specific target person.
    - **score_label** (string) - A label describing the target person's score.
    - **description** (string) - A textual description of the connection path.
  - **paths** (array) - A list of possible introduction paths to the target person.
    - **type** (string) - The type of introduction path (e.g., "intro", "direct").
    - **starters** (array) - Individuals who can initiate an introduction.
      - **profile** (object) - Profile details of the starter.
      - **score** (number) - The score associated with this starter.
      - **score_label** (string) - The score label for the starter.
      - **score_description** (string) - A description of why this starter is relevant.
      - **score_meta** (array) - Metadata providing context for the connection.
        - **title** (string) - The category of the metadata.
        - **description** (string) - The details of the metadata.
    - **introducer** (object) - Information about the person who can make the introduction.
      - **profile** (object) - Profile details of the introducer.
      - **score** (number) - The score associated with the introducer.
      - **score_label** (string) - The score label for the introducer.
      - **score_meta** (array) - Metadata providing context for the introduction.
        - **title** (string) - The category of the metadata.
        - **description** (string) - The details of the metadata.
    - **summary** (object) - A summary of the introduction path.
      - **score** (number) - The score for this introduction path.
      - **score_label** (string) - The score label for this introduction path.
      - **description** (string) - A description of the introduction path.
- **count** (integer) - The total count of relevant entries.

#### Response Example
```json
{
  "company": {
    "name": "Hooli",
    "linkedin_url": "https://linkedin.com/company/hooli"
  },
  "summary": {
    "score": 8.5,
    "score_label": "Excellent"
  },
  "target_people": [
    {
      "target": {
        "profile": {
          "village_id": "vill_999abc",
          "first_name": "Gavin",
          "last_name": "Belson",
          "linkedin_url": "https://linkedin.com/in/gavin-belson",
          "headline": "CEO at Hooli"
        }
      },
      "count": 1,
      "summary": {
        "score": 8,
        "score_label": "Excellent",
        "description": "🟢 Erlich Bachman → Peter Gregory → Gavin Belson (CEO)"
      },
      "paths": [
        {
          "type": "intro",
          "starters": [
            {
              "profile": {
                "village_id": "vill_789xyz",
                "first_name": "Erlich",
                "last_name": "Bachman",
                "linkedin_url": "https://linkedin.com/in/erlich-bachman",
                "headline": "Founder at Aviato"
              },
              "score": 8.5,
              "score_label": "Excellent",
              "score_description": "🟢 Erlich can make a strong introduction",
              "score_meta": [
                {
                  "title": "Work",
                  "description": "Both worked at Pied Piper (12 employees) Jan '14 - Dec '16"
                },
                {
                  "title": "LinkedIn",
                  "description": "Both are connected on LinkedIn"
                }
              ]
            }
          ],
          "introducer": {
            "profile": {
              "village_id": "vill_456def",
              "first_name": "Peter",
              "last_name": "Gregory",
              "linkedin_url": "https://linkedin.com/in/peter-gregory",
              "headline": "Founder at Raviga Capital"
            },
            "score": 8.5,
            "score_label": "Excellent",
            "score_meta": [
              {
                "title": "Work",
                "description": "Both worked at Hooli (5000 employees) Jan '08 - Jan '12. Peter as Board Member while Gavin as CEO"
              },
              {
                "title": "Verified interactions",
                "description": "Met 15 times for board meetings"
              }
            ]
          },
          "summary": {
            "score": 8.5,
            "score_label": "Excellent",
            "description": "🟢 Erlich can intro via Peter Gregory (Lead investor)"
          }
        }
      ]
    },
    {
      "target": {
        "profile": {
          "village_id": "vill_888xyz",
          "first_name": "Nelson",
          "last_name": "Bighetti",
          "linkedin_url": "https://linkedin.com/in/big-head",
          "headline": "CTO at Hooli"
        }
      },
      "count": 1,
      "summary": {
        "score": 9,
        "score_label": "Excellent",
        "description": "🟢 Richard Hendricks (direct)"
      },
      "paths": [
        {
          "type": "direct",
          "introducer": {
            "profile": {
              "village_id": "vill_123abc456",
              "first_name": "Richard",
              "last_name": "Hendricks",
              "linkedin_url": "https://linkedin.com/in/richard-hendricks",
              "headline": "CEO at Pied Piper"
            },
            "score": 9,
            "score_label": "Excellent",
            "score_description": "🟢 You can reach out directly (college roommate)"
          },
          "starters": [
            {
              "profile": {
                "village_id": "vill_123abc456",
                "first_name": "Richard",
                "last_name": "Hendricks",
                "linkedin_url": "https://linkedin.com/in/richard-hendricks",
                "headline": "CEO at Pied Piper"
              },
              "score": 9,
              "score_label": "Excellent",
              "score_description": "🟢 You can reach out directly (college roommate)",
              "score_meta": [
                {
                  "title": "Personal",
                  "description": "Former roommates at the Hacker Hostel"
                },
                {
                  "title": "Work",
                  "description": "Both worked at Pied Piper (12 employees) Jan '14 - Jun '14"
                }
              ]
            }
          ],
          "summary": {
            "score": 9,
            "score_label": "Excellent",
            "description": "🟢 You can reach out directly (college roommate)"
          }
        }
      ]
    }
  ],
  "count": 9
}
```
#### Error Response
(No specific error responses defined in the provided documentation.)
```

--------------------------------

### Install Village Extension SDK with npm

Source: https://docs.village.do/custom-extension-sdk

Install the @villagehq/extension-sdk package as a dependency. This is the first step to integrate Village's relationship intelligence features into a Chrome extension.

```bash
npm install @villagehq/extension-sdk
```

--------------------------------

### GET /v1/people/paths/{url}

Source: https://docs.village.do/api-reference/people

Retrieves all connection paths from the authenticated user to a target person. Returns introduction routes with scoring metrics, connection details, and introduction recommendations through mutual connections.

```APIDOC
## GET /v1/people/paths/{url}

### Description
Retrieve all connection paths from the authenticated user to a target person. This endpoint discovers introduction routes, calculates connection strength scores, and provides recommendations for making introductions through mutual connections.

### Method
GET

### Endpoint
```
https://api.village.do/v1/people/paths/{url}
```

### Parameters

#### Path Parameters
- **url** (string) - Required - LinkedIn URL of the target person (e.g., https://linkedin.com/in/gavin-belson)

#### Headers
- **x-access-token** (string) - Required - JWT token obtained from /users/authorization endpoint for authentication
- **user-identifier** (string) - Required - Identifier of the user making the request. Should match the identifier used during user integration with Village. Not needed when using user token authentication.

### Request Example
```
curl --request GET \
  --url https://api.village.do/v1/people/paths/{url} \
  --header 'user-identifier: <user-identifier>' \
  --header 'x-access-token: <api-key>'
```

### Response

#### Success Response (200 OK)
- **target** (object) - Target person's profile information
  - **profile** (object) - Profile details
    - **village_id** (string) - Unique Village identifier
    - **first_name** (string) - First name
    - **last_name** (string) - Last name
    - **linkedin_url** (string) - LinkedIn profile URL
    - **headline** (string) - Current professional headline
- **count** (integer) - Number of connection paths found
- **summary** (object) - Overall connection summary
  - **score** (number) - Overall connection strength score (0-10)
  - **score_label** (string) - Score label (e.g., "Excellent", "Good")
  - **description** (string) - Human-readable path description
- **paths** (array) - Array of connection paths
  - **type** (string) - Path type (e.g., "intro")
  - **summary** (object) - Path summary with score and description
  - **starters** (array) - Initiating connection(s)
    - **profile** (object) - Starter's profile information
    - **score** (number) - Connection score
    - **score_label** (string) - Score label
    - **score_description** (string) - Score explanation
    - **score_meta** (array) - Score metadata (work history, LinkedIn connection, etc.)
  - **introducer** (object) - Intermediate connection facilitating the introduction
    - **profile** (object) - Introducer's profile information
    - **score** (number) - Connection score
    - **score_label** (string) - Score label
    - **score_meta** (array) - Score metadata

#### Response Example
```json
{
  "target": {
    "profile": {
      "village_id": "vill_999abc",
      "first_name": "Gavin",
      "last_name": "Belson",
      "linkedin_url": "https://linkedin.com/in/gavin-belson",
      "headline": "CEO at Hooli"
    }
  },
  "count": 1,
  "summary": {
    "score": 8,
    "score_label": "Excellent",
    "description": "🟢 Erlich Bachman → Peter Gregory → Gavin Belson (CEO)"
  },
  "paths": [
    {
      "type": "intro",
      "summary": {
        "score": 8.5,
        "score_label": "Excellent",
        "description": "🟢 Erlich can intro via Peter Gregory (Lead investor)"
      },
      "starters": [
        {
          "profile": {
            "village_id": "vill_789xyz",
            "first_name": "Erlich",
            "last_name": "Bachman",
            "linkedin_url": "https://linkedin.com/in/erlich-bachman",
            "headline": "Founder at Aviato"
          },
          "score": 8.5,
          "score_label": "Excellent",
          "score_description": "🟢 Erlich can make a strong introduction",
          "score_meta": [
            {
              "title": "Work",
              "description": "Both worked at Pied Piper (12 employees) Jan '14 - Present"
            },
            {
              "title": "LinkedIn",
              "description": "Both are connected on LinkedIn"
            }
          ]
        }
      ],
      "introducer": {
        "profile": {
          "village_id": "vill_456def",
          "first_name": "Peter",
          "last_name": "Gregory",
          "linkedin_url": "https://linkedin.com/in/peter-gregory",
          "headline": "Founder at Raviga Capital"
        },
        "score": 8.5,
        "score_label": "Excellent",
        "score_meta": [
          {
            "title": "Work",
            "description": "Both worked at Raviga Capital (50 employees) Jan '13 - Dec '15"
          },
          {
            "title": "LinkedIn",
            "description": "Both are connected on LinkedIn"
          }
        ]
      }
    }
  ]
}
```

#### Error Responses
- **400 Bad Request** - Invalid parameters or malformed request
- **401 Unauthorized** - Missing or invalid authentication token
- **404 Not Found** - Target person not found or no paths available
- **429 Too Many Requests** - Rate limit exceeded
```

--------------------------------

### Company Data Enrichment Example (JSON)

Source: https://docs.village.do/api-reference/companies/enrich-company--bulk

This example demonstrates a successful response for a bulk company data enrichment request. It returns detailed information about a company, including its name, URLs, size, industry, and description.

```json
{
  "success": true,
  "data": [
    {
      "company": {
        "village_id": "company-123",
        "name": "TechCorp Inc",
        "linkedin_url": "https://linkedin.com/company/techcorp",
        "website": "https://techcorp.com",
        "domain": "techcorp.com",
        "employee_size": 500,
        "industry": [
          "Technology",
          "Software"
        ],
        "crunchbase_url": "https://crunchbase.com/organization/techcorp",
        "founded": 2015,
        "description": "Leading technology company specializing in enterprise\n                      software solutions."
      }
    }
  ]
}
```

--------------------------------

### Parse Company Connection Paths JSON Response

Source: https://docs.village.do/api-reference/companies

Example JSON response structure showing target people at a company with their connection paths, introduction chains, and relationship quality scores. Includes nested profiles, path types (intro/direct), and scoring metadata for evaluating connection strength.

```json
[
  {
    "target": {
      "profile": {
        "village_id": "vill_999abc",
        "first_name": "Gavin",
        "last_name": "Belson",
        "linkedin_url": "https://linkedin.com/in/gavin-belson",
        "headline": "CEO at Hooli"
      }
    },
    "count": 1,
    "summary": {
      "score": 8,
      "score_label": "Excellent",
      "description": "🟢 Erlich Bachman → Peter Gregory → Gavin Belson (CEO)"
    },
    "paths": [
      {
        "type": "intro",
        "starters": [
          {
            "profile": {
              "village_id": "vill_789xyz",
              "first_name": "Erlich",
              "last_name": "Bachman",
              "linkedin_url": "https://linkedin.com/in/erlich-bachman",
              "headline": "Founder at Aviato"
            },
            "score": 8.5,
            "score_label": "Excellent",
            "score_description": "🟢 Erlich can make a strong introduction",
            "score_meta": [
              {
                "title": "Work",
                "description": "Both worked at Pied Piper (12 employees) Jan '14 - Dec '16"
              },
              {
                "title": "LinkedIn",
                "description": "Both are connected on LinkedIn"
              }
            ]
          }
        ],
        "introducer": {
          "profile": {
            "village_id": "vill_456def",
            "first_name": "Peter",
            "last_name": "Gregory",
            "linkedin_url": "https://linkedin.com/in/peter-gregory",
            "headline": "Founder at Raviga Capital"
          },
          "score": 8.5,
          "score_label": "Excellent",
          "score_meta": [
            {
              "title": "Work",
              "description": "Both worked at Hooli (5000 employees) Jan '08 - Jan '12. Peter as Board Member while Gavin as CEO"
            },
            {
              "title": "Verified interactions",
              "description": "Met 15 times for board meetings"
            }
          ]
        },
        "summary": {
          "score": 8.5,
          "score_label": "Excellent",
          "description": "🟢 Erlich can intro via Peter Gregory (Lead investor)"
        }
      }
    ]
  },
  {
    "target": {
      "profile": {
        "village_id": "vill_888xyz",
        "first_name": "Nelson",
        "last_name": "Bighetti",
        "linkedin_url": "https://linkedin.com/in/big-head",
        "headline": "CTO at Hooli"
      }
    },
    "count": 1,
    "summary": {
      "score": 9,
      "score_label": "Excellent",
      "description": "🟢 Richard Hendricks (direct)"
    },
    "paths": [
      {
        "type": "direct",
        "introducer": {
          "profile": {
            "village_id": "vill_123abc456",
            "first_name": "Richard",
            "last_name": "Hendricks",
            "linkedin_url": "https://linkedin.com/in/richard-hendricks",
            "headline": "CEO at Pied Piper"
          },
          "score": 9,
          "score_label": "Excellent",
          "score_description": "🟢 You can reach out directly (college roommate)"
        },
        "starters": [
          {
            "profile": {
              "village_id": "vill_123abc456",
              "first_name": "Richard",
              "last_name": "Hendricks",
              "linkedin_url": "https://linkedin.com/in/richard-hendricks",
              "headline": "CEO at Pied Piper"
            },
            "score": 9,
            "score_label": "Excellent",
            "score_description": "🟢 You can reach out directly (college roommate)",
            "score_meta": [
              {
                "title": "Personal",
                "description": "Former roommates at the Hacker Hostel"
              },
              {
                "title": "Work",
                "description": "Both worked at Pied Piper (12 employees) Jan '14 - Jun '14"
              }
            ]
          }
        ],
        "summary": {
          "score": 9,
          "score_label": "Excellent",
          "description": "🟢 You can reach out directly (college roommate)"
        }
      }
    ]
  }
]
```

--------------------------------

### GET /v1/companies/paths/{url}

Source: https://docs.village.do/api-reference/companies

Retrieves connection paths and relevant company information for a given company URL. It helps in understanding how to connect with people within a company by outlining introduction paths.

```APIDOC
## GET /v1/companies/paths/{url}

### Description
Retrieves connection paths and relevant company information for a given company URL. It helps in understanding how to connect with people within a company by outlining introduction paths.

### Method
GET

### Endpoint
/v1/companies/paths/{url}

### Parameters
#### Path Parameters
- **url** (string) - Required - The unique identifier or URL of the company.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl --request GET \
  --url https://api.village.do/v1/companies/paths/{url} \
  --header 'user-identifier: <user-identifier>' \
  --header 'x-access-token: <api-key>'
```

### Response
#### Success Response (200)
- **company** (object) - Information about the company.
  - **name** (string) - The name of the company.
  - **linkedin_url** (string) - The LinkedIn URL of the company.
- **summary** (object) - A summary of the company's reach or potential.
  - **score** (number) - A numerical score representing the summary.
  - **score_label** (string) - A descriptive label for the score.
- **target_people** (array) - A list of target individuals within the company and their connection paths.
  - **target** (object) - Information about the target person.
    - **profile** (object) - Profile details of the target person.
      - **village_id** (string) - The unique Village ID of the person.
      - **first_name** (string) - The first name of the person.
      - **last_name** (string) - The last name of the person.
      - **linkedin_url** (string) - The LinkedIn URL of the person.
      - **headline** (string) - The current headline of the person.
  - **count** (integer) - The number of connection paths found.
  - **summary** (object) - A summary of the connection possibilities for this person.
    - **score** (number) - The score for this connection summary.
    - **score_label** (string) - The label for the connection summary score.
    - **description** (string) - A textual description of the connection path.
  - **paths** (array) - An array of possible connection paths.
    - **type** (string) - The type of connection path (e.g., 'intro', 'direct').
    - **starters** (array) - Individuals who can initiate a connection.
      - **profile** (object) - Profile details of the starter.
      - **score** (number) - The score of this starter.
      - **score_label** (string) - The label for the starter's score.
      - **score_description** (string) - A description of why this starter is relevant.
      - **score_meta** (array) - Additional metadata about the connection score.
    - **introducer** (object) - Information about the person who can make an introduction.
      - **profile** (object) - Profile details of the introducer.
      - **score** (number) - The score of this introducer.
      - **score_label** (string) - The label for the introducer's score.
      - **score_meta** (array) - Additional metadata about the introducer's score.
- **count** (integer) - The total number of target people found.

#### Response Example
```json
{
  "company": {
    "name": "Hooli",
    "linkedin_url": "https://linkedin.com/company/hooli"
  },
  "summary": {
    "score": 8.5,
    "score_label": "Excellent"
  },
  "target_people": [
    {
      "target": {
        "profile": {
          "village_id": "vill_999abc",
          "first_name": "Gavin",
          "last_name": "Belson",
          "linkedin_url": "https://linkedin.com/in/gavin-belson",
          "headline": "CEO at Hooli"
        }
      },
      "count": 1,
      "summary": {
        "score": 8,
        "score_label": "Excellent",
        "description": "🟢 Erlich Bachman → Peter Gregory → Gavin Belson (CEO)"
      },
      "paths": [
        {
          "type": "intro",
          "starters": [
            {
              "profile": {
                "village_id": "vill_789xyz",
                "first_name": "Erlich",
                "last_name": "Bachman",
                "linkedin_url": "https://linkedin.com/in/erlich-bachman",
                "headline": "Founder at Aviato"
              },
              "score": 8.5,
              "score_label": "Excellent",
              "score_description": "🟢 Erlich can make a strong introduction",
              "score_meta": [
                {
                  "title": "Work",
                  "description": "Both worked at Pied Piper (12 employees) Jan '14 - Dec '16"
                },
                {
                  "title": "LinkedIn",
                  "description": "Both are connected on LinkedIn"
                }
              ]
            }
          ],
          "introducer": {
            "profile": {
              "village_id": "vill_456def",
              "first_name": "Peter",
              "last_name": "Gregory",
              "linkedin_url": "https://linkedin.com/in/peter-gregory",
              "headline": "Founder at Raviga Capital"
            },
            "score": 8.5,
            "score_label": "Excellent",
            "score_meta": [
              {
                "title": "Work",
                "description": "Both worked at Hooli (5000 employees) Jan '08 - Jan '12. Peter as Board Member while Gavin as CEO"
              },
              {
                "title": "Verified interactions",
                "description": "Met 15 times for board meetings"
              }
            ]
          },
          "summary": {
            "score": 8.5,
            "score_label": "Excellent",
            "description": "🟢 Erlich can intro via Peter Gregory (Lead investor)"
          }
        }
      ]
    },
    {
      "target": {
        "profile": {
          "village_id": "vill_888xyz",
          "first_name": "Nelson",
          "last_name": "Bighetti",
          "linkedin_url": "https://linkedin.com/in/big-head",
          "headline": "CTO at Hooli"
        }
      },
      "count": 1,
      "summary": {
        "score": 9,
        "score_label": "Excellent",
        "description": "🟢 Richard Hendricks (direct)"
      },
      "paths": [
        {
          "type": "direct",
          "introducer": {
            "profile": {
              "village_id": "vill_123abc456",
              "first_name": "Richard",
              "last_name": "Hendricks",
              "linkedin_url": "https://linkedin.com/in/richard-hendricks",
              "headline": "CEO at Pied Piper"
            },
            "score": 9,
            "score_label": "Excellent",
            "score_description": "🟢 You can reach out directly (college roommate)"
          },
          "starters": [
            {
              "profile": {
                "village_id": "vill_123abc456",
                "first_name": "Richard",
                "last_name": "Hendricks",
                "linkedin_url": "https://linkedin.com/in/richard-hendricks",
                "headline": "CEO at Pied Piper"
              },
              "score": 9,
              "score_label": "Excellent",
              "score_description": "🟢 You can reach out directly (college roommate)",
              "score_meta": [
                {
                  "title": "Personal",
                  "description": "Former roommates at the Hacker Hostel"
                },
                {
                  "title": "Work",
                  "description": "Both worked at Pied Piper (12 employees) Jan '14 - Jun '14"
                }
              ]
            }
          ],
          "summary": {
            "score": 9,
            "score_label": "Excellent",
            "description": "🟢 You can reach out directly (college roommate)"
          }
        }
      ]
    }
  ],
  "count": 9
}
```
```

--------------------------------

### Get Company Paths

Source: https://docs.village.do/api-reference/companies/get-company-paths

Retrieves a list of paths and contacts for a given company, including direct connections and introducers.

```APIDOC
## GET /websites/village_do

### Description
Retrieves a list of introduction paths and contact details for individuals within a specified company.

### Method
GET

### Endpoint
/websites/village_do

### Parameters
#### Query Parameters
- **company** (string) - Required - The name or identifier of the company to search for.

### Request Example
```
GET /websites/village_do?company=Pied Piper
```

### Response
#### Success Response (200)
- **company** (object) - Information about the company.
  - **paths** (array) - A list of introduction paths.
    - **target** (object) - The target individual in the path.
      - **profile** (object) - Profile details of the target individual.
        - **village_id** (string) - Unique identifier for the individual.
        - **first_name** (string) - First name of the individual.
        - **last_name** (string) - Last name of the individual.
        - **linkedin_url** (string) - LinkedIn profile URL.
        - **headline** (string) - Professional headline.
      - **score** (number) - Relevance score for this path.
      - **score_label** (string) - Label for the score (e.g., "Excellent").
      - **summary** (object) - Summary of the path's value.
    - **introducer** (object) - The introducer in the path.
      - **profile** (object) - Profile details of the introducer.
      - **score** (number) - Relevance score for the introducer.
      - **score_label** (string) - Label for the introducer's score.
      - **score_meta** (array) - Metadata about the introducer's score.
    - **count** (integer) - The number of people found at the company.
  - **summary** (object) - Overall summary of the introduction paths.

#### Response Example
```json
{
  "company": {
    "paths": [
      {
        "target": {
          "profile": {
            "village_id": "vill_456def",
            "first_name": "Peter",
            "last_name": "Gregory",
            "linkedin_url": "https://linkedin.com/in/peter-gregory",
            "headline": "Founder at Raviga Capital"
          },
          "score": 8.5,
          "score_label": "Excellent",
          "score_meta": [
            {
              "title": "Work",
              "description": "Both worked at Hooli (5000 employees) Jan '08 - Jan '12. Peter as Board Member while Gavin as CEO"
            },
            {
              "title": "Verified interactions",
              "description": "Met 15 times for board meetings"
            }
          ]
        },
        "introducer": {
          "profile": {
            "village_id": "vill_123abc456",
            "first_name": "Richard",
            "last_name": "Hendricks",
            "linkedin_url": "https://linkedin.com/in/richard-hendricks",
            "headline": "CEO at Pied Piper"
          },
          "score": 9,
          "score_label": "Excellent",
          "score_description": "🟢 You can reach out directly (college roommate)",
          "starters": [
            {
              "profile": {
                "village_id": "vill_123abc456",
                "first_name": "Richard",
                "last_name": "Hendricks",
                "linkedin_url": "https://linkedin.com/in/richard-hendricks",
                "headline": "CEO at Pied Piper"
              },
              "score": 9,
              "score_label": "Excellent",
              "score_description": "🟢 You can reach out directly (college roommate)",
              "score_meta": [
                {
                  "title": "Personal",
                  "description": "Former roommates at the Hacker Hostel"
                },
                {
                  "title": "Work",
                  "description": "Both worked at Pied Piper (12 employees) Jan '14 - Jun '14"
                }
              ]
            }
          ],
          "summary": {
            "score": 9,
            "score_label": "Excellent",
            "description": "🟢 You can reach out directly (college roommate)"
          }
        },
        "summary": {
          "score": 9,
          "score_label": "Excellent",
          "description": "🟢 You can reach out directly (college roommate)"
        }
      }
    ],
    "count": {
      "allOf": [
        {
          "type": "integer",
          "example": 9,
          "description": "Total number of people found at the company"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Get List Details via OpenAPI Specification

Source: https://docs.village.do/api-reference/lists/get-list

This OpenAPI specification defines the GET /lists/{listId} endpoint. It outlines the request parameters (path, query, header, cookie), authentication methods (UserTokenAuth, APIKey), and possible responses (200 for success with list details, 404 for not found). Dependencies include the JWT token or API secret key and a user identifier for certain authentication types.

```yaml
paths:
  /lists/{listId}:
    get:
      servers:
        - url: https://api.village.do/v1
      request:
        security:
          - title: UserTokenAuth
            parameters:
              query: {}
              header:
                x-access-token:
                  type: apiKey
                  description: JWT token obtained from /users/authorization endpoint
              cookie: {}
          - title: APIKey
            parameters:
              query: {}
              header:
                secret-key:
                  type: apiKey
                  description: API secret key (requires user-identifier header)
              cookie: {}
        parameters:
          path:
            listId:
              schema:
                - type: integer
                  required: true
          query: {}
          header:
            user-identifier:
              schema:
                - type: string
                  required: true
                  description: >-
                    Specify the user making the request. This identifier should
                    match the one you used when integrating the user with Village.
                    **Not needed when using user token authentication.**
          cookie: {}
        body: {}
      response:
        '200':
          application/json:
            schemaArray:
              - type: object
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/List'
            examples:
              example:
                value:
                  data:
                    id: 42
                    title: Seed investors
                    type: people
                    description: <string>
                    is_public: false
                    fit_count: 18
                    created_date: '2024-06-26T12:00:00Z'
        description: List details
        '404':
          application/json:
            schemaArray:
              - type: object
                properties:
                  error:
                    allOf:
                      - type: string
                        description: Error message
                  code:
                    allOf:
                      - type: string
                        description: Error code for machine reading
            refIdentifier: '#/components/schemas/Error'
        examples:
          example:
            value:
              error: User not found
              code: USER_NOT_FOUND
        description: Not Found - Resource doesn't exist
      deprecated: false
      type: path
components:
  schemas:
    List:
      type: object
      properties:
        id:
          type: integer
          example: 42
        title:
          type: string
          example: Seed investors
        type:
          type: string
          enum:
            - people
            - company
          example: people
        description:
          type: string
        is_public:
          type: boolean
          example: false
        fit_count:
          type: integer
          example: 18
        created_date:
          type: string
          format: date-time
          example: '2024-06-26T12:00:00Z'
```

--------------------------------

### Company Paths API Response Structure

Source: https://docs.village.do/api-reference/companies

This JSON object represents the response from the Village.do 'Get Company Paths' API endpoint. It includes details about the company, a summary score, and a list of target people with their respective connection paths. Each path details how to connect, including starters and introducers, along with scores and descriptions.

```json
{
  "company": {
    "name": "Hooli",
    "linkedin_url": "https://linkedin.com/company/hooli"
  },
  "summary": {
    "score": 8.5,
    "score_label": "Excellent"
  },
  "target_people": [
    {
      "target": {
        "profile": {
          "village_id": "vill_999abc",
          "first_name": "Gavin",
          "last_name": "Belson",
          "linkedin_url": "https://linkedin.com/in/gavin-belson",
          "headline": "CEO at Hooli"
        }
      },
      "count": 1,
      "summary": {
        "score": 8,
        "score_label": "Excellent",
        "description": "🟢 Erlich Bachman → Peter Gregory → Gavin Belson (CEO)"
      },
      "paths": [
        {
          "type": "intro",
          "starters": [
            {
              "profile": {
                "village_id": "vill_789xyz",
                "first_name": "Erlich",
                "last_name": "Bachman",
                "linkedin_url": "https://linkedin.com/in/erlich-bachman",
                "headline": "Founder at Aviato"
              },
              "score": 8.5,
              "score_label": "Excellent",
              "score_description": "🟢 Erlich can make a strong introduction",
              "score_meta": [
                {
                  "title": "Work",
                  "description": "Both worked at Pied Piper (12 employees) Jan '14 - Dec '16"
                },
                {
                  "title": "LinkedIn",
                  "description": "Both are connected on LinkedIn"
                }
              ]
            }
          ],
          "introducer": {
            "profile": {
              "village_id": "vill_456def",
              "first_name": "Peter",
              "last_name": "Gregory",
              "linkedin_url": "https://linkedin.com/in/peter-gregory",
              "headline": "Founder at Raviga Capital"
            },
            "score": 8.5,
            "score_label": "Excellent",
            "score_meta": [
              {
                "title": "Work",
                "description": "Both worked at Hooli (5000 employees) Jan '08 - Jan '12. Peter as Board Member while Gavin as CEO"
              },
              {
                "title": "Verified interactions",
                "description": "Met 15 times for board meetings"
              }
            ]
          },
          "summary": {
            "score": 8.5,
            "score_label": "Excellent",
            "description": "🟢 Erlich can intro via Peter Gregory (Lead investor)"
          }
        }
      ]
    },
    {
      "target": {
        "profile": {
          "village_id": "vill_888xyz",
          "first_name": "Nelson",
          "last_name": "Bighetti",
          "linkedin_url": "https://linkedin.com/in/big-head",
          "headline": "CTO at Hooli"
        }
      },
      "count": 1,
      "summary": {
        "score": 9,
        "score_label": "Excellent",
        "description": "🟢 Richard Hendricks (direct)"
      },
      "paths": [
        {
          "type": "direct",
          "introducer": {
            "profile": {
              "village_id": "vill_123abc456",
              "first_name": "Richard",
              "last_name": "Hendricks",
              "linkedin_url": "https://linkedin.com/in/richard-hendricks",
              "headline": "CEO at Pied Piper"
            },
            "score": 9,
            "score_label": "Excellent",
            "score_description": "🟢 You can reach out directly (college roommate)"
          },
          "starters": [
            {
              "profile": {
                "village_id": "vill_123abc456",
                "first_name": "Richard",
                "last_name": "Hendricks",
                "linkedin_url": "https://linkedin.com/in/richard-hendricks",
                "headline": "CEO at Pied Piper"
              },
              "score": 9,
              "score_label": "Excellent",
              "score_description": "🟢 You can reach out directly (college roommate)",
              "score_meta": [
                {
                  "title": "Personal",
                  "description": "Former roommates at the Hacker Hostel"
                },
                {
                  "title": "Work",
                  "description": "Both worked at Pied Piper (12 employees) Jan '14 - Jun '14"
                }
              ]
            }
          ],
          "summary": {
            "score": 9,
            "score_label": "Excellent",
            "description": "🟢 You can reach out directly (college roommate)"
          }
        }
      ]
    }
  ],
  "count": 9
}
```

--------------------------------

### API Error Response Example (Rate Limit Exceeded)

Source: https://docs.village.do/api-reference/companies/enrich-company--bulk

This example displays the JSON response when the API rate limit is exceeded. It provides a message suggesting a delay before retrying and a specific error code for identifying this condition.

```json
{
  "error": "Rate limit exceeded. Try again in 60 seconds",
  "code": "RATE_LIMIT_EXCEEDED"
}
```
Tokens:
Raw