LeadTruffle Public API (1.0.0)

Download OpenAPI specification:

The LeadTruffle Public API allows you to access your leads and lead form submissions programmatically.

Leads

https://pub-api.leadtruffle.com/api/v1/pub/leads

The Leads endpoint allows you to retrieve a paginated list of leads for your company. This returns a maximum of 10 records per result.

Leads/{uuid}

https://pub-api.leadtruffle.com/api/v1/pub/leads/{uuid}

The Leads/{uuid} endpoint allows you to retrieve a specific lead by its UUID. This is useful in case you need to access the updates to a lead if further qualifying information was recorded via the course fo the conversation with the AI.

Authentication

All API endpoints require an API key to be sent in the X-API-Key header. You can obtain an API key from your LeadTruffle dashboard.

Rate Limiting

The API implements rate limiting based on your companyId, you can generally call the API roughly once per second. If you exceed the rate limit, you'll receive a 429 status code.

Pagination

List endpoints support cursor-based pagination using the since parameter and return a hasMore flag in the response.

List leads

Retrieve a paginated list of leads for your company

Authorizations:
ApiKeyAuth
query Parameters
before
string <date-time>
Example: before=2024-01-01T00:00:00Z

Pagination cursor - get leads created before this timestamp (ISO8601). Defaults to current time if not provided.

limit
integer [ 1 .. 10 ]
Default: 10

Maximum number of leads to return (max 10)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get lead by ID

Retrieve a specific lead by its UUID

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

The UUID of the lead to retrieve

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List webhooks

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

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{}

Add missed call webhook

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"
    }
  ]
}
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

Remove missed call webhook

Remove an existing webhook URL for missed call lead completion notifications

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

Add chat widget webhook

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"
    }
  ]
}
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

Remove chat widget webhook

Remove an existing webhook URL for chat widget lead completion notifications

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

Create or update a client

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'
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
phone
required
string

Phone number in E.164 format or US national format (e.g., +18001234567 or 8001234567)

firstName
string
lastName
string
email
string <email>
address1
string
address2
string
city
string
state
string
zip
string
country
string

Responses

Request samples

Content type
application/json
{
  • "phone": "8001234567",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "john.doe@example.com",
  • "address1": "123 Main St",
  • "address2": "Unit 456",
  • "city": "Austin",
  • "state": "TX",
  • "zip": "78701",
  • "country": "US"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "data": {
    },
  • "action": "CREATED"
}

Get client by phone number

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.

Authorizations:
ApiKeyAuth
path Parameters
phone
required
string
Example: 8001234567

Phone number in E.164 format or US national format (e.g., +18001234567 or 8001234567)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List leads without conversation history

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.

Authorizations:
ApiKeyAuth
query Parameters
before
string <date-time>
Example: before=2024-01-01T00:00:00Z

Pagination cursor - get leads created before this timestamp (ISO8601). Defaults to current time if not provided.

limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of leads to return (max 100)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List V2 webhooks

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.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Create V2 webhook

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
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
eventType
required
string
Enum: "CONVERSATION_COMPLETED" "MESSAGE_REPLY" "LEAD_CREATED"

Type of event that triggers this webhook

url
required
string <uri> <= 1000 characters

URL where webhook payloads will be sent via HTTP POST

secret
string or null <= 200 characters

Optional secret for webhook verification (currently not used)

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update V2 webhook

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
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The UUID of the webhook to update

Request Body schema: application/json
required
eventType
string
Enum: "CONVERSATION_COMPLETED" "MESSAGE_REPLY" "LEAD_CREATED"

Type of event that triggers this webhook

url
string <uri> <= 1000 characters

URL where webhook payloads will be sent via HTTP POST

secret
string or null <= 200 characters

Optional secret for webhook verification (currently not used)

enabled
boolean

Whether the webhook is active

clearErrors
boolean

Clear any existing error history for this webhook

Responses

Request samples

Content type
application/json
Example

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete V2 webhook

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.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The UUID of the webhook to delete

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Webhook deleted successfully"
}