LeadTruffle Public API (1.0.0)

Retrieve a specific lead by its UUID

Update the conversion status and notes for a specific lead.

This endpoint allows you to track the progress of leads through your sales funnel by updating their conversion status and adding notes for internal tracking.

Conversion Status Values:

• NEW: Just qualified (default status)
• CONTACTED: Sales team has reached out to the lead
• QUOTED: Quote or estimate has been provided
• WON: Lead converted to customer/sale closed
• LOST: Lead did not convert/sale was lost
• NURTURING: Lead is in long-term follow-up process
• CLOSED: Lead is closed and no longer being pursued

The status update timestamp is automatically recorded for tracking purposes.

Add a new webhook URL for missed call lead completion notifications.

When a lead conversation is completed, we will POST the payload described below to your webhook URL. The webhook will timeout after 10 seconds and we will retry failed deliveries up to 3 times with exponential backoff.

Webhook Payload Example

{
  "type": "conversation_completed",
  "clientId": "456",
  "leadId": "123",
  "companyId": "789",
  "leadQualificationStatus": "COMPLETED",
  "leadInformation": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+18001234567",
    "additionalData": {
      "source": "popup",
      "message": "I need help with..."
    }
  },
  "trackingData": {
    "source": "popup",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "home_renovation",
    "pageInfo": {
      "title": "Home - Best HVAC Services",
      "referrer": "https://www.google.com/",
      "currentUrl": "http://localhost:3002/index.html"
    }
  },
  "qualifyingData": {
    "example_budget": "$5000",
    "example_timeline": "Within 3 months",
    "example_projectType": "Home Renovation"
  },
  "commonFields": {
    "fullAddress": "111 main st, Austin TX 73301",
    "address": "111 main st",
    "zipcode": "73301",
    "state": "TX",
    "city": "Austin",
    "country": "US",
    "isHomeowner": true,
    "customerName": "John"
  },
  "qualifyingDataSummary": "The client lives in a 3 bedroom house.\nHas a budget of $2000.\nzipcode is 45150.",
  "contactReason": "Client is interested in a home renovation project...",
  "timestamp": "2024-01-01T00:00:00Z",
  "messageHistory": [
    {
      "direction": "outbound",
      "name": "AI Agent",
      "message": "How can we help you...",
      "date": "2024-01-01T00:00:00Z"
    },
    {
      "direction": "inbound",
      "name": "John Doe",
      "message": "I need help with...",
      "date": "2024-01-01T00:01:00Z"
    }
  ],
  "userMedia": [
    {
      "type": "image/jpeg",
      "url": "https://tooldesk-public-user-uploads.s3.us-west-2.amazonaws.com/email-assets/leadtruffle-Wordmark-white.png"
    }
  ]
}

Remove an existing webhook URL for missed call lead completion notifications

Add a new webhook URL for chat widget lead completion notifications.

When a lead conversation is completed, we will POST the payload described below to your webhook URL. The webhook will timeout after 10 seconds and we will retry failed deliveries up to 3 times with exponential backoff.

Webhook Payload Example

{
  "type": "conversation_completed",
  "clientId": "456",
  "leadId": "123",
  "companyId": "789",
  "leadQualificationStatus": "COMPLETED",
  "leadInformation": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+18001234567",
    "additionalData": {
      "source": "popup",
      "message": "I need help with..."
    }
  },
  "trackingData": {
    "source": "popup",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "home_renovation",
    "pageInfo": {
      "title": "Home - Best HVAC Services",
      "referrer": "https://www.google.com/",
      "currentUrl": "http://localhost:3002/index.html"
    }
  },
  "qualifyingData": {
    "example_budget": "$5000",
    "example_timeline": "Within 3 months",
    "example_projectType": "Home Renovation"
  },
  "commonFields": {
    "fullAddress": "111 main st, Austin TX 73301",
    "address": "111 main st",
    "zipcode": "73301",
    "state": "TX",
    "city": "Austin",
    "country": "US",
    "isHomeowner": true,
    "customerName": "John"
  },
  "qualifyingDataSummary": "The client lives in a 3 bedroom house.\nHas a budget of $2000.\nzipcode is 45150.",
  "contactReason": "Client is interested in a home renovation project...",
  "timestamp": "2024-01-01T00:00:00Z",
  "messageHistory": [
    {
      "direction": "outbound",
      "name": "AI Agent",
      "message": "How can we help you...",
      "date": "2024-01-01T00:00:00Z"
    },
    {
      "direction": "inbound",
      "name": "John Doe",
      "message": "I need help with...",
      "date": "2024-01-01T00:01:00Z"
    }
  ],
  "userMedia": [
    {
      "type": "image/jpeg",
      "url": "https://tooldesk-public-user-uploads.s3.us-west-2.amazonaws.com/email-assets/leadtruffle-Wordmark-white.png"
    }
  ]
}

Remove an existing webhook URL for chat widget lead completion notifications

Creates a new client record or updates an existing one based on the phone number.

The phone number is used as the unique identifier for finding existing clients. Phone numbers are normalized to E.164 format internally (+1XXXXXXXXXX for US numbers).

When updating existing clients:

• Only non-null fields in the request are updated
• Existing data is preserved for fields not included in the request
• The phone number cannot be changed once a client is created
• Operations are restricted to the authenticated company's data

Notes

• Phone numbers must be valid US numbers
• All fields except phone are optional
• Email addresses must be valid format
• New clients are automatically marked as leads with status 'NEW'

Retrieves a client record by their phone number.

The phone number should be in E.164 format (+1XXXXXXXXXX) or a standard US format. The system will normalize the phone number to E.164 format before searching.

Returns a 404 error if no client with the specified phone number exists for the authenticated company.

Retrieve a paginated list of leads for your company without full conversation history. This endpoint is optimized for performance and can return up to 100 records at once.

Use this endpoint when you need to fetch larger batches of leads and don't require the full message history for each lead.

Retrieve all configured V2 webhooks for your company.

V2 webhooks provide improved payload structure and support for multiple event types:

• LEAD_CREATED: Fires instantly when a new lead is created from missed calls or widget submissions
• MESSAGE_REPLY: Fires when leads reply to messages (useful for Slack integrations)
• CONVERSATION_COMPLETED: Fires when lead qualification is complete

Each webhook includes tracking information such as delivery success/failure rates and timestamps.

Create a new V2 webhook for your company.

V2 webhooks support three event types:

LEAD_CREATED

Fires instantly when a new lead form submission is received from your website or missed call. The fastest way to get notified of new leads.

MESSAGE_REPLY

Fires when any message is replied to by a lead or customer. Useful for Slack integrations to notify your team of new responses in real-time.

CONVERSATION_COMPLETED

Fires when a conversation is marked complete - either after lead qualification finishes or an AI call ends. Perfect for triggering follow-up workflows in your CRM.

Headers sent with webhook:

• Content-Type: application/json
• x-origin: leadtruffle
• x-event-type: [EVENT_TYPE]

Delivery & Retry:

• Webhooks timeout after 10 seconds
• Failed deliveries are retried with exponential backoff
• Maximum of 6 webhooks per company

Update an existing V2 webhook by ID.

You can partially update webhooks by including only the fields you want to change. All fields are optional in the update request.

Special fields:

• enabled: Set to false to disable the webhook without deleting it
• clearErrors: Set to true to reset the failed delivery counter

Delete an existing V2 webhook by ID.

This action is permanent and cannot be undone. The webhook will immediately stop receiving events and all associated delivery history will be preserved for audit purposes.

Retrieve a specific lead in the "lead created" format by its UUID.

This endpoint returns the same payload format that is sent to LEAD_CREATED webhooks. Designed specifically for Zapier integration requirements.

Retrieve a paginated list of leads in the "lead created" format.

This endpoint returns the same payload format that is sent to LEAD_CREATED webhooks. Returns up to 100 records per request. Designed specifically for Zapier integration requirements.

This is the abbreviated format that gets delivered when we first receive a lead, before the conversation is completed.

Retrieve a specific lead in the "conversation completed" format by its UUID.

This endpoint returns the same payload format that is sent to CONVERSATION_COMPLETED webhooks. Designed specifically for Zapier integration requirements.

Retrieve a paginated list of leads in the "conversation completed" format.

This endpoint returns the same payload format that is sent to CONVERSATION_COMPLETED webhooks. Returns up to 10 records per request due to the larger payload size (includes full message history). Designed specifically for Zapier integration requirements.

This is what gets delivered to the conversation complete webhook - the same lead data but with full message history and completed qualification information.

Retrieve the current chat widget configuration for your company.

This includes styling settings, AI agent configuration, and lead qualification settings. If no configuration exists, a default configuration will be created automatically.

Update the chat widget configuration for your company.

You can partially update the configuration by including only the fields you want to change. This endpoint combines styling updates and AI agent configuration updates.

Key Configuration Options:

• greetingMessage: The initial message shown to visitors
• agentConfig: AI agent styling, popup behavior, and appearance
• leadQualifierAgentConfig: AI qualification logic and message limits
• Styling: Primary/secondary colors, background, custom CSS

⚠️ RESTRICTED ENDPOINT - APPROVAL REQUIRED ⚠️

This endpoint allows you to programmatically submit leads and trigger the AI lead qualification process.

Prerequisites & Restrictions

This endpoint may ONLY be used if ALL of the following conditions are met:

1. Active 10DLC Phone Number: Your company must have an active 10DLC (Application-to-Person) phone number provisioned
2. Lead Qualifier Agent Enabled: The lead qualification AI agent must be enabled in your widget configuration
3. Approved Usage: LeadTruffle must have explicitly approved your specific use case and implementation
4. SMS Opt-in Compliance: You must have proper SMS opt-in consent as part of your lead collection flow

Pre-Approved Use Cases

The following lead sources have been pre-approved for use with this endpoint:

• Facebook Lead Ads - With proper SMS opt-in checkbox
• Google Lead Ads - With SMS consent collection
• Thumbtack Lead Ads - Following platform opt-in requirements
• Yelp Lead Ads - With SMS permission collection

Compliance Requirements

SMS Opt-in Consent: You MUST collect explicit SMS opt-in consent from leads before using this endpoint. This includes:

• Clear disclosure that they will receive SMS messages
• Explicit consent checkbox or opt-in mechanism
• Compliance with TCPA regulations
• Documentation of consent for audit purposes

Approval Process: Contact support@leadtruffle.com to:

1. Submit your lead collection workflow for review
2. Demonstrate proper SMS opt-in implementation
3. Receive written approval for your specific use case
4. Get the permission flag enabled on your account

Important Notes

• Unauthorized usage will result in immediate API access suspension
• Only approved opt-in methods will be accepted
• LeadTruffle reserves the right to audit and verify compliance
• All lead submissions are logged and monitored
• You are responsible for TCPA and SMS compliance

Usage Example

{
  "name": "John Doe",
  "phone": "+15551234567",
  "additionalData": {
    "leadSource": "facebook",
    "fbid": "923849028492034890283094",
    "campaignId": "summer_hvac_2024",
    "smsOptInConfirmed": "true",
    "optInTimestamp": "2024-01-01T12:00:00Z"
  }
}

The lead qualifier AI will automatically initiate an SMS conversation with the provided phone number using your configured qualification questions and company branding.

Report conversion data (revenue, status) for a specific lead.

This endpoint allows CRMs and external systems to report back when a lead converts to a customer. If a conversion already exists for the lead, it will be updated. Otherwise, a new conversion record is created.

Upsert Behavior:

• First call for a lead → Creates new conversion
• Subsequent calls → Updates existing conversion

Input:

• EITHER - leadId or phone is required to associate the conversion with.

Use Cases:

• CRM reports when a lead converts to a paying customer
• Update revenue amount when final billing is processed
• Track conversion status changes (QUOTED → WON)
• Store integration-specific data in sourceData field

Important Notes:

• Revenue amount is optional (you can track conversions without revenue)
• Currency defaults to USD if not specified
• Source field helps track which CRM/system reported the conversion
• Source defaults to 'API' if not specified
• sourceData field can store CRM-specific metadata (max 10KB)
• Identify the lead by providing either leadId or phone in the request body. If both are provided, leadId is used.

Webhook Integration: When you report conversions via this API, the conversion data will be automatically included in all future webhook payloads for this lead (LEAD_CREATED, CONVERSATION_COMPLETED). This allows downstream systems to have complete lead lifecycle data including revenue tracking.

Creates a review request associated with a lead. If a review request already exists for the lead, the call is idempotent and returns the existing request with isDuplicate: true.

Identify the lead by providing either leadId or phone in the request body. If both are provided, leadId is used.

Retrieve appointments for the company's default (primary) calendar with optional date filtering and pagination.

Default Behavior:

• If no date range is specified, returns appointments from today to 2 weeks in the future
• Returns up to 100 appointments per request
• Results are ordered by appointment start time (ascending)
• Includes associated client information when available

Date Filtering:

• Use startDate and endDate query parameters to specify custom date ranges
• Dates must be in ISO 8601 format (e.g., "2024-01-15T00:00:00Z")

Pagination:

• Use limit (1-100) and offset parameters for pagination
• Response includes pagination metadata to help navigate through results