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"
  },
  "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"
  },
  "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.