List Contact Requests

Retrieve a paginated list of contact requests for your organization with optional filtering.

🔹 Endpoint Details

GET /api/v1/contact-requests

🔒 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
externalId	string	No	Filter by external identifier (e.g. Dilema form id)	-
type	enum	No	Filter by type. One of: contactmeback, keepmeinformed	-
status	enum	No	Filter by status. One of: pending, accepted, rejected	-
userId	string (UUID)	No	Filter by user ID	-
serviceId	string (UUID)	No	Filter by service ID	-
taxonomies	array of strings	No	Filter by taxonomies (string or array accepted)	-
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/contact-requests?page=1&limit=10" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Filter by status and type

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

Filter by taxonomy and service

curl -X GET "https://openapi.onlive.site/api/v1/contact-requests?taxonomies=/model/contact-request&serviceId=7a96c97a-bcf9-42df-984a-051c0fb8487e" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📥 Response Format (HTTP 200)

Field	Type	Description
items	array	Array of Contact Request 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.",
      "type": "contactmeback",
      "status": "pending",
      "preferredContact": "email",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+33612345678",
      "message": "Please send me a copy of the contract",
      "relatedService": "7a96c97a-bcf9-42df-984a-051c0fb8487e",
      "extraFields": { "department": "Sales" },
      "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
      "userGroup": "Sales Team",
      "taxonomies": ["/model/contact-request"],
      "externalId": "frm_abc123",
      "communicationLogs": [],
      "countCommunicationLogs": 0,
      "createdAt": "2025-05-13T15:00:00Z",
      "updatedAt": "2025-05-13T15:00:00Z"
    }
  ],
  "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
• taxonomies accepts a single string or an array; values are normalized to an array server-side
• extraFields matches on the full JSON bag
• Results are scoped to the caller's organization
• Only contact requests visible to your security context are returned

💡 Best Practices

1. Pagination
   • Use page and limit for large result sets
2. Filtering
   • Combine status + type to build agent triage views
   • Use taxonomies to segment by source model
   • Use userId / serviceId for owner- or product-scoped views
3. Performance
   • Apply the most selective filter first
   • Avoid fetching all pages when a status filter suffices

✅ Common Use Cases

• 🗂️ Agent Inbox: List pending requests for a user group
• 📊 Dashboards: Aggregate counts by status or type
• 🔁 CRM Sync: Iterate pages matching externalId to reconcile
• 📤 Exports: Pull filtered requests for offline processing