List Lost Opportunities

Retrieve a paginated list of lost opportunities for your organization with optional filtering.

🔹 Endpoint Details

GET /api/v1/lost-opportunities

🔒 Authentication

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

📝 Query Parameters

Parameter	Type	Required	Description	Default
page	number	No	Page number for pagination	1
limit	number	No	Number of items per page	10
entityType	enum	No	Filter by channel. One of: iCall, iChat, booking	-
status	enum	No	Filter by status. One of: pending, processed, rejected	-
userId	string (UUID)	No	Filter by user ID	-
extraFields	object	No	Filter by custom field values (exact-match on the JSON bag)	-

🧩 Request Examples

Basic list

curl -X GET "https://openapi.onlive.site/api/v1/lost-opportunities?page=1&limit=10" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Filter by channel and status

curl -X GET "https://openapi.onlive.site/api/v1/lost-opportunities?entityType=iCall&status=pending&page=1&limit=20" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Filter by user and extra fields

curl -X GET "https://openapi.onlive.site/api/v1/lost-opportunities?userId=123e4567-e89b-12d3-a456-426614174000&extraFields[department]=Sales" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📥 Response Format (HTTP 200)

Field	Type	Description
items	array	Array of Lost Opportunity objects
total	number	Total number of items matching the query
count	number	Number of items in the current page
totalPages	number	Total number of pages
currentPage	number	Current page number

Response Example

{
  "items": [
    {
      "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-13T16:42:11Z"
    }
  ],
  "total": 1,
  "count": 1,
  "totalPages": 1,
  "currentPage": 1
}

❌ Error Responses

This endpoint follows the standard error format.

📘 Notes

• Default pagination is page=1, limit=10
• entityType and status are case-sensitive strings
• extraFields matches on the full JSON bag
• Results are scoped to the caller's organization
• Only records visible to your security context are returned

💡 Best Practices

1. Pagination
   • Use page and limit for large result sets
2. Filtering
   • Combine entityType + status to build channel- and state-specific views
   • Use userId to scope to a specific agent's queue
   • Use extraFields for channel-specific segmentation
3. Performance
   • Apply the most selective filter first
   • Avoid fetching all pages when an entityType + status filter suffices

✅ Common Use Cases

• 🗂️ Agent Inbox: List pending lost opportunities for a user group
• 📊 Dashboards: Aggregate counts by entityType or status
• 📞 Channel Analytics: Compare loss rates across iCall, iChat, booking
• 📤 Exports: Pull filtered records for offline processing