Contact Requests

The Contact Requests API lets you capture, manage, and triage inbound lead-generation requests submitted through Onlive flows (e.g. "Contact me back", "Keep me informed"). Endpoints support creating a request, paginated listing with filters, retrieving a single request, updating its status, and deletion.

🔐 Authentication

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

Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📌 Available Endpoints

Contact Request Management

• Create Contact Request - Record a new contact request
• Get Contact Request - Retrieve a specific contact request by ID
• List Contact Requests - Paginated list with filtering (type, status, user, service, taxonomies, extra fields)
• Update Contact Request - Modify a contact request's fields (partial)
• Delete Contact Request - Permanently remove a contact request

💡 Common Use Cases

• Capturing leads from contact forms and "call-me-back" widgets
• Triaging incoming requests by status (pending → accepted / rejected)
• Routing requests to specific agents or user groups
• Syncing contact requests with downstream CRMs
• Filtering and exporting requests by taxonomy, service, or custom fields

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.

🔄 Contact Request Lifecycle

1. Submission: A contact request is created (typically by a flow stage) with status: pending
2. Triage: An agent reviews the request and updates status to accepted or rejected
3. Follow-up: Communication logs (communicationLogs) accumulate as agents reach the contact
4. Assignment: Request can be assigned via agentId / userGroupId
5. Deletion: When no longer needed, the request can be deleted (permanent)

🔌 Integration with Other Services

• Communication Logs: Each request maintains an audit trail of messages and calls
• Flows: Contact requests are typically produced by Onlive flow stages
• Services: Requests can be linked to a specific service via relatedService
• User Groups: Requests can be scoped to a user group for routing
• Taxonomies: Free-form tags for categorization (/model/contact-request, etc.)

🔐 Security Considerations

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

🧰 Development Tips

• Use status filtering on list endpoints to build agent dashboards
• Use taxonomies to segment requests by source or campaign
• Leverage extraFields to store integration-specific metadata (e.g. Dilema form id)
• Paginate list requests — 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