How the API fits together

A contact is the person or business you work with. A lead inquiry is a specific interaction with that contact. Understanding the difference helps you update the right record.

Contacts and lead inquiries

Contacts hold details such as names, phone numbers, email addresses, notes, and pipeline status. Existing API paths and payloads use clients and clientId for these records.

To retrieve a contact by its ID, use Get contact by ID:

curl 'https://pub-api.leadtruffle.com/api/v2/pub/clients/CONTACT_UUID' \
  --header 'X-API-Key: YOUR_API_KEY'

The contact is returned directly in data, including address, tags, notes, opt-out flags, pipeline, assignment, review and archive state. By default, data.recentInquiries contains the most recent 5 inquiry summaries, and data.history contains the most recent 10 public lifecycle events. Both contain items and hasMore, newest first.

Set includeInquiries=false or includeHistory=false to omit a section. Use inquiriesLimit=1 through 25 and historyLimit=1 through 50 to change preview sizes. For example, retrieve just the profile:

curl 'https://pub-api.leadtruffle.com/api/v2/pub/clients/CONTACT_UUID?includeInquiries=false&includeHistory=false' \
  --header 'X-API-Key: YOUR_API_KEY'

Inquiry previews contain individual saved inquiry rows with IDs, statuses, source, timestamps and a bounded qualification summary. History contains public activity metadata; it excludes message text, raw event data, internal notes and diagnostics. Use the Inbox timeline for paginated communication history and the V2 lead-inquiry detail endpoints for a full inquiry record.

Both the GET and PUT Contacts endpoints require an unrestricted API key. For AI state and message previews with an inbox:read key, use Read a contact conversation.

Use Update contact by ID to edit profile details and pipeline state:

curl --request PUT 'https://pub-api.leadtruffle.com/api/v2/pub/clients/CONTACT_UUID' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"firstName":"Sarah","primaryEmail":"sarah@example.com","tags":["Customer"],"userNotes":"Prefers email"}'

Only supplied fields change. Supported fields are firstName, lastName, companyName, primaryEmail, address, address2, city, state, zipCode, country, tags, userNotes, leadStatus, assignedToUserId and archived. Unknown fields, incorrect types and oversized values return 400 before changes. Use null to clear nullable profile fields or assignment, and [] to clear tags. Phone numbers, consent flags, IDs and internal settings cannot be edited here. Use company status IDs and enabled employee IDs for status/assignment changes. The PUT response returns the updated profile without previews; GET again to refresh inquiries and history.

Changing or clearing the email resets its verification and preserves opt-out settings. An unchanged email keeps its verification state.

Lead inquiries represent interactions such as a website conversation, phone call, or marketplace lead. A contact can have multiple lead inquiries. Use the IDs returned by the API rather than assuming a contact ID and a lead ID are interchangeable.

Created and completed events

A lead created payload contains the information available when the lead first arrives. A conversation completed payload contains the information collected through the conversation.

Choose the event that matches your workflow. An initial lead event does not mean qualification or booking has finished.

API versions

The version is part of each endpoint path. V1 and V2 endpoints coexist; a V1 endpoint is not automatically obsolete. Check the specific operation's request and response schema.

For new webhook integrations, use V2 webhooks. V1 webhook operations remain documented for existing integrations under Legacy webhooks.

REST API and browser widgets

Use the REST API from your server with an API key. Website widgets use their own browser JavaScript APIs and company or agency identifiers. They do not require you to expose your REST API key.

See Website widgets for the available methods and their differences.

Operations that take action

Read the description and prerequisites before calling an endpoint. Some operations update contacts, register webhook destinations, initiate messages, or trigger review requests.

The lead qualifier trigger requires account approval and the prerequisites listed in its reference. A successful acceptance response does not guarantee that a message has already been delivered. See Trigger lead qualifier agent.