Skip to main content

Lead Lookup and Profile Update by Alias

Look up a lead by a known alias (such as an email address) and update their profile metadata without needing the internal lead ID. These endpoints are designed for situations where you know a lead's email but not their kenbun ID -- for example, when the Chrome extension identifies a lead on a page, or when an external system needs to enrich a lead by email.

When to Use This​

  • Chrome Extension Lead Profile: The extension auto-detects a lead's email on the page and uses these endpoints to display and update their profile
  • CRM Enrichment: Push contextual data (deal stage, meeting notes, plan interest) from your CRM into kenbun by email
  • Automation Workflows: Update lead attributes from Zapier, Make, or custom scripts that know the lead's email but not their kenbun ID

GET /lead/by-alias​

Look up a lead by alias and return their ID, email, and current metadata attributes.

Authentication​

Required: Yes -- Bearer token (JWT) or HTTP Basic Auth (client_id:client_secret)

Request​

ParameterTypeRequiredDescription
kindstringNoAlias type to search by. Defaults to email.
valuestringYesThe alias value to look up (e.g., the lead's email address)

Response​

200 OK

FieldTypeDescription
lead_idstringUnique lead identifier
emailstringThe email alias that matched
metadataobjectCurrent lead metadata attributes (key-value pairs)

Example​

curl -X GET "https://api.kenbun.io/lead/by-alias?kind=email&value=alex@example.com" \
  -u "CLIENT_ID:CLIENT_SECRET"

Response:

{
  "lead_id": "ld_abc123",
  "email": "alex@example.com",
  "metadata": {
    "first_name": "Alex",
    "company": "Acme Corp",
    "quote_step": "Step 1"
  }
}

Common Errors​

StatusMeaningSolution
400Missing value parameterInclude ?value=email@example.com in the query string
401UnauthorizedCheck your API credentials or bearer token
404No lead found for this aliasVerify the email exists as a lead alias in the active OU

PATCH /lead/by-alias/metadata​

Update a lead's metadata attributes by resolving the lead from an alias. This is a silent update -- no event is created in the activity timeline. Only the specified attributes are merged; existing attributes not included in the request are preserved.

Authentication​

Required: Yes -- Bearer token (JWT) or HTTP Basic Auth (client_id:client_secret)

Request Body​

FieldTypeRequiredDescription
alias_kindstringNoAlias type. Defaults to email.
alias_valuestringYesThe alias value to resolve the lead (e.g., email address)
attributesobjectNoKey-value pairs to merge into the lead's metadata. Required if account_id is not provided.
account_idstringNoAccount ID to associate with this lead. Required if attributes is not provided.

At least one of attributes or account_id must be included.

Attribute key rules:

  • 1 to 64 characters long
  • May contain letters, digits, underscores (_), dashes (-), dots (.), or spaces
  • Keys that do not meet these requirements are rejected with a 400 error

Response​

200 OK

FieldTypeDescription
lead_idstringThe lead that was updated
updatedintegerNumber of metadata attributes written (0 if only account_id was provided)
attributesobjectThe metadata attributes that were saved
account_linkedbooleanWhether the lead was successfully associated with the specified account

Example: Update Metadata​

curl -X PATCH "https://api.kenbun.io/lead/by-alias/metadata" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias_value": "alex@example.com",
    "attributes": {
      "quote_step": "Step 1",
      "interest_level": "high"
    }
  }'

Response:

{
  "lead_id": "ld_abc123",
  "updated": 2,
  "attributes": {
    "quote_step": "Step 1",
    "interest_level": "high"
  },
  "account_linked": false
}
curl -X PATCH "https://api.kenbun.io/lead/by-alias/metadata" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias_value": "alex@example.com",
    "account_id": "acct_abc123"
  }'

Response:

{
  "lead_id": "ld_abc123",
  "updated": 0,
  "attributes": {},
  "account_linked": true
}

Both operations can be combined in a single request:

curl -X PATCH "https://api.kenbun.io/lead/by-alias/metadata" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias_value": "alex@example.com",
    "attributes": {
      "title": "VP Marketing",
      "linkedin_url": "https://linkedin.com/in/alexjohnson"
    },
    "account_id": "acct_abc123"
  }'

Common Errors​

StatusMeaningSolution
400Missing alias_value, or neither attributes nor account_id provided, or invalid attribute keyCheck that alias_value is provided, at least one of attributes or account_id is included, and all attribute keys follow the naming rules above
401UnauthorizedCheck your API credentials or bearer token
404No lead found for this aliasVerify the email exists as a lead alias in the active OU
413Metadata payload too largeReduce the number or size of attributes in a single request

Notes​

  • Both endpoints are OU-scoped to the active Organizational Unit. The lead must exist within your current OU.
  • The PATCH endpoint performs a partial merge -- existing metadata fields not included in the request are preserved unchanged.
  • Updates via this endpoint are silent: they do not create an event in the lead's activity timeline. This keeps profile annotations separate from behavioral engagement data.
  • Account linking via account_id is non-fatal -- if the account association fails, the metadata update still succeeds and account_linked will be false in the response.
  • The kind parameter currently supports email. Additional alias types may be added in the future.