Update Lead

Update an existing lead. Only the fields included in the request body are modified; omitted fields retain their current values.

🔹 Endpoint Details

PUT /api/v1/leads/{id}

🔒 Authentication

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

📝 Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	ID of the lead to update

📝 Updatable Fields

All fields are optional on update (the body is validated with PartialType of the create DTO).

Field	Type	Description
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 (email)	Lead's email
userGroupId	string (UUID)	User group the lead is routed to
labels	array of strings	Free-form labels (no special characters)
extraFields	object	Custom metadata bag
location	object	Geo location captured at lead capture time
device	object	Device fingerprint captured at lead capture time
origin	object	Origin information captured at lead capture time
status	string	Lead status label (currently only created)
organizationId	string (UUID)	Deprecated — server-derived; kept for backward compatibility
userId	string (UUID)	Deprecated — kept for backward compatibility

Server-managed fields like qualification, sentToIntegration, actorIds, sub-entity IDs, and timestamps are not directly updatable via this endpoint. Use integration-specific endpoints to modify them.

🧩 Request Example

curl -X PUT "https://openapi.onlive.site/api/v1/leads/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    "hotlead",
    "qualified"
  ],
  "extraFields": {
    "source": "landing-page",
    "campaign": "spring-2026"
  }
}'

📥 Response

Success Response (200 OK)

Returns the full updated Lead entity.

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", "qualified"],
  "extraFields": { "source": "landing-page", "campaign": "spring-2026" },
  "qualification": 0.75,
  "sentToIntegration": false,
  "locations": [],
  "devices": [],
  "origins": [],
  "interactions": [],
  "historics": [],
  "createdAt": "2025-05-13T15:00:00Z",
  "updatedAt": "2025-05-13T16:42:11Z"
}

❌ Error Responses

Status	Description
404	Lead not found

This endpoint follows the standard error format.

🔍 Validation Rules

1. Partial update
   • Any subset of the create DTO fields may be sent; omitted fields are preserved
2. Format
   • UUIDs must be valid when provided
   • email must be a valid email when provided
3. Labels
   • Cannot contain special characters when provided
4. Objects
   • extraFields, location, device, origin must be objects when provided

💡 Best Practices

1. Routing
   • Update userGroupId to re-route a lead
2. Classification
   • Add or replace labels to reflect the lead's current stage
   • Enrich extraFields as you learn more about the lead
3. Contact updates
   • Update phone / email when the lead provides new contact info
4. Audit
   • Prefer small, focused updates — each one updates updatedAt

📘 Notes

• Only the fields you include are updated
• The updatedAt timestamp is refreshed automatically
• Server-managed fields (qualification, sentToIntegration, actorIds, sub-entity IDs) cannot be set via this endpoint
• You must have access to the owning organization

✅ Common Use Cases

• 🏷️ Reclassification: Update labels as the lead progresses
• 👥 Routing: Reassign userGroupId to a different team
• 📞 Contact updates: Capture a new phone or email
• 📝 Enrichment: Add extraFields with additional context