Create Contact Request

This endpoint creates a new contact request associated with your organization. It is typically invoked by a flow stage, a form submission, or directly by your integration.

🔹 Endpoint Details

POST /api/v1/contact-requests

🔒 Authentication

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

📝 Request Body

Field	Type	Required	Description
organizationId	string (UUID)	Yes	UUID of the organization the request belongs to
type	enum	Yes	One of: contactmeback, keepmeinformed
status	enum	Yes	One of: pending, accepted, rejected
preferredContact	enum	Yes	One of: email, phone, whatsapp
name	string	No	Name associated with the request
email	string	No	Email address (validated against RFC format when present)
phone	string	No	Phone number (free-form, E.164 recommended)
message	string	No	Free-form message
relatedService	string (UUID)	No	Service the request relates to
extraFields	object	No	Custom metadata bag for integration-specific data
agentId	string (UUID)	No	Agent assigned to the request
agentComment	string	No	Comment from the agent
userGroupId	string (UUID)	No	User group this request is assigned to
taxonomies	array of strings	No	Free-form taxonomy tags (e.g. ["/model/contact-request"])
externalId	string	No	External identifier from the upstream integration (e.g. Dilema form id)
createdAt	date (ISO 8601)	No	Optional client-supplied creation timestamp

📤 Request Example

curl -X POST "https://openapi.onlive.site/api/v1/contact-requests" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "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",
  "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "agentId": "e4567-e89b-12d3-a456-426614174000",
  "agentComment": "Forwarded to sales team",
  "taxonomies": [
    "/model/contact-request"
  ],
  "extraFields": {
    "department": "Sales",
    "location": "New York"
  },
  "externalId": "frm_abc123"
}'

📥 Response

Success Response (201 Created)

Field	Type	Description
id	string (UUID)	Unique identifier for the newly created request
organizationId	string (UUID)	Organization ID
organizationName	string	Denormalized organization name
type	enum	Contact request type
status	enum	Contact request status
preferredContact	enum	Preferred contact method
name	string	Contact name
email	string	Contact email
phone	string	Contact phone
message	string	Free-form message
relatedService	string (UUID)	Related service ID
extraFields	object	Custom metadata
agentId	string (UUID)	Assigned agent ID
agentComment	string	Comment from the agent
userGroupId	string (UUID)	Assigned user group ID
userGroup	string	Denormalized user group name
taxonomies	array of strings	Taxonomy tags
externalId	string	External identifier
communicationLogs	array of objects	Communication log entries (empty on create)
countCommunicationLogs	number	Number of communication logs
createdAt	string (ISO 8601)	Creation timestamp
updatedAt	string (ISO 8601)	Last update timestamp

Response Example

{
  "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",
    "location": "New York"
  },
  "agentId": "e4567-e89b-12d3-a456-426614174000",
  "agentComment": "Forwarded to sales team",
  "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"
}

❌ Error Responses

This endpoint follows the standard error format.

🔍 Validation Rules

1. Required fields
   • organizationId, type, status, preferredContact must be provided
2. Enum values
   • type ∈ keepmeinformed
   • status ∈ rejected
   • preferredContact ∈ whatsapp
3. Format
   • organizationId, userGroupId, agentId, relatedService must be valid UUIDs
   • email must be a valid email address (when provided)
   • createdAt accepts ISO 8601 strings and is converted to a Date

💡 Best Practices

1. Capture
   • Always send organizationId and at least one contact channel (email or phone)
   • Use externalId to link to your upstream form system
2. Classification
   • Set taxonomies (e.g. ["/model/contact-request"]) so flows can filter by source
   • Use extraFields for integration-specific data you need to round-trip
3. Routing
   • Pre-assign userGroupId / agentId when the source already knows the owner

📘 Notes

• The organizationId must match an organization accessible by your credentials
• communicationLogs and countCommunicationLogs are server-managed and returned empty on create
• The server enforces ownership — requests cannot be created on behalf of other organizations

✅ Common Use Cases

• 📝 Form Submissions: Capture leads from a "Contact me" form
• 🔁 Flow Integrations: Persist requests generated by an Onlive flow stage
• 🧩 CRM Sync: Forward requests to an external CRM via externalId
• 📨 Newsletter Signup: Use type: keepmeinformed for opt-in subscriptions