AI people search

curl --request POST \
  --url https://api.village.do/v1/people/search \
  --header 'Content-Type: application/json' \
  --header 'user-identifier: <user-identifier>' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "prompt": "software engineers in silicon valley",
  "limit": 25,
  "high_reasoning": false,
  "network_filters": {
    "connection_degrees": [
      1,
      2
    ],
    "exclude_teams": true,
    "user_to_introducer_types": [
      "linkedin_contact",
      "worked_together"
    ],
    "user_to_introducer_min_score": "good",
    "introducer_to_target_types": [
      "linkedin_contact"
    ],
    "introducer_to_target_min_score": "good"
  }
}
'

{
  "success": true,
  "data": [
    {
      "id": "420587592",
      "avatar": "https://village.sfo3.cdn.digitaloceanspaces.com/l-castilhos-anderson.jpg",
      "first_name": "Anderson",
      "last_name": "Castilhos",
      "full_name": "Anderson Castilhos",
      "title": "Senior Software Engineer",
      "linkedin_identifier": "castilhos-anderson",
      "linkedin_url": "https://linkedin.com/in/castilhos-anderson",
      "location": "Porto Alegre, Rio Grande Do Sul, Brazil",
      "village_person_url": "https://rafael-village-tunnel.village.do/people/profile/5KvSxBQ%252B%252FbUGKWrxxnr%252Fnw%253D%253D!vNnNM",
      "relationship": {
        "paths": {
          "count": 1,
          "avatars": [
            "https://village.sfo3.cdn.digitaloceanspaces.com/l-rafaelmuttoni.jpg"
          ]
        },
        "score": 17.4
      },
      "relevant_work": {
        "position": "Senior Software Engineer",
        "start_date": null,
        "end_date": null,
        "company": {
          "name": "PayPal",
          "employee_size": null,
          "domain_name": null,
          "image_url": "",
          "linkedin_url": null,
          "website": ""
        }
      }
    }
  ],
  "pagination": {
    "cursor": "eyJzb3VyY2UiOiJuZXR3b3JrIiwiY2h1bmtTa2lwIjowLCJyZXN1bHRzU2tpcCI6MTAwfQ",
    "hasNextPage": true,
    "count": 25
  },
  "metadata": {
    "resultSource": "network",
    "networkStageComplete": false
  }
}

POST

people

AI people search

curl --request POST \
  --url https://api.village.do/v1/people/search \
  --header 'Content-Type: application/json' \
  --header 'user-identifier: <user-identifier>' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "prompt": "software engineers in silicon valley",
  "limit": 25,
  "high_reasoning": false,
  "network_filters": {
    "connection_degrees": [
      1,
      2
    ],
    "exclude_teams": true,
    "user_to_introducer_types": [
      "linkedin_contact",
      "worked_together"
    ],
    "user_to_introducer_min_score": "good",
    "introducer_to_target_types": [
      "linkedin_contact"
    ],
    "introducer_to_target_min_score": "good"
  }
}
'

{
  "success": true,
  "data": [
    {
      "id": "420587592",
      "avatar": "https://village.sfo3.cdn.digitaloceanspaces.com/l-castilhos-anderson.jpg",
      "first_name": "Anderson",
      "last_name": "Castilhos",
      "full_name": "Anderson Castilhos",
      "title": "Senior Software Engineer",
      "linkedin_identifier": "castilhos-anderson",
      "linkedin_url": "https://linkedin.com/in/castilhos-anderson",
      "location": "Porto Alegre, Rio Grande Do Sul, Brazil",
      "village_person_url": "https://rafael-village-tunnel.village.do/people/profile/5KvSxBQ%252B%252FbUGKWrxxnr%252Fnw%253D%253D!vNnNM",
      "relationship": {
        "paths": {
          "count": 1,
          "avatars": [
            "https://village.sfo3.cdn.digitaloceanspaces.com/l-rafaelmuttoni.jpg"
          ]
        },
        "score": 17.4
      },
      "relevant_work": {
        "position": "Senior Software Engineer",
        "start_date": null,
        "end_date": null,
        "company": {
          "name": "PayPal",
          "employee_size": null,
          "domain_name": null,
          "image_url": "",
          "linkedin_url": null,
          "website": ""
        }
      }
    }
  ],
  "pagination": {
    "cursor": "eyJzb3VyY2UiOiJuZXR3b3JrIiwiY2h1bmtTa2lwIjowLCJyZXN1bHRzU2tpcCI6MTAwfQ",
    "hasNextPage": true,
    "count": 25
  },
  "metadata": {
    "resultSource": "network",
    "networkStageComplete": false
  }
}

Authorizations

x-access-token

string

header

required

JWT token obtained from /users/authorization endpoint

Headers

user-identifier

string

required

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.

Body

application/json

prompt

string

required

Natural language search query

Example:

"software engineers in silicon valley"

limit

integer

default:25

Number of results per page

Required range: x <= 100

cursor

string

Cursor for pagination (returned from previous requests)

high_reasoning

boolean

default:false

Enable high reasoning mode for complex queries

network_filters

object

Advanced filters to refine people search results based on relationship connections and network paths. Only applicable to people search - ignored for company search.

Show child attributes

network_filters.connection_degrees

integer[]

Filter by connection distance: 1st degree (direct connections), 2nd degree (friends of friends), 3rd degree (extended network requiring team introductions)

Required range: 1 <= x <= 3

Example:

[1, 2]

network_filters.introducer_linkedin_ids

string[]

Only include results that can be reached through specific people (by their LinkedIn identifiers). Useful for finding connections through particular individuals.

Minimum string length: 1

Example:

["john-doe-123", "jane-smith-456"]

network_filters.exclude_teams

boolean

default:false

Exclude results from your team members. Useful when searching for external connections.

network_filters.exclude_communities

boolean

default:false

Exclude results from community members. Useful when searching for connections outside your communities.

network_filters.user_to_introducer_types

enum<string>[]

Types of connections between you and the introducer: 'worked_together' (professional colleagues), 'linkedin_contact' (LinkedIn connections), 'has_contact_info' (have contact details), 'had_meetings' (have met in person)

Minimum array length: 1

Available options:

worked_together,

linkedin_contact,

has_contact_info,

had_meetings

Example:

["linkedin_contact", "worked_together"]

network_filters.user_to_introducer_min_score

enum<string>

Minimum relationship strength between you and the introducer. Higher scores indicate stronger, more trustworthy connections.

Available options:

excellent,

very_good,

good,

okay,

maybe,

no_path

Example:

"good"

network_filters.introducer_to_target_types

enum<string>[]

Types of connections between the introducer and target person: 'worked_together' (professional colleagues), 'linkedin_contact' (LinkedIn connections), 'has_contact_info' (have contact details), 'had_meetings' (have met in person)

Minimum array length: 1

Available options:

worked_together,

linkedin_contact,

has_contact_info,

had_meetings

Example:

["linkedin_contact", "worked_together"]

network_filters.introducer_to_target_min_score

enum<string>

Minimum relationship strength between the introducer and target person. Higher scores indicate stronger, more trustworthy introduction paths.

Available options:

excellent,

very_good,

good,

okay,

maybe,

no_path

Example:

"good"

Response

Successfully processed AI search query

success

boolean

Indicates if the request was successful

Example:

true

data

object[]

Array of people search results

Show child attributes

data.id

string

Unique identifier for the person

data.avatar

string

URL to person's avatar image

data.first_name

string

Person's first name

data.last_name

string

Person's last name

data.full_name

string

Person's full name

data.title

string

Person's job title

data.linkedin_identifier

string

LinkedIn identifier

data.linkedin_url

string

LinkedIn profile URL

data.location

string

Person's location

data.village_person_url

string

Village profile URL

data.relationship

object

Relationship data

Show child attributes

data.relationship.paths

object

Show child attributes

data.relationship.paths.count

integer

Number of connection paths

data.relationship.paths.avatars

string[]

Avatar URLs for connection paths

data.relationship.score

number

Warmth score for this relationship

data.relevant_work

object

Most relevant work experience

Show child attributes

data.relevant_work.position

string

Job position

data.relevant_work.start_date

string<date> | null

Start date

data.relevant_work.end_date

string<date> | null

End date

data.relevant_work.company

object

Show child attributes

data.relevant_work.company.name

string

Company name

data.relevant_work.company.employee_size

integer | null

Employee count

data.relevant_work.company.domain_name

string | null

Company domain

data.relevant_work.company.image_url

string

Company logo URL

data.relevant_work.company.linkedin_url

string | null

Company LinkedIn URL

data.relevant_work.company.website

string

Company website

pagination

object

Show child attributes

pagination.cursor

string | null

Cursor for next page of results

pagination.hasNextPage

boolean

Whether there are more pages available

pagination.count

integer

Number of results in this batch

metadata

object

Show child attributes

metadata.resultSource

enum<string>

Source of the search results

Available options:

network,

global

metadata.networkStageComplete

boolean

Whether the network search stage is complete

Enrich Emails (Bulk)Get Company Paths

⌘I

API Documentation

People

Companies

Provisioned Users

Lists

Groups

Teams

User Relationships

AI people search

Authorizations

Headers

Body

Response