Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.lofty.com/llms.txt

Use this file to discover all available pages before exploring further.

A transaction in Lofty represents a real estate deal — a purchase, listing, lease, or other arrangement — associated with a specific lead. Transactions track deal financials, pipeline status, close dates, commission, and the property address, and they move through a configurable pipeline as the deal progresses.

​
What is a transaction?

Each transaction belongs to exactly one lead and is managed by an assigned agent. When you create a transaction, you give it a name (typically the property address or deal identifier), a type, and an initial status. From there, you update it as the deal moves through your team’s configured pipeline stages. Transactions support custom fields, letting teams capture deal-specific data beyond the standard schema. You can retrieve your team’s custom field definitions before creating or updating transactions.

​
Key transaction fields

FieldTypeDescription
transactionIdint64Unique transaction ID (read-only)
leadIdint64Lead this transaction belongs to
transactionNamestringProperty address or deal name (required on create)
transactionTypestringPurchase, Listing, Lease, or Other
transactionStatusstringPipeline status name (must match your team’s pipeline config)
homePricenumberDeal price
expectedCloseDateint64Expected close date (Unix ms)
closeDateint64Actual close date (Unix ms)
commissionRatenumberCommission rate as a percentage (e.g., 3 for 3%)
gcinumberGross Commission Income
teamRevenuenumberPortion of GCI attributed to the team
agentRevenuenumberPortion of GCI attributed to the agent
assignedAgentint64User ID of the assigned agent
createdint64Creation timestamp (Unix ms, read-only)
updatedint64Last-modified timestamp (Unix ms, read-only)

​
Transaction lifecycle

Transactions move through a pipeline you configure in Lofty. The typical progression is:
  1. Created — You create the transaction with POST /v1.0/leads/{leadId}/transaction. Supply a transactionName, transactionType, and initial transactionStatus.
  2. In-progress — As the deal advances, you update the status with PUT /v1.0/leads/{leadId}/transaction/{transactionId}. The status value must match one of the statuses configured in your team’s pipeline for the given transactionType.
  3. Closed — Set closeDate and update the status to reflect the closed or cancelled state.
Both transactionType and transactionStatus are case-sensitive and must match your team’s pipeline configuration exactly. Unmatched values silently fall back to the first pipeline or first status — they do not produce an error. Always validate these values against your pipeline configuration before submitting.

​
Creating a transaction

Transactions are created under a specific lead. The transactionName field is required and must not be blank or contain < or > characters. 
POST https://api.lofty.com/v1.0/leads/{leadId}/transaction

{
  "transactionName": "456 Oak Avenue",
  "transactionType": "Purchase",
  "transactionStatus": "Pre-contract",
  "homePrice": 875000,
  "expectedCloseDate": 1780000000000,
  "commissionRate": 3
}

​
Custom fields

Your team can define custom fields on transactions to capture deal-specific data. Before creating or updating transactions with custom fields, retrieve the field definitions: 
GET https://api.lofty.com/v1.0/transaction/customfields
This returns the list of custom field definitions for your team, including field names, types, and IDs. Use these definitions to populate custom field values correctly when creating or updating a transaction.

​
Property address

Each transaction can have a property address attached to it separately from the transactionName. This is useful when you need to store a structured address alongside the deal name. 
# Update the property address on a transaction
POST https://api.lofty.com/v1.0/leads/{leadId}/transaction/property/address

# Retrieve the current property address
GET https://api.lofty.com/v1.0/leads/{leadId}/transaction/{transactionId}/property/address

​
Searching transactions (V2)

The V2 transactions endpoint lets you search across transactions without filtering by a specific lead. This is useful for building pipeline dashboards or reports that span multiple leads. 
GET https://api.lofty.com/v2.0/transactions
Use GET /v2.0/transactions when building team-level reporting or pipeline views. Use GET /v1.0/leads/{leadId}/transactions when you need all transactions for a specific lead.

​
Endpoint overview

MethodEndpointDescription
GET/v1.0/leads/{leadId}/transactionsList all transactions for a lead
POST/v1.0/leads/{leadId}/transactionCreate a transaction on a lead
GET/v1.0/leads/{leadId}/transaction/{transactionId}Get a transaction by ID
PUT/v1.0/leads/{leadId}/transaction/{transactionId}Partially update a transaction
GET/v2.0/transactionsSearch transactions across leads
GET/v1.0/transaction/customfieldsList transaction custom field definitions
POST/v1.0/leads/{leadId}/transaction/property/addressSet the property address on a transaction
GET/v1.0/leads/{leadId}/transaction/{transactionId}/property/addressGet the property address for a transaction