​
Welcome

Welcome to Village’s API documentation. Our API enables partners to access connection paths and relationship data through their integrated applications. You can use these endpoints to add relationship intelligence features to your applications, such as showing connection paths to LinkedIn profiles.

​
Authentication

All API endpoints require an API key for authentication. To get your API key:
  1. Log in to the Village Platform Admin
  2. Navigate to API Keys
  3. Create a new API key or copy your existing one
Include your API key in all requests using the following header: 
secret-key: YOUR_API_KEY
For testing purposes, if your app is not live yet, you can use this test key: 
secret-key: demo_sk_global

​
User Identification

Most endpoints require a user identifier to specify which end-user’s network we’re referencing. This identifier should match the one you used when integrating the user with Village. Include it in the request headers: 
user-identifier: YOUR_USER_IDENTIFIER
For testing purposes, if your app is not live yet, you can use this test identifier: 
user-identifier: test_user_identifier
For example, if you integrated user “123” from your system with Village, you would use “123” as the identifier in your API requests to reference that user’s network.

​
Core Concepts

  • 🛣️ Paths: Connection routes showing how you can reach someone through your network
  • 📊 Score: Numerical values indicating relationship strength
  • 🤝 Introducers: People who can make direct introductions to your target
  • 🚀 Starters: Your direct connections who can kick off the introduction chain

​
Rate Limits

  • 100 requests per second per API key
  • Contact support to increase limits

​
Base URL

The API is available at:

​
Error Responses

All endpoints may return these error responses:
StatusDescription
400Bad Request - Check the request parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Please contact support

​
Available Endpoints

Our API provides endpoints in three main categories:

People Endpoints

Find connection paths to people and sort contacts by relationship strength

Companies Endpoints

Discover company relationships and connection paths

Provisioned Users Endpoints

Manage provisioned users and their subscriptions