REST API

Vsyble API

Add people search, company search, and enrichment to your own scripts and services. The public API uses JSON over HTTPS and a revocable Vsyble API key.

Base URL

https://api.vsyble.com

Prefer an AI-client connection?

Read the MCP guide

Quick start

Create a key Create a separate, revocable API key for each application or environment.
Store it securely Keep the key in a server-side secret or environment variable, not in source code.
Send a request Pass the key in the authentication header and send a JSON request body.

curl https://api.vsyble.com/v1/people/search \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Vsyble-Api-Key: $VSYBLE_API_KEY" \
  --data '{
    "query": "Revenue leaders at B2B software companies",
    "limit": 5,
    "search_type": "fast",
    "filters": {
      "seniority": "executive",
      "requireLinkedIn": true
    }
  }'

Manage API keys

Live API playground

Try a canonical request against the fixed Vsyble API origin. The page validates your JSON locally and sends only when you choose Send request. It never retries or polls automatically.

Endpoint

API key

Kept only in this page's memory and never added to examples.

Request JSON

Search requests use the caller's Vsyble search allowance and are subject to credential spend controls. Clicking Send request confirms this use.

Authentication

Every request requires a Vsyble API key in the X-Vsyble-Api-Key header. Do not send the key in the URL or request body.

Use a different key for each integration, keep it outside the browser in production, and revoke it immediately if it is exposed.

HTTP header

X-Vsyble-Api-Key: $VSYBLE_API_KEY

Errors and rate limits

Error responses use a stable code and concise message. They can also include a request ID for support and an explicit retry delay. A retry delay is guidance, not permission to poll automatically.

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "limit must be an integer between 1 and 25",
    "retry_after_seconds": 0
  }
}

API request rate limits
Scope	Limit
Per API key	60 requests / 60 seconds
Per client address	120 requests / 60 seconds

Account quotas, credential spend controls, and enrichment allowances are enforced separately.

POST/v1/people/search

Search for people

Find an exact requested number of professionals when enough matching public-source results are available. Filter by experience, seniority, geography, and LinkedIn availability. Email and phone are intentionally excluded from base search and require enrichment.

Search allowance

Search requests use the caller's Vsyble search allowance and are subject to credential spend controls.

Usage unit: search request

Request parameters

Search for people request parameters
Parameter	Type	Requirement	Description
`query`	string	Required	Natural-language description of the professionals to find. Constraints: 2–500 characters
`limit`	integer	Required	Exact requested number of results, from 1 to 25. Constraints: 1–25
`search_type`	string	Optional	Search strategy. Auto is recommended; instant and fast prioritize latency, while deep modes add research depth. Neural is a legacy alias for auto. Constraints: auto \| instant \| fast \| deep-lite \| deep \| deep-reasoning \| neural; default: auto
`filters`	object	Optional	Optional structured people filters.
`filters.includeInternational`	boolean	Optional	False requires the United States or Canada, true allows global results, and omission follows the query.
`filters.minYearsExperience`	integer	Optional	Minimum years of professional experience. Constraints: 0–80
`filters.seniority`	string	Optional	Required seniority category. Constraints: any \| founder \| executive \| manager \| individual_contributor; default: any
`filters.requireLinkedIn`	boolean	Optional	Require each returned person to have a LinkedIn profile URL. Constraints: default: false

Request example

curl https://api.vsyble.com/v1/people/search \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Vsyble-Api-Key: $VSYBLE_API_KEY" \
  --data '{
    "query": "Revenue leaders at B2B software companies",
    "limit": 5,
    "search_type": "fast",
    "filters": {
      "seniority": "executive",
      "requireLinkedIn": true
    }
  }'

Response example

The people search completed. Fewer results can be returned when the available public evidence does not satisfy the request.

Response status

JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "tool": "people_search",
  "result_count": 1,
  "duration_ms": 1840,
  "people": [
    {
      "name": "Jordan Lee",
      "jobTitle": "VP of Revenue",
      "company": "Example Cloud",
      "linkedinUrl": "https://www.linkedin.com/in/example-jordan-lee"
    }
  ],
  "companies": [],
  "search_results": [
    {
      "title": "Jordan Lee - VP of Revenue",
      "url": "https://example.com/jordan-lee"
    }
  ],
  "citations": [
    "https://example.com/jordan-lee"
  ],
  "model": "exa-people-fast"
}

POST/v1/companies/search

Search for companies

Find an exact requested number of companies when enough matching public-source results are available. Filter by geography, employee range, funding stage, hiring activity, and technology.

Search allowance

Search requests use the caller's Vsyble search allowance and are subject to credential spend controls.

Usage unit: search request

Request parameters

Search for companies request parameters
Parameter	Type	Requirement	Description
`query`	string	Required	Natural-language description of the companies or accounts to find. Constraints: 2–500 characters
`limit`	integer	Required	Exact requested number of results, from 1 to 25. Constraints: 1–25
`search_type`	string	Optional	Search strategy. Auto is recommended; instant and fast prioritize latency, while deep modes add research depth. Neural is a legacy alias for auto. Constraints: auto \| instant \| fast \| deep-lite \| deep \| deep-reasoning \| neural; default: auto
`filters`	object	Optional	Optional structured company filters.
`filters.includeInternational`	boolean	Optional	False requires the United States or Canada, true allows global results, and omission follows the query.
`filters.employeeRange`	string	Optional	Required employee-count range. Constraints: any \| 1-10 \| 11-50 \| 51-200 \| 201-500 \| 501-1000 \| 1001-5000 \| 5001+; default: any
`filters.fundingStage`	string	Optional	Required funding stage. Constraints: any \| bootstrapped \| seed \| series_a \| series_b_plus \| public; default: any
`filters.hiringOnly`	boolean	Optional	Restrict results to companies with current hiring evidence. Constraints: default: false
`filters.technology`	string	Optional	Technology that matching companies should use. Constraints: 1–80 characters

Request example

curl https://api.vsyble.com/v1/companies/search \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Vsyble-Api-Key: $VSYBLE_API_KEY" \
  --data '{
    "query": "AI infrastructure companies hiring sales leaders",
    "limit": 10,
    "search_type": "auto",
    "filters": {
      "employeeRange": "51-200",
      "fundingStage": "series_a",
      "hiringOnly": true,
      "technology": "Kubernetes"
    }
  }'

Response example

The company search completed. Fewer results can be returned when the available public evidence does not satisfy the request.

Response status

JSON

{
  "request_id": "22222222-2222-4222-8222-222222222222",
  "tool": "company_search",
  "result_count": 1,
  "duration_ms": 2260,
  "people": [],
  "companies": [
    {
      "name": "Example Cloud",
      "domain": "example.com",
      "employeeCount": 120,
      "fundingStage": "series_a"
    }
  ],
  "search_results": [
    {
      "title": "Example Cloud",
      "url": "https://example.com"
    }
  ],
  "citations": [
    "https://example.com"
  ],
  "model": "exa-company"
}

POST/v1/enrich

Enrich selected search results

Enrich only the requested 1-based result numbers from the most recent completed search made with this API key. After a people search, choose exactly one field: email, phone, or university. After a company search, omit field. Repeat the same request to continue work that is still running.

Contact enrichment allowance

Each newly selected result—and, for people, its requested field—can use the caller's contact enrichment allowance. Repeating the same selection resumes or returns its existing work without reserving it again.

Usage unit: new selected result

Request parameters

Enrich selected search results request parameters
Parameter	Type	Requirement	Description
`result_numbers`	integer[]	Required	Explicit 1-based result numbers from this API key's latest completed search. Constraints: 1–25 items; unique items
`field`	string	Optional	Required after a people search and omitted after a company search. Only the selected category is requested from the provider. Constraints: email \| phone \| university

Request example

curl https://api.vsyble.com/v1/enrich \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Vsyble-Api-Key: $VSYBLE_API_KEY" \
  --data '{
    "result_numbers": [
      1,
      3
    ],
    "field": "email"
  }'

Response example

The current enrichment state. A running response can be continued by repeating the same request.

Response status

JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "tool": "people_search",
  "entity_type": "person",
  "status": "completed",
  "done": true,
  "result_count": 2,
  "enriched_count": 2,
  "results": [
    {
      "result_position": 0,
      "result_number": 1,
      "status": "completed",
      "result": {
        "name": "Jordan Lee",
        "email": "jordan.lee@example.com"
      }
    },
    {
      "result_position": 2,
      "result_number": 3,
      "status": "completed",
      "result": {
        "name": "Taylor Morgan",
        "email": "taylor.morgan@example.com"
      }
    }
  ]
}