Create Lead

This endpoint creates a new lead 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/leads

🔒 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
phone	string	Conditional	Lead's phone number. Required when email is not provided
email	string (email)	Conditional	Lead's email address. Required when phone is not provided
name	string	No	Lead's full name
firstName	string	No	Lead's first name
lastName	string	No	Lead's last name
userGroupId	string (UUID)	No	UUID of the user group the lead is routed to
labels	array of strings	No	Free-form labels (no special characters)
extraFields	object	No	Custom metadata bag
location	object	No	Geo location captured at lead capture time
device	object	No	Device fingerprint captured at lead capture time
origin	object	No	Origin information captured at lead capture time
status	string	No	Lead status label (currently only created)
organizationId	string (UUID)	No	Deprecated — server derives from the security context
userId	string (UUID)	No	Deprecated — use actorIds via update for multi-agent assignment

📤 Request Example

curl -X POST "https://openapi.onlive.site/api/v1/leads" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "<[email protected]>",
  "phone": "+33612345678",
  "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    "hotlead",
    "enterprise"
  ],
  "extraFields": {
    "source": "landing-page",
    "campaign": "spring-2026"
  },
  "location": {
    "country": "FR",
    "city": "Paris"
  },
  "device": {
    "type": "mobile",
    "os": "iOS"
  },
  "origin": {
    "name": "Website contact form",
    "channel": "web"
  }
}'

📥 Response

Success Response (201 Created)

Field	Type	Description
id	string (UUID)	Unique identifier for the newly created lead
organizationId	string (UUID)	Organization ID
organizationName	string	Denormalized organization name
name	string	Lead's full name
firstName	string	Lead's first name
lastName	string	Lead's last name
phone	string	Lead's phone
email	string	Lead's email
status	enum	Lead status
userGroupId	string (UUID)	Assigned user group ID
userGroup	string	Denormalized user group name
actorIds	array of strings	Assigned agent IDs
labels	array of strings	Labels
extraFields	object	Custom metadata
qualification	number (0-1)	Lead qualification score
sentToIntegration	boolean	Whether the lead has been forwarded to integration
externalId	string	External identifier
device	string (UUID)	Primary device ID
location	string (UUID)	Primary location ID
origin	string (UUID)	Primary origin ID
locations	array of objects	All location records
devices	array of objects	All device records
origins	array of objects	All origin records
interactions	array of objects	All interactions
historics	array of objects	Historic events
createdAt	string (ISO 8601)	Creation timestamp
updatedAt	string (ISO 8601)	Last update timestamp

See Lead Properties for the full schema and sub-entity structures.

Response Example

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "organizationName": "Acme Inc.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+33612345678",
  "email": "[email protected]",
  "status": "created",
  "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "userGroup": "Sales Team",
  "labels": ["hotlead", "enterprise"],
  "extraFields": { "source": "landing-page" },
  "qualification": 0,
  "sentToIntegration": false,
  "locations": [],
  "devices": [],
  "origins": [],
  "interactions": [],
  "historics": [],
  "createdAt": "2025-05-13T15:00:00Z",
  "updatedAt": "2025-05-13T15:00:00Z"
}

❌ Error Responses

This endpoint follows the standard error format.

🔍 Validation Rules

1. Contact channel
   • At least one of phone or email must be provided
   • email is lowercased and validated against RFC format when present
   • phone whitespace is stripped when present
2. Format
   • userGroupId must be a valid UUID
   • organizationId / userId (deprecated) must be valid UUIDs when present
3. Labels
   • Cannot contain special characters: ^ ` ~ ! @ # $ % ^ & * ( ) | + - = ? ; : ' " , . < > { } [ ] \ / and spaces
4. Objects
   • extraFields, location, device, origin must be objects when present

💡 Best Practices

1. Contact
   • Always send at least email or phone — never both empty
   • Send name + firstName/lastName when available to enrich the lead
2. Capture context
   • Use location, device, origin to enrich at lead capture time
   • Use extraFields for integration-specific data
3. Classification
   • Set labels (no special chars) for filtering and routing
   • Pre-assign userGroupId to route the lead to the right team
4. Avoid deprecated fields
   • Do not send organizationId (server-derived)
   • Do not send userId (use actorIds via update)

📘 Notes

• The organizationId is enforced server-side from the security context
• sentToIntegration defaults to false
• qualification defaults to 0
• Sub-entity lists (locations, devices, origins, interactions, historics) are server-populated

✅ Common Use Cases

• 📝 Form Submissions: Capture leads from a "Contact us" form
• 🔁 Flow Integrations: Persist leads generated by an Onlive flow stage
• 🧩 CRM Sync: Use externalId to link with your CRM
• 📊 Segmentation: Apply labels to segment by source or campaign