POST
/
people
/
search
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 '{
  "query": "Fintech CFOs in London",
  "page": 123,
  "limit": 25
}'
{
  "success": true,
  "data": [
    {
      "id": "12345678-1234-5678-9abc-123456789def",
      "type": "person",
      "avatar": "https://example.com/avatars/john-smith.jpg",
      "country": "United States",
      "firstName": "John",
      "lastName": "Smith",
      "fullName": "John Smith",
      "linkedinIdentifier": "john-smith-12345",
      "linkedinUrl": "https://linkedin.com/in/john-smith-12345",
      "location": "San Francisco, CA",
      "villageUrl": "https://example.com/people/profile/encoded-id-1",
      "warmthScore": 85.2,
      "relationship": {
        "warmthScore": 85.2,
        "paths": {
          "count": 2,
          "ids": [
            "path-123",
            "path-456"
          ],
          "avatars": [
            "https://example.com/avatars/connector1.jpg",
            "https://example.com/avatars/connector2.jpg"
          ]
        }
      },
      "currentWork": {
        "position": "Founder & CEO",
        "startDate": "2018-03-01",
        "endDate": null,
        "company": {
          "id": "example-startup",
          "type": "company",
          "name": "Example Startup Inc.",
          "linkedinUrl": "https://linkedin.com/company/example-startup",
          "website": "https://example-startup.com",
          "domain": "example-startup.com",
          "imageUrl": "https://example.com/company-logos/example-startup.jpg",
          "employeeSize": 25
        }
      }
    },
    {
      "id": "87654321-4321-8765-cba9-987654321fed",
      "type": "person",
      "avatar": "https://example.com/avatars/jane-doe.jpg",
      "country": "United Kingdom",
      "firstName": "Jane",
      "lastName": "Doe",
      "fullName": "Jane Doe",
      "linkedinIdentifier": "jane-doe-67890",
      "linkedinUrl": "https://linkedin.com/in/jane-doe-67890",
      "location": "London, UK",
      "villageUrl": "https://example.com/people/profile/encoded-id-2",
      "warmthScore": 72.8,
      "relationship": {
        "warmthScore": 72.8,
        "paths": {
          "count": 1,
          "ids": [
            "path-789"
          ],
          "avatars": [
            "https://example.com/avatars/connector3.jpg"
          ]
        }
      },
      "currentWork": {
        "position": "CTO & Co-founder",
        "startDate": "2019-06-15",
        "endDate": null,
        "company": {
          "id": "tech-innovations",
          "type": "company",
          "name": "Tech Innovations Ltd",
          "linkedinUrl": "https://linkedin.com/company/tech-innovations",
          "website": "https://tech-innovations.co.uk",
          "domain": "tech-innovations.co.uk",
          "imageUrl": "https://example.com/company-logos/tech-innovations.jpg",
          "employeeSize": 12
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 2,
    "hasNextPage": true
  },
  "meta": {
    "query": "Fintech CFOs in London",
    "searchType": "ai",
    "apiVersion": "v1"
  }
}

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

Response

200
application/json

Successfully processed AI search query

The response is of type object.