Semantic Search

Perform an AI-powered semantic search. Use the entityType field in the request body to specify which entity type to search. Currently only supports companies.

The prompt field accepts natural language describing the companies to find. Supported query dimensions include:

• Industry or sector
  • Example: climate tech companies in our pipeline
• Descriptive technology or business concepts
  • Example: biotech companies working on extracellular vesicles
• Funding information: investment stage, funding date, amount raised, and year founded
  • Example: Series A companies that raised more than $10M
• Employee metrics: headcount, hiring rate, and departure rate
  • Example: companies with more than 100 employees
• Interaction history
  • Example: companies our firm emailed recently
• Relationship strength
  • Example: companies where we have strong connections
• Relative time references
  • Example: AI companies founded in the past 3 years
• Headquarters location: city, state, country, or region
  • Example: fintech startups in San Francisco
• Investor name
  • Example: companies backed by Sequoia Capital

These dimensions can be combined in a single prompt, for example climate tech companies in San Francisco that raised a Series A in the past year.

Results can be sorted by including the desired sort in the prompt itself, for example Series B companies with the most funding. Only one sortable attribute is supported per request.

Use the listIds field to scope results to companies on specific lists, and combine it with prompt to search semantically within those lists. Retrieve list IDs from GET /v2/lists.

The phrases I, we, and our firm always refer to firm-wide data: interaction history and relationship strength cannot be filtered to a specific team member. The phrases in our pipeline and in our network match companies your firm has interacted with or added to Affinity in general. They do not search for membership in a list literally named “Pipeline” or similar. To search a specific named list, use listIds.

The following are not supported:

• Third-party enrichment data such as Crunchbase, PitchBook, or Dealroom.
• Company valuation and revenue metrics.
• Lookup by similarity to a named company, for example companies like OpenAI.
• Notes, email body content, or file attachments.
• Custom fields.
• Computed or formula-based sorts, such as a ratio between two fields.

POST /v2/semantic-search

Semantic Search

cURL

curl --request POST \
  --url https://api.affinity.co/v2/semantic-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Fintech companies based in the United States with over 50 employees",
  "limit": 10,
  "entityType": "companies",
  "listIds": [
    1,
    2
  ]
}
'

201

{
  "data": [
    {
      "id": 1,
      "name": "Horizon Technologies",
      "domain": "horizontech.com",
      "domains": [
        "horizontech.com"
      ],
      "isGlobal": true,
      "score": "0.85"
    }
  ],
  "entityType": "companies",
  "explanation": "This result matched the search criteria."
}

Authorizations

apiKeyAuthoauth2

Authorization · string · header · required

A static Affinity API key, presented as a bearer token.

Body

application/json

Semantic search criteria including search prompt and entity type

prompt · string · required

The search prompt to apply.

Required string length: 1 - 500

Example:

"Fintech companies based in the United States with over 50 employees"

limit · integer<int32> · default: 100

Number of items to include in the response.

Required range: 1 <= x <= 100

Example:

10

entityType · string

The type of entity to search for.

Allowed value: "companies"

Example:

"companies"

listIds · integer<int64>[]

The IDs of the lists to filter results by.

Maximum array length: 100

Required range: 1 <= x <= 9007199254740991

Example:

[1, 2]

Response

201

application/json

Created

Includes the list of entities that matched the search prompt and the explanation for the search.

data · companies.SemanticSearchCompany · object[] · required

The list of entities that matched the search prompt

Maximum array length: 100

Show child attributes

entityType · string · required

The type of entity that was searched.

Allowed value: "companies"

Example:

"companies"

explanation · string · required

Example:

"This result matched the search criteria."