Skip to main content
POST
/
companies
/
search
AI company search
curl --request POST \
  --url https://api.village.do/v1/companies/search \
  --header 'Content-Type: application/json' \
  --header 'user-identifier: <user-identifier>' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "prompt": "fintech companies in london",
  "limit": 25,
  "cursor": "<string>",
  "high_reasoning": false
}
'
{
  "success": true,
  "data": [
    {
      "employee_size": 144071,
      "domain_name": "upwork.com",
      "id": "upwork",
      "image_url": "https://village.sfo3.cdn.digitaloceanspaces.com/company/upwork.jpg",
      "linkedin_url": "https://linkedin.com/company/upwork",
      "name": "Upwork",
      "website": "https://upwork.com",
      "relationship": {
        "score": 16.9,
        "paths": {
          "count": 111,
          "avatars": [
            "https://village.sfo3.cdn.digitaloceanspaces.com/l-ziad-ibrahim-12391279.jpg",
            "https://village.sfo3.cdn.digitaloceanspaces.com/l-eric-mendoza-65528a187.jpg",
            "https://village.sfo3.cdn.digitaloceanspaces.com/l-priyankaupadhyay11.jpg"
          ]
        }
      },
      "headquarters": "San Francisco, California",
      "country_code": "us"
    }
  ],
  "pagination": {
    "cursor": "eyJzb3VyY2UiOiJuZXR3b3JrIiwiY2h1bmtTa2lwIjowLCJyZXN1bHRzU2tpcCI6MX0",
    "hasNextPage": true,
    "count": 1
  },
  "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:

"fintech companies in london"

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

Response

Successfully processed AI search query

success
boolean

Indicates if the request was successful

Example:

true

data
object[]

Array of company search results

pagination
object
metadata
object