Update Lost Opportunity

Update an existing lost opportunity. Only the fields included in the request body are modified; omitted fields retain their current values.

🔹 Endpoint Details

PUT /api/v1/lost-opportunities/{id}

🔒 Authentication

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

📝 Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	ID of the lost opportunity to update

📝 Updatable Fields

All fields are optional on update (the body is validated with PartialType of the create DTO).

Field	Type	Description
organizationId	string (UUID)	Organization the record belongs to
entityType	enum	iCall | iChat | booking
interactionId	string	Source interaction identifier
status	enum	pending | processed | rejected
reason	string	Loss reason
userGroupId	string (UUID)	Assigned user group
comment	string	Free-form comment
origin	string	Origin name
userEmail	string	Contact email
userPhone	string	Contact phone
extraFields	object	Custom metadata bag
externalId	string	External identifier

🧩 Request Example

curl -X PUT "https://openapi.onlive.site/api/v1/lost-opportunities/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "status": "processed",
  "reason": "Customer chose a competitor",
  "comment": "Customer asked to be contacted again in Q3"
}'

📥 Response

Success Response (200 OK)

Returns the full updated Lost Opportunity entity.

Response Example

{
  "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" },
  "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-13T17:22:11Z"
}

❌ Error Responses

Status	Description
404	Lost opportunity not found

This endpoint follows the standard error format.

🔍 Validation Rules

1. Partial update
   • Any subset of the create DTO fields may be sent; omitted fields are preserved
2. Format
   • UUIDs must be valid when provided
   • userEmail must be a valid email when provided
3. Enum values (when provided)
   • entityType ∈ booking
   • status ∈ rejected (DTO does not accept draft)

💡 Best Practices

1. Status transitions
   • pending → processed / rejected once an agent triages the record
2. Reasoning
   • Update reason and comment together to record a complete loss analysis
3. Classification
   • Use extraFields to enrich records over time
4. Audit
   • Prefer small, focused updates — each one updates updatedAt

📘 Notes

• Only the fields you include are updated
• The updatedAt timestamp is refreshed automatically
• involvedAgent, organizationName, userGroup, and visibleAt are server-managed
• You must have access to the owning organization

✅ Common Use Cases

• ✅ Triage: Move a record from pending to processed / rejected
• 📝 Reasoning: Update reason and comment after analyzing the loss
• 🏷️ Classification: Enrich extraFields with additional context
• 👤 Routing: Reassign the record via userGroupId