Leads

Create, list, retrieve, and update leads in your lending pipeline.

Leads represent potential borrowers entering your pipeline. Each lead is scoped to your organization and can be assigned to advisors, tagged, and moved through pipeline stages.

List Leads

GET /v1/leads

Returns a paginated list of leads in your organization, sorted by creation date (newest first).

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`20`	Items per page (max 100)
`search`	string	—	Full-text search across business name, contact name, and email

Example Request

curl -H "Authorization: Bearer lw_live_xxxx" \
     "https://api.lend.works/v1/leads?limit=10&search=acme"

Example Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "type": "lead",
      "attributes": {
        "businessName": "Acme Corp",
        "contactFirstName": "Jane",
        "contactLastName": "Doe",
        "email": "jane@acme.com",
        "phone": "555-0100",
        "industry": "Technology",
        "monthlyRevenue": "85000",
        "requestedAmount": "250000",
        "source": "api",
        "priority": "high",
        "isDoNotCall": false,
        "tags": ["technology", "high-value"],
        "customFields": {},
        "externalIds": {},
        "leadScore": null,
        "stage": {
          "id": "a1b2c3d4-...",
          "stageKey": "new_lead",
          "stageLabel": "New Lead",
          "color": "#3b82f6",
          "semanticSlot": "new"
        },
        "primaryAdvisorId": "e5f6g7h8-...",
        "primaryAdvisorName": "Mike Johnson",
        "lastContactedAt": null,
        "stageChangedAt": "2025-01-15T10:30:00Z",
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "hasMore": true,
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

The response includes all lead fields. Key fields are documented below; additional fields like dncReason, dncAt, convertedAt, convertedAccountId, convertedContactId, importJobId, and createdBy are included when applicable (otherwise null).

Get a Lead

GET /v1/leads/{id}

Retrieve a single lead by its UUID.

Path Parameters

Parameter	Type	Description
`id`	UUID	Lead ID

Example Request

curl -H "Authorization: Bearer lw_live_xxxx" \
     https://api.lend.works/v1/leads/d290f1ee-6c54-4b01-90e6-d701748f0851

Example Response

{
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "type": "lead",
    "attributes": {
      "businessName": "Acme Corp",
      "contactFirstName": "Jane",
      "contactLastName": "Doe",
      "email": "jane@acme.com",
      "phone": "555-0100",
      "industry": "Technology",
      "monthlyRevenue": "85000",
      "requestedAmount": "250000",
      "source": "api",
      "priority": "high",
      "isDoNotCall": false,
      "tags": ["technology", "high-value"],
      "customFields": {},
      "externalIds": {},
      "leadScore": null,
      "stage": {
        "id": "a1b2c3d4-...",
        "stageKey": "new_lead",
        "stageLabel": "New Lead",
        "color": "#3b82f6",
        "semanticSlot": "new"
      },
      "primaryAdvisorId": "e5f6g7h8-...",
      "primaryAdvisorName": "Mike Johnson",
      "lastContactedAt": null,
      "stageChangedAt": "2025-01-15T10:30:00Z",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T14:20:00Z"
    }
  },
  "meta": {
    "requestId": "661f9511-a29b-42d5-b827-557766551111"
  }
}

Create a Lead

POST /v1/leads

Create a new lead in your pipeline. Supports idempotency keys for safe retries.

Request Body

Field	Type	Required	Description
`businessName`	string	No	Business name (1-255 chars, no HTML)
`contactFirstName`	string	No	Contact first name (max 100 chars)
`contactLastName`	string	No	Contact last name (max 100 chars)
`email`	string	No	Valid email address
`phone`	string	No	Phone number (max 20 chars)
`industry`	string	No	Industry classification (max 100 chars)
`monthlyRevenue`	string	No	Monthly revenue amount (numeric string)
`requestedAmount`	string	No	Requested funding amount (numeric string)
`source`	enum	No	`manual`, `csv_import`, `api`, `web_form`, `referral`, `dialer`. Default: `manual`
`priority`	enum	No	`low`, `normal`, `high`, `urgent`. Default: `normal`
`stageId`	UUID	No	Pipeline stage ID. Defaults to first stage
`tags`	string[]	No	Array of tag strings
`customFields`	object	No	Key-value pairs for custom fields
`assignToAdvisorId`	UUID	No	Assign to a specific advisor
`contactId`	UUID	No	Link to an existing contact

Example Request

curl -X POST https://api.lend.works/v1/leads \
  -H "Authorization: Bearer lw_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-lead-acme-001" \
  -d '{
    "businessName": "Acme Corp",
    "contactFirstName": "Jane",
    "contactLastName": "Doe",
    "email": "jane@acme.com",
    "phone": "555-0100",
    "industry": "Technology",
    "monthlyRevenue": "85000",
    "requestedAmount": "250000",
    "source": "api",
    "priority": "high",
    "tags": ["technology", "high-value"]
  }'

SDK Example

const lead = await client.leads.create({
  businessName: 'Acme Corp',
  contactFirstName: 'Jane',
  contactLastName: 'Doe',
  email: 'jane@acme.com',
  phone: '555-0100',
  industry: 'Technology',
  monthlyRevenue: '85000',
  requestedAmount: '250000',
  source: 'api',
  priority: 'high',
  tags: ['technology', 'high-value'],
}, {
  idempotencyKey: 'create-lead-acme-001',
})

Response — `201 Created`

Returns the created lead in the standard response envelope.

Update a Lead

PATCH /v1/leads/{id}

Update an existing lead. Only include the fields you want to change.

Path Parameters

Parameter	Type	Description
`id`	UUID	Lead ID

Request Body

All fields from the create endpoint are accepted (except source, stageId, assignToAdvisorId, contactId). Only include fields you want to update.

Example Request

curl -X PATCH https://api.lend.works/v1/leads/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer lw_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update-lead-acme-priority" \
  -d '{
    "priority": "urgent",
    "requestedAmount": "500000"
  }'

Response — `200 OK`

Returns the updated lead in the standard response envelope.

Errors

Status	Code	Description
`400`	`BAD_REQUEST`	Malformed JSON body
`403`	`FORBIDDEN`	API key lacks write permission
`404`	`NOT_FOUND`	Lead not found
`422`	`VALIDATION_ERROR`	Request body failed validation

Webhook Events

Event	Description
`lead.created`	Fired when a new lead is created
`lead.status_changed`	Fired when a lead moves to a new pipeline stage

See Webhook Events for payload details.

Leads

On this page