Search Leads API

Search for leads by ID or email address. This endpoint powers the lead autocomplete used throughout kenbun, including the trigger test dialog and integration lookups.

GET /leads/search

Returns up to 10 matching leads with their best alias, match type, and current engagement and profile levels.

Request

Parameter	Type	Required	Description
q	string	Yes	Search query (minimum 2 characters). Searches by lead ID prefix or alias value (email, phone, etc.). Case-insensitive

Response

200 OK

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "match_type": "alias",
    "best_alias": "jane.doe@example.com",
    "engagement_level": "High",
    "profile_level": "Ideal Customer"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "match_type": "alias",
    "best_alias": "jane.smith@company.com",
    "engagement_level": "Medium",
    "profile_level": null
  }
]

Response Fields

Field	Type	Description
id	string	Lead's unique identifier
match_type	string	How the lead was matched: id (Lead ID prefix) or alias (email or other alias)
best_alias	string or null	Lead's primary alias (typically email). Null if no aliases exist
engagement_level	string or null	Current engagement level (e.g., "High", "Medium", "Low"). Null if not yet classified
profile_level	string or null	Current profile level (e.g., "Ideal Customer", "Good Fit"). Null if not yet classified

Example

curl -X GET "https://api.kenbun.io/leads/search?q=jane" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
400	Bad Request	Ensure active OU is set
401	Unauthorized	Check authentication credentials
500	Server Error	Retry later or contact support

---

Notes

• Results are OU-scoped to the active Organizational Unit
• Queries shorter than 2 characters return an empty array
• Lead ID matching uses prefix search (type the beginning of a Lead ID)
• Alias matching uses contains search (type any part of an email address)
• Results are ordered by match type (ID matches first, then alias matches), then by most recently updated
• Returns a maximum of 10 results

Related Endpoints

• Leads - List all leads with scores
• Lead by ID - Get a specific lead's details
• Trigger Simulate - Test a milestone trigger against a lead
• Sequence Simulate - Test a sequence trigger against a lead