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"
}
}
Search for people using natural language queries. The AI converts your query into structured filters and returns matching results.
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"
}
}
JWT token obtained from /users/authorization endpoint
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.
Successfully processed AI search query
The response is of type object
.