Leads

The Leads API lets you capture, enrich, and manage inbound leads collected from Onlive flows, forms, and integrations. A lead bundles contact information with device, location, origin, and interaction history so agents can qualify and route it to the right user group.

🔐 Authentication

All Leads API endpoints require authentication using the ONLIVESITE authentication scheme. Include the following header in all requests:

Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📌 Available Endpoints

Lead Management

• Create Lead - Record a new lead
• Get Lead - Retrieve a specific lead by ID (includes devices, locations, origins, interactions, historics)
• List Leads - Paginated list with filtering (origin, status, labels, date range, extra fields)
• Update Lead - Modify a lead's fields (partial)
• Delete Lead - Permanently remove a lead

💡 Common Use Cases

• Capturing leads from contact forms and flow stages
• Enriching leads with device, location, and origin metadata
• Qualifying leads (qualification score 0-1) before handoff
• Routing leads to a user group via userGroupId
• Filtering lead pipelines by labels, status, or custom fields
• Forwarding leads to downstream integrations (sentToIntegration)

For detailed information about specific operations, please refer to the individual endpoint documentation sections.

API requests are subject to rate limiting to ensure optimal performance. Please contact our support team for your specific rate limits.

🔄 Lead Lifecycle

1. Capture: A lead is created via flow, form, or integration with status: created
2. Enrichment: Device, location, origin, and historic records are attached
3. Qualification: qualification score is updated as agents work the lead
4. Routing: Lead is assigned to a user group or set of actors (actorIds)
5. Handoff: Once qualified, sentToIntegration is flipped and the lead is forwarded downstream
6. Deletion: When no longer needed, the lead can be deleted (permanent)

🔌 Integration with Other Services

• Flows: Leads are typically produced by Onlive flow stages
• CRM / Downstream: sentToIntegration indicates the lead has been pushed to the integration pipeline
• Device / Location / Origin: Sub-entities captured at lead creation time

🔐 Security Considerations

• All API endpoints require proper authentication (ONLIVESITE scheme)
• Operations are restricted based on organization membership and user permissions
• Leads are isolated between organizations
• The organizationId is derived from the authenticated security context

🧰 Development Tips

• phone XOR email is required (one of the two must be provided)
• labels cannot contain special characters
• Use date filters (startDate / endDate + timezone) for time-windowed queries
• Set excludeTest=true to filter out test records
• Default page size is 10

Errors

Common error responses:

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Missing or invalid authentication
404	Not Found - Requested resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong