Lead Insights

Insights (internally audience segments) are structured data fields the AI extracts from each conversation — budget, city, interests, and so on. Extracted values are stored on the contact under lead_segments. Each insight has:

• key — unique id, must match ^[a-zA-Z][a-zA-Z0-9_]*$. Immutable after creation. Addresses the insight.
• name — human-friendly display name.
• valueType — text, number, array (multiple values), or date. Number values are stored as numbers. Date values are extracted as YYYY-MM-DD (relative dates such as "next Friday" are resolved against today in the organisation's timezone) and stored on the contact as a calendar date at UTC midnight, so they can be range-filtered on the Leads page.
• options — optional list of expected values, passed to the AI as guidance (not enforced as a strict enum); leave empty for free-form.
• description — guides what the AI should extract.

If a person edits an insight value on a contact by hand (in the dashboard or Teambox), that key is locked for that contact and AI categorization will not overwrite it. Choosing "Let AI update" on the contact hands the key back to the AI.

List insights

curl -X GET "https://api.sendiee.com/v2.0/leads/insights" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "key": "budget",
      "name": "Budget",
      "valueType": "text",
      "options": [],
      "description": "The customer's stated budget."
    },
    {
      "key": "interests",
      "name": "Interests",
      "valueType": "array",
      "options": [],
      "description": "Topics the customer cares about."
    }
  ],
  "meta": {
    "total": 2
  }
}

Get a single insight

curl -X GET "https://api.sendiee.com/v2.0/leads/insights/budget" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "key": "budget",
    "name": "Budget",
    "valueType": "text",
    "options": [],
    "description": "Stated budget."
  }
}

Create an insight

curl -X POST "https://api.sendiee.com/v2.0/leads/insights" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "budget",
    "name": "Budget",
    "valueType": "text",
    "description": "The customer's stated budget for the purchase."
  }'

{
  "success": true,
  "data": {
    "key": "budget",
    "name": "Budget",
    "valueType": "text",
    "options": [],
    "description": "The customer's stated budget for the purchase."
  }
}

{
  "error": true,
  "code": "INSIGHT_EXISTS",
  "message": "An insight with this key already exists."
}

Update an insight

Update name, valueType, options or description. The key is immutable — to rename it, delete and recreate.

curl -X PATCH "https://api.sendiee.com/v2.0/leads/insights/budget" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "valueType": "array", "options": ["low", "medium", "high"] }'

{
  "success": true,
  "data": {
    "key": "budget",
    "name": "Budget",
    "valueType": "array",
    "options": [
      "low",
      "medium",
      "high"
    ],
    "description": "Stated budget."
  }
}

Delete an insight

curl -X DELETE "https://api.sendiee.com/v2.0/leads/insights/budget" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "deleted": true
  }
}