Lost Opportunity Properties

This page defines the structure of the lost opportunity entity, including all properties and their descriptions. Server-managed fields are read-only.

🔹 Identity

Property	Type	Required	Read-Only	Description	Example
id	string (UUID)	No	Yes	Unique identifier for the lost opportunity	"123e4567-e89b-12d3-a456-426614174000"
organizationId	string (UUID)	Yes (create)	Yes	UUID of the organization that owns the record	"123e4567-e89b-12d3-a456-426614174001"
organizationName	string	No	Yes	Denormalized organization name	"Acme Inc."
externalId	string	No	No	External identifier from the upstream integration (e.g. Dilema form id)	"frm_abc123"

🔹 Type & Status

Property	Type	Required	Read-Only	Description	Example
entityType	enum	Yes	No	Channel that produced the lost opportunity. One of: iCall, iChat, booking	"iCall"
status	enum	Yes	No	Record status. One of: pending, processed, rejected	"pending"

🔹 Source Interaction

Property	Type	Required	Read-Only	Description	Example
interactionId	string	Yes	No	Identifier of the interaction (iCall, iChat, or booking) that was lost	"123e4567-e89b-12d3-a456-426614174000"
origin	string	No	No	Origin name where the lost opportunity was captured	"Website contact form"
visibleAt	date (ISO 8601)	No	Yes	Datetime from which the lost opportunity becomes visible to agents	"2026-05-13T15:00:00Z"

🔹 Loss Details

Property	Type	Required	Read-Only	Description	Example
reason	string	Yes	No	Reason why the opportunity was lost	"Customer chose a competitor"
comment	string	No	No	Free-form comment from the agent or system	"Customer asked to be contacted again in Q3"

🔹 Contact

Property	Type	Required	Read-Only	Description	Example
userEmail	string (email)	No	No	Email address associated with the lost opportunity	"[email protected]"
userPhone	string	No	No	Phone number associated with the lost opportunity	"+33612345678"

🔹 Routing & Assignment

Property	Type	Required	Read-Only	Description	Example
userGroupId	string (UUID)	No	No	User group this record is assigned to	"550e8400-e29b-41d4-a716-446655440000"
userGroup	string	No	Yes	Denormalized user group name	"Sales Team"
involvedAgent	string (UUID)	No	Yes	UUID of the agent involved in the lost opportunity	"123e4567-e89b-12d3-a456-426614174000"

🔹 Classification

Property	Type	Required	Read-Only	Description	Example
extraFields	object	No	No	Custom metadata bag for integration-specific data	{ "department": "Sales", "location": "New York" }

🔹 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

🧩 Property Details

• id: UUID generated by the server. Cannot be modified.
• organizationId: Server-derived from the security context on create. Pass on create for clarity, but the server enforces ownership.
• entityType: Identifies the originating channel. iCall for failed calls, iChat for dropped chats, booking for unfulfilled bookings.
• status: Default pending. The DTO does not accept draft (reserved for internal use).
• interactionId: Free-form string identifier of the source interaction. Not constrained to UUID.
• reason: Short text describing why the opportunity was lost. Use a controlled vocabulary in your integration for analytics.
• userEmail: Validated against RFC email format only when provided.
• involvedAgent: Server-populated; identifies the agent that handled the interaction.
• visibleAt: Server-managed; controls when the record becomes visible to agents.

📊 Property Usage Examples

Basic Lost Opportunity

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "entityType": "iCall",
  "interactionId": "call_abc123",
  "status": "pending",
  "reason": "No answer"
}

Complete Lost Opportunity

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "organizationName": "Acme Inc.",
  "entityType": "iCall",
  "interactionId": "call_abc123",
  "status": "processed",
  "reason": "Customer chose a competitor",
  "comment": "Customer asked to be contacted again in Q3",
  "origin": "Website contact form",
  "userEmail": "[email protected]",
  "userPhone": "+33612345678",
  "extraFields": {
    "department": "Sales",
    "location": "New York"
  },
  "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "userGroup": "Sales Team",
  "involvedAgent": "123e4567-e89b-12d3-a456-426614174002",
  "visibleAt": "2025-05-13T15:00:00Z",
  "externalId": "frm_abc123",
  "createdAt": "2025-05-13T15:00:00Z",
  "updatedAt": "2025-05-13T16:42:11Z"
}

📘 Notes

• All timestamps are returned in ISO 8601 format with UTC timezone
• Enum values are case-sensitive strings
• The organizationId is enforced server-side from the security context
• involvedAgent, organizationName, userGroup, and visibleAt are server-managed