Get Lead

Retrieve detailed information about a specific lead by its ID, including all sub-entities (devices, locations, origins, interactions, historics).

🔹 Endpoint Details

GET /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	Unique identifier of the lead

🧩 Request Example

curl -X GET "https://openapi.onlive.site/api/v1/leads/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📥 Response Format (HTTP 200)

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

Field	Type	Description
id	string (UUID)	Unique identifier
organizationId	string (UUID)	Owning organization
organizationName	string	Denormalized organization name
name / firstName / lastName	string	Lead name parts
phone	string	Lead's phone
email	string	Lead's email
status	enum	Lead status
userGroupId	string (UUID)	Assigned user group
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)	Qualification score
sentToIntegration	boolean	Forwarded to integration
externalId	string	External identifier
device / location / origin	string (UUID)	Primary record IDs
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

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",
  "actorIds": ["123e4567-e89b-12d3-a456-426614174002"],
  "labels": ["hotlead", "enterprise"],
  "extraFields": { "source": "landing-page" },
  "qualification": 0.75,
  "sentToIntegration": false,
  "externalId": "frm_abc123",
  "device": "123e4567-e89b-12d3-a456-426614174003",
  "location": "123e4567-e89b-12d3-a456-426614174004",
  "origin": "123e4567-e89b-12d3-a456-426614174005",
  "locations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174004",
      "ipv4": "203.0.113.42",
      "countryName": "France",
      "countryCode": "FR",
      "city": "Paris"
    }
  ],
  "devices": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174003",
      "type": "mobile",
      "osName": "iOS",
      "osVersion": "17.2.1",
      "browserName": "Safari"
    }
  ],
  "origins": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174005",
      "origin": "Website contact form",
      "direction": "inbound",
      "type": "form"
    }
  ],
  "interactions": [],
  "historics": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174006",
      "description": "Lead submitted the contact form"
    }
  ],
  "createdAt": "2025-05-13T15:00:00Z",
  "updatedAt": "2025-05-13T15:00:00Z"
}

❌ Error Responses

Status	Description
404	Lead not found

This endpoint follows the standard error format.

📘 Notes

• The lead must belong to your organization
• Sub-entity lists are server-populated
• organizationId and userId (deprecated) are accepted on input for backward compatibility but the server enforces ownership

✅ Common Use Cases

• 🔍 Detail View: Open a single lead in an agent dashboard
• 🔁 Sync: Refresh a local cache after a webhook
• 🧾 Audit: Fetch a lead for compliance review
• 📊 Qualification: Read the qualification score for routing decisions