Lead Properties

This page defines the structure of the lead entity and its sub-entities (Device, Location, Origin, Interaction, Historic). Server-managed fields are read-only.

🔹 Lead — Identity

Property	Type	Required	Read-Only	Description	Example
`id`	string (UUID)	No	Yes	Unique identifier for the lead	`"123e4567-e89b-12d3-a456-426614174000"`
`organizationId`	string (UUID)	No	Yes	UUID of the owning organization (deprecated on input, server-derived)	`"123e4567-e89b-12d3-a456-426614174001"`
`organizationName`	string	No	Yes	Denormalized organization name	`"Acme Inc."`
`userGroupId`	string (UUID)	No	No	User group the lead is routed to	`"550e8400-e29b-41d4-a716-446655440000"`
`userGroup`	string	No	Yes	Denormalized user group name	`"Sales Team"`
`externalId`	string	No	No	External identifier from the upstream integration	`"frm_abc123"`

🔹 Lead — Identity & Status

Property	Type	Required	Read-Only	Description	Example
`name`	string	No	No	Lead's full name	`"John Doe"`
`firstName`	string	No	No	Lead's first name	`"John"`
`lastName`	string	No	No	Lead's last name	`"Doe"`
`phone`	string	Conditional	No	Lead's phone number; required when `email` is not provided	`"+33612345678"`
`email`	string (email)	Conditional	No	Lead's email address; required when `phone` is not provided	`"[email protected]"`
`status`	enum	No	No	Lead status. Currently only `created`	`"created"`
`subStatus`	string	No	No	Lead sub-status (free-form)	`"qualified"`
`actorIds`	array of strings (UUIDs)	No	No	UUIDs of the agents (actors) associated with the lead	`["123e4567-e89b-12d3-a456-426614174000"]`

🔹 Lead — Classification

Property	Type	Required	Read-Only	Description	Example
`labels`	array of strings	No	No	Free-form labels (no special characters)	`["hotlead", "enterprise"]`
`extraFields`	object	No	No	Custom metadata bag	`{ "source": "landing-page" }`
`qualification`	number (0-1)	No	No	Lead qualification score	`0.75`
`sentToIntegration`	boolean	No	No	Whether the lead has been forwarded to the integration pipeline	`false`

🔹 Lead — Embedded Records (IDs)

These fields hold the identifier of the primary embedded record (singular).

Property	Type	Required	Read-Only	Description	Example
`device`	string (UUID)	No	No	Identifier of the primary device	`"123e4567-e89b-12d3-a456-426614174002"`
`location`	string (UUID)	No	No	Identifier of the primary location	`"123e4567-e89b-12d3-a456-426614174003"`
`origin`	string (UUID)	No	No	Identifier of the primary origin	`"123e4567-e89b-12d3-a456-426614174004"`

🔹 Lead — Embedded Records (Lists)

These fields hold all embedded records captured for the lead (server-populated).

Property	Type	Required	Read-Only	Description
`locations`	array of Location	No	Yes	All location records captured for the lead
`devices`	array of Device	No	Yes	All device records captured for the lead
`origins`	array of Origin	No	Yes	All origin records captured for the lead
`interactions`	array of Interaction	No	Yes	All interactions recorded for the lead
`historics`	array of Historic	No	Yes	Historic events recorded for the lead

🔹 Lead — Timestamps

Property	Type	Required	Read-Only	Description	Example
`createdAt`	date (ISO 8601)	No	Yes	Creation timestamp	`"2025-05-13T15:00:00Z"`
`updatedAt`	date (ISO 8601)	No	Yes	Last update timestamp	`"2025-05-13T15:00:00Z"`
`deletedAt`	date (ISO 8601)	No	Yes	Deletion timestamp (soft delete)	`null`

🔹 Device

Property	Type	Required	Description	Example
`id`	string (UUID)	No	Unique identifier	`"123e4567-e89b-12d3-a456-426614174000"`
`type`	string	No	Device type (e.g. `desktop`, `mobile`, `tablet`)	`"mobile"`
`browserName`	string	No	Browser name reported by the user agent	`"Chrome"`
`fullBrowserVersion`	string	No	Full browser version string	`"120.0.6099.130"`
`mobileModel`	string	No	Mobile device model when type is mobile	`"iPhone15,2"`
`mobileVendor`	string	No	Mobile device vendor when type is mobile	`"Apple"`
`osName`	string	No	Operating system name	`"iOS"`
`osVersion`	string	No	Operating system version	`"17.2.1"`
`leadId`	string (UUID)	Yes	UUID of the lead this device belongs to	`"123e4567-e89b-12d3-a456-426614174000"`
`createdAt` / `updatedAt` / `deletedAt`	date (ISO 8601)	No	Standard timestamps	-

🔹 Location

Property	Type	Required	Description	Example
`id`	string (UUID)	No	Unique identifier	`"123e4567-e89b-12d3-a456-426614174000"`
`ipv4`	string	No	IPv4 address captured at lead capture time	`"203.0.113.42"`
`countryName`	string	No	Resolved country name from the IP	`"France"`
`countryCode`	string	No	ISO 3166-1 alpha-2 country code	`"FR"`
`state`	string	No	State or region resolved from the IP	`"Île-de-France"`
`city`	string	No	City resolved from the IP	`"Paris"`
`leadId`	string (UUID)	No	UUID of the lead this location belongs to	`"123e4567-e89b-12d3-a456-426614174000"`
`createdAt` / `updatedAt` / `deletedAt`	date (ISO 8601)	No	Standard timestamps	-

🔹 Origin

Property	Type	Required	Description	Example
`id`	string (UUID)	No	Unique identifier	`"123e4567-e89b-12d3-a456-426614174000"`
`origin`	string	No	Origin name or label	`"Website contact form"`
`direction`	string	No	Direction of the lead at this origin (e.g. `inbound`, `outbound`)	`"inbound"`
`channelUrl`	string	No	Channel URL where the lead originated	`"https://example.com/contact"`
`externalId`	string	No	External identifier of the origin in the upstream system	`"ext_abc123"`
`name`	string	No	Display name of the origin	`"Spring Campaign 2026"`
`type`	string	No	Type of origin (e.g. `form`, `call`, `chat`)	`"form"`
`url`	string	No	URL associated with the origin	`"https://example.com/campaigns/spring-2026"`
`interactionId`	string	No	Identifier of the interaction that produced the lead at this origin	`"123e4567-e89b-12d3-a456-426614174000"`
`interactionType`	string	No	Type of the originating interaction (e.g. `iCall`, `iChat`)	`"iCall"`
`admin`	string	No	Identifier of the admin who owns the origin	`"admin_abc123"`
`originDate`	date (ISO 8601)	No	Datetime when the origin record was created	`"2026-05-13T15:00:00Z"`
`leadId`	string (UUID)	Yes	UUID of the lead this origin belongs to	`"123e4567-e89b-12d3-a456-426614174000"`
`createdAt` / `updatedAt` / `deletedAt`	date (ISO 8601)	No	Standard timestamps	-

🔹 Interaction

Property	Type	Required	Description	Example
`id`	string (UUID)	No	Unique identifier	`"123e4567-e89b-12d3-a456-426614174000"`
`type`	string	Yes	Type of interaction (e.g. `iCall`, `iChat`)	`"iCall"`
`interactionId`	string	No	External identifier in the upstream system	`"call_abc123"`
`metadata`	object	No	Free-form metadata captured for the interaction	`{ "duration": 120, "outcome": "voicemail" }`
`leadId`	string (UUID)	Yes	UUID of the lead this interaction belongs to	`"123e4567-e89b-12d3-a456-426614174000"`
`createdAt` / `updatedAt` / `deletedAt`	date (ISO 8601)	No	Standard timestamps	-

🔹 Historic

Property	Type	Required	Description	Example
`id`	string (UUID)	No	Unique identifier	`"123e4567-e89b-12d3-a456-426614174000"`
`description`	string	Yes	Description of the historic event	`"Lead submitted the contact form on the website"`
`leadId`	string (UUID)	Yes	UUID of the lead this event belongs to	`"123e4567-e89b-12d3-a456-426614174000"`
`originId`	string (UUID)	No	UUID of the origin that produced this event	`"123e4567-e89b-12d3-a456-426614174000"`
`metadata`	object	No	Free-form metadata for the event	`{ "source": "web", "campaign": "spring-2026" }`
`createdAt` / `updatedAt` / `deletedAt`	date (ISO 8601)	No	Standard timestamps	-

🧩 Property Details

phone / email: At least one of phone or email must be provided on create (XOR constraint enforced by ValidateIf).
status: Currently a single value created. New statuses may be added; treat as a string in integrations.
labels: Free-form, but cannot contain special characters (^ `` `` ~!@#$%^&*()|+-=?;:'",.<>[]/`).
qualification: 0-1 score; 0 means unqualified, 1 means fully qualified.
sentToIntegration: true once the lead has been pushed to the downstream pipeline; do not re-send.
organizationId: Deprecated on input — server derives from security context. Kept for backward compatibility.
userId: Deprecated on input — use actorIds for multi-agent assignment.

📊 Property Usage Examples

Minimal Lead (email only)

{
  "email": "[email protected]"
}

Complete Lead

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "organizationName": "Acme Inc.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+33612345678",
  "email": "[email protected]",
  "status": "created",
  "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "userGroup": "Sales Team",
  "actorIds": ["123e4567-e89b-12d3-a456-426614174002"],
  "labels": ["hotlead", "enterprise"],
  "extraFields": { "source": "landing-page", "campaign": "spring-2026" },
  "qualification": 0.75,
  "sentToIntegration": false,
  "externalId": "frm_abc123",
  "device": "123e4567-e89b-12d3-a456-426614174003",
  "location": "123e4567-e89b-12d3-a456-426614174004",
  "origin": "123e4567-e89b-12d3-a456-426614174005",
  "locations": [
    {
      "id": "...",
      "ipv4": "203.0.113.42",
      "countryName": "France",
      "countryCode": "FR",
      "city": "Paris"
    }
  ],
  "devices": [
    {
      "id": "...",
      "type": "mobile",
      "osName": "iOS",
      "osVersion": "17.2.1",
      "browserName": "Safari"
    }
  ],
  "origins": [
    {
      "id": "...",
      "origin": "Website contact form",
      "direction": "inbound",
      "type": "form"
    }
  ],
  "interactions": [],
  "historics": [
    { "id": "...", "description": "Lead submitted the contact form" }
  ],
  "createdAt": "2025-05-13T15:00:00Z",
  "updatedAt": "2025-05-13T15:00:00Z"
}

📘 Notes

All timestamps are returned in ISO 8601 format with UTC timezone
The organizationId is enforced server-side from the security context
Sub-entity lists (locations, devices, origins, interactions, historics) are server-populated

🔹 Lead — Identity​

🔹 Lead — Identity & Status​

🔹 Lead — Classification​

🔹 Lead — Embedded Records (IDs)​

🔹 Lead — Embedded Records (Lists)​

🔹 Lead — Timestamps​

🔹 Device​

🔹 Location​

🔹 Origin​

🔹 Interaction​

🔹 Historic​

🧩 Property Details​

📊 Property Usage Examples​

Minimal Lead (email only)​

Complete Lead​

📘 Notes​