LeadTruffle Public API (1.0.0)

Retrieve a paginated list of leads for your company

Retrieve a specific lead by its UUID

Retrieve all configured webhooks for both chat widget and missed call lead completion

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.