Search Profiles

​

Endpoint

GET /v1/search

​

Description

• Vector search for semantic, natural language queries.
• Classic search for field-based filtering, sorting, and pagination.

​

Query Parameters

​

Behavior

​

If query is provided:

• Uses vector search (AI embeddings) to find similar profiles.
• Results are always ranked by similarity (similarityScore).
• Classic sorting (sortBy) is ignored for vector search (limitation of vector search engines).

​

If no query is provided:

• Classic search: results are filtered, sorted, and paginated as usual.

​

If both query and filters are provided:

• Vector search results are filtered by filterBy and filterValue after vector search.
• Sorted by similarity.

​

Example Request

GET /v1/smart-search?query=experienced+data+scientist+with+PhD+looking+for+job&filterBy=location&filterValue=California&sortBy=last_updated&sortOrder=desc&page=1&pageSize=10

​

Example Response

{
  "profiles": [
    {
      "profile_id": "abc123",
      "tenant_id": "tenant123",
      "status": "active",
      "core_info": {
        "name": "Jane Doe",
        "location": "Helsinki",
        "age": 35,
        "language": "Finnish"
      },
      "last_updated": "2024-06-01T10:00:00Z",
      "created_at": "2023-05-10T15:30:00Z",
      "similarityScore": 0.92
    },
    ...
  ],
  "total": 10,
  "page": 1,
  "pageSize": 10
}

​

Notes

• Vector search does not support custom sortBy fields—results are always sorted by similarityScore when query is used.
• If you need to sort vector search results by another field, consider post-processing in your application after fetching results.
• For classic listing, sorting works as expected for any sortBy field.

​

Use Cases

• Discover profiles matching natural language queries like:

“experienced data scientist with PhD looking for job”

• Filter results by specific fields like location or language.
• Paginate and load results seamlessly in your UI.
• Soon: create profile segments based on search results for targeted actions and campaigns.

​

Conclusion