Create Lost Opportunity

This endpoint creates a new lost opportunity associated with your organization. It is typically invoked by an integration after an iCall, iChat, or booking interaction fails to convert.

🔹 Endpoint Details

POST /api/v1/lost-opportunities

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Body

Field	Type	Required	Description
organizationId	string (UUID)	Yes	UUID of the organization the record belongs to
entityType	enum	Yes	Channel that produced the lost opportunity. One of: iCall, iChat, booking
interactionId	string	Yes	Identifier of the interaction (iCall, iChat, or booking) that was lost
status	enum	Yes	One of: pending, processed, rejected
reason	string	Yes	Short text describing why the opportunity was lost
userGroupId	string (UUID)	No	User group this record is assigned to
comment	string	No	Free-form comment from the agent or system
origin	string	No	Origin name where the lost opportunity was captured
userEmail	string	No	Email address (validated against RFC format when present)
userPhone	string	No	Phone number (free-form, E.164 recommended)
extraFields	object	No	Custom metadata bag for integration-specific data
externalId	string	No	External identifier from the upstream integration (e.g. Dilema form id)

📤 Request Example

curl -X POST "https://openapi.onlive.site/api/v1/lost-opportunities" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "entityType": "iCall",
  "interactionId": "call_abc123",
  "status": "pending",
  "reason": "Customer chose a competitor",
  "comment": "Customer asked to be contacted again in Q3",
  "origin": "Website contact form",
  "userEmail": "[email protected]",
  "userPhone": "+33612345678",
  "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "extraFields": {
    "department": "Sales",
    "location": "New York"
  },
  "externalId": "frm_abc123"
}'

📥 Response

Success Response (201 Created)

Field	Type	Description
id	string (UUID)	Unique identifier for the newly created record
organizationId	string (UUID)	Organization ID
organizationName	string	Denormalized organization name
entityType	enum	Channel that produced the lost opportunity
interactionId	string	Source interaction identifier
status	enum	Record status
reason	string	Loss reason
comment	string	Free-form comment
origin	string	Origin name
userEmail	string	Contact email
userPhone	string	Contact phone
extraFields	object	Custom metadata
userGroupId	string (UUID)	Assigned user group ID
userGroup	string	Denormalized user group name
involvedAgent	string (UUID)	Agent that handled the interaction
visibleAt	string (ISO 8601)	Datetime the record becomes visible to agents
externalId	string	External identifier
createdAt	string (ISO 8601)	Creation timestamp
updatedAt	string (ISO 8601)	Last update timestamp

Response Example

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "organizationName": "Acme Inc.",
  "entityType": "iCall",
  "interactionId": "call_abc123",
  "status": "pending",
  "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-13T15:00:00Z"
}

❌ Error Responses

This endpoint follows the standard error format.

🔍 Validation Rules

1. Required fields
   • organizationId, entityType, interactionId, status, reason must be provided
2. Enum values
   • entityType ∈ booking
   • status ∈ rejected (DTO does not accept draft)
3. Format
   • organizationId, userGroupId must be valid UUIDs
   • userEmail must be a valid email address (when provided)

💡 Best Practices

1. Capture
   • Always send organizationId, entityType, interactionId, and reason
   • Use externalId to link to your upstream system
2. Reasoning
   • Keep reason short and consistent (e.g. use a fixed vocabulary)
   • Use comment for free-form notes
3. Classification
   • Set origin to track the capture surface (e.g. "Website contact form")
   • Use extraFields for channel-specific metadata

📘 Notes

• The organizationId must match an organization accessible by your credentials
• involvedAgent, organizationName, userGroup, and visibleAt are server-managed
• The server enforces ownership — records cannot be created on behalf of other organizations

✅ Common Use Cases

• 📞 Failed iCall: Capture a missed call as a lost opportunity
• 💬 Dropped iChat: Persist an abandoned chat for follow-up
• 📅 Unfulfilled Booking: Track a booking that did not complete
• 📊 Loss Analytics: Persist a structured reason for reporting