Download OpenAPI specification:
The LeadTruffle Public API allows you to access your leads and lead form submissions programmatically.
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.
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.
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.
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.
List endpoints support cursor-based pagination using the since
parameter and return a hasMore
flag in the response.
Retrieve a paginated list of leads for your company
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) |
{- "success": true,
- "data": {
- "leads": [
- {
- "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",
- "utm_term": "home_renovation_cost",
- "utm_content": "home_renovation_cost",
- "gclid": "1234567890",
- "fbclid": "1234567890",
- "msclkid": "1234567890",
- "ttclid": "1234567890",
- "snapcid": "1234567890",
- "gbraid": "gbraid_example",
- "wbraid": "wbraid_example",
- "gad_source": "google_ads",
- "igshid": "ig_share_id",
- "gclsrc": "aw.ds",
- "srsltid": "search_result_id",
- "ga_client_id": "123456789.987654321",
- "ga_session_id": "1700000000"
}, - "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",
- "isRepeatLead": false,
- "messageHistory": [
- {
- "direction": "inbound",
- "name": "AI Agent",
- "message": "How can we help you...",
- "date": "2024-01-01T00:00:00Z"
}
], - "userMedia": [
- {
- "type": "image/jpeg",
}
]
}
], - "hasMore": true
}
}
Retrieve a specific lead by its UUID
uuid required | string <uuid> The UUID of the lead to retrieve |
{- "success": true,
- "data": {
- "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",
- "utm_term": "home_renovation_cost",
- "utm_content": "home_renovation_cost",
- "gclid": "1234567890",
- "fbclid": "1234567890",
- "msclkid": "1234567890",
- "ttclid": "1234567890",
- "snapcid": "1234567890",
- "gbraid": "gbraid_example",
- "wbraid": "wbraid_example",
- "gad_source": "google_ads",
- "igshid": "ig_share_id",
- "gclsrc": "aw.ds",
- "srsltid": "search_result_id",
- "ga_client_id": "123456789.987654321",
- "ga_session_id": "1700000000"
}, - "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",
- "isRepeatLead": false,
- "messageHistory": [
- {
- "direction": "inbound",
- "name": "AI Agent",
- "message": "How can we help you...",
- "date": "2024-01-01T00:00:00Z"
}
], - "userMedia": [
- {
- "type": "image/jpeg",
}
]
}
}
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.
{
"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"
}
]
}
url required | string <uri> |
{
}
{- "success": true,
}
Remove an existing webhook URL for missed call lead completion notifications
url required | string <uri> |
{
}
{- "success": true,
}
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.
{
"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"
}
]
}
url required | string <uri> |
{
}
{- "success": true,
}
Remove an existing webhook URL for chat widget lead completion notifications
url required | string <uri> |
{
}
{- "success": true,
}
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:
phone required | string Phone number in E.164 format or US national format (e.g., +18001234567 or 8001234567) |
firstName | string |
lastName | string |
string <email> | |
address1 | string |
address2 | string |
city | string |
state | string |
zip | string |
country | string |
{- "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"
}
{- "success": true,
- "data": {
- "id": "415f2b29-39e6-4182-9d6f-ec2d817f01c2",
- "companyId": "f096f9e3-001d-49ac-864c-3d73453bbe08",
- "primaryPhone": "+18001234567",
- "firstName": "John",
- "lastName": "Doe",
- "primaryEmail": "john.doe@example.com",
- "address": "123 Main St",
- "address2": "Unit 456",
- "city": "Austin",
- "state": "TX",
- "zipCode": "78701",
- "country": "US",
- "isLead": true,
- "leadStatus": "NEW",
- "createdAt": "2023-06-01T00:00:00Z",
- "updatedAt": "2023-06-01T00:00:00Z"
}, - "action": "CREATED"
}
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.
phone required | string Example: 8001234567 Phone number in E.164 format or US national format (e.g., +18001234567 or 8001234567) |
{- "success": true,
- "data": {
- "id": "415f2b29-39e6-4182-9d6f-ec2d817f01c2",
- "companyId": "f096f9e3-001d-49ac-864c-3d73453bbe08",
- "primaryPhone": "+17345520800",
- "firstName": "John",
- "lastName": "Doe",
- "primaryEmail": "john.doe@example.com",
- "address": "123 Main St",
- "address2": "Unit 456",
- "city": "Austin",
- "state": "TX",
- "zipCode": "78701",
- "country": "US",
- "isLead": true,
- "leadStatus": "NEW",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
}
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.
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) |
{- "success": true,
- "data": {
- "leads": [
- {
- "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",
- "utm_term": "home_renovation_cost",
- "utm_content": "home_renovation_cost",
- "gclid": "1234567890",
- "fbclid": "1234567890",
- "msclkid": "1234567890",
- "ttclid": "1234567890",
- "snapcid": "1234567890",
- "gbraid": "gbraid_example",
- "wbraid": "wbraid_example",
- "gad_source": "google_ads",
- "igshid": "ig_share_id",
- "gclsrc": "aw.ds",
- "srsltid": "search_result_id",
- "ga_client_id": "123456789.987654321",
- "ga_session_id": "1700000000"
}, - "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",
- "isRepeatLead": false,
- "messageHistory": [
- {
- "direction": "inbound",
- "name": "AI Agent",
- "message": "How can we help you...",
- "date": "2024-01-01T00:00:00Z"
}
], - "userMedia": [
- {
- "type": "image/jpeg",
}
]
}
], - "hasMore": true
}
}
Retrieve all configured V2 webhooks for your company.
V2 webhooks provide improved payload structure and support for multiple event types:
Each webhook includes tracking information such as delivery success/failure rates and timestamps.
{- "success": true,
- "data": [
- {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "companyId": "f096f9e3-001d-49ac-864c-3d73453bbe08",
- "eventType": "LEAD_CREATED",
- "enabled": true,
- "failedAttempts": 0,
- "lastFailedAt": "2019-08-24T14:15:22Z",
- "lastSuccessAt": "2019-08-24T14:15:22Z",
- "integrationSource": "API",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
]
}
Create a new V2 webhook for your company.
V2 webhooks support three event types:
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.
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.
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:
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) |
{- "eventType": "LEAD_CREATED",
}
{- "success": true,
- "data": {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "companyId": "f096f9e3-001d-49ac-864c-3d73453bbe08",
- "eventType": "LEAD_CREATED",
- "enabled": true,
- "failedAttempts": 0,
- "lastFailedAt": "2019-08-24T14:15:22Z",
- "lastSuccessAt": "2019-08-24T14:15:22Z",
- "integrationSource": "API",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
}
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 itclearErrors
: Set to true to reset the failed delivery counterid required | string <uuid> Example: 550e8400-e29b-41d4-a716-446655440000 The UUID of the webhook to update |
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 |
{- "success": true,
- "data": {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "companyId": "f096f9e3-001d-49ac-864c-3d73453bbe08",
- "eventType": "LEAD_CREATED",
- "enabled": true,
- "failedAttempts": 0,
- "lastFailedAt": "2019-08-24T14:15:22Z",
- "lastSuccessAt": "2019-08-24T14:15:22Z",
- "integrationSource": "API",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
}
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.
id required | string <uuid> Example: 550e8400-e29b-41d4-a716-446655440000 The UUID of the webhook to delete |
{- "success": true,
- "message": "Webhook deleted successfully"
}