Dialer

Submit call events, manage agent presence, record dispositions, and view agent availability.

The dialer API integrates with power dialer systems (Convoso) to track call events, agent presence, and dispositions. This enables real-time call tracking within your LendWorks pipeline.

Submit a Call Event

POST /v1/dialer/events

Record a call event from your dialer system. Supports idempotency keys.

Request Body

All fields accept both camelCase and snake_case aliases (e.g., externalCallId or call_id).

Field	Type	Required	Description
`externalCallId`	string	Yes	Unique call ID from the dialer system
`userId`	UUID	Yes	LendWorks user ID of the agent
`leadId`	UUID	No	Associated lead ID
`eventType`	enum	Yes	`call_started`, `call_answered`, `call_ended`, `disposition`, `transfer`, `hold`, `resume`
`direction`	enum	No	`inbound` or `outbound`
`durationSeconds`	integer	No	Call duration (>= 0)
`disposition`	string	No	Disposition code
`metadata`	object	No	Additional event data
`occurredAt`	ISO 8601	Yes	When the event happened

Example Request

curl -X POST https://api.lend.works/v1/dialer/events \
  -H "Authorization: Bearer lw_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: call-evt-12345-ended" \
  -d '{
    "externalCallId": "convoso-call-12345",
    "userId": "e5f6g7h8-1234-5678-9abc-def012345678",
    "leadId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "eventType": "call_ended",
    "direction": "outbound",
    "durationSeconds": 180,
    "disposition": "interested",
    "occurredAt": "2025-01-15T14:35:00Z"
  }'

Response — `201 Created`

{
  "data": {
    "id": "evt_a1b2c3d4-...",
    "type": "call_event",
    "attributes": {
      "externalCallId": "convoso-call-12345",
      "userId": "e5f6g7h8-...",
      "leadId": "d290f1ee-...",
      "eventType": "call_ended",
      "direction": "outbound",
      "durationSeconds": 180,
      "disposition": "interested",
      "metadata": {},
      "occurredAt": "2025-01-15T14:35:00Z",
      "createdAt": "2025-01-15T14:35:01Z",
      "updatedAt": "2025-01-15T14:35:01Z"
    }
  },
  "meta": {
    "requestId": "a76b86c9-d0e1-4f23-4567-890123456012"
  }
}

Update Agent Presence

POST /v1/dialer/presence

Update an agent's availability status in the dialer system.

Request Body

Field	Type	Required	Description
`userId`	UUID	Yes	LendWorks user ID
`status`	enum	Yes	`online`, `on_call`, `break`, `offline`
`currentCallId`	string	No	Active call ID
`currentLeadId`	UUID	No	Lead currently being worked
`metadata`	object	No	Additional presence data

Example Request

curl -X POST https://api.lend.works/v1/dialer/presence \
  -H "Authorization: Bearer lw_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "e5f6g7h8-1234-5678-9abc-def012345678",
    "status": "on_call",
    "currentCallId": "convoso-call-12345",
    "currentLeadId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }'

Response — `200 OK`

Returns the updated agent presence record with enriched data (agent name, lead name, call statistics).

Submit a Disposition

POST /v1/dialer/disposition

Record a call disposition. Supports idempotency keys.

Request Body

Field	Type	Required	Description
`externalCallId`	string	Yes	Call ID from the dialer
`userId`	UUID	Yes	Agent's LendWorks user ID
`leadId`	UUID	No	Associated lead ID
`disposition`	string	Yes	Disposition code (e.g., `interested`, `callback`, `not_interested`, `no_answer`)
`notes`	string	No	Agent notes
`occurredAt`	ISO 8601	Yes	When the disposition was recorded

Example Request

curl -X POST https://api.lend.works/v1/dialer/disposition \
  -H "Authorization: Bearer lw_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: disp-12345" \
  -d '{
    "externalCallId": "convoso-call-12345",
    "userId": "e5f6g7h8-1234-5678-9abc-def012345678",
    "leadId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "disposition": "interested",
    "notes": "Wants to discuss term loan options. Callback scheduled.",
    "occurredAt": "2025-01-15T14:38:00Z"
  }'

Response — `201 Created`

Returns the created call event record.

List Agent Availability

GET /v1/dialer/agents

Returns the current presence status of all dialer agents.

Query Parameters

Parameter	Type	Description
`teamId`	UUID	Filter by team (optional)

Example Request

curl -H "Authorization: Bearer lw_live_xxxx" \
     "https://api.lend.works/v1/dialer/agents?teamId=t1e2a3m4-..."

Example Response

{
  "data": [
    {
      "id": "pres_a1b2c3d4-...",
      "type": "agent_presence",
      "attributes": {
        "userId": "e5f6g7h8-...",
        "firstName": "Mike",
        "lastName": "Johnson",
        "email": "mike@company.com",
        "status": "on_call",
        "currentCallId": "convoso-call-12345",
        "currentLeadId": "d290f1ee-...",
        "currentLeadName": "Acme Corp",
        "callStartedAt": "2025-01-15T14:32:00Z",
        "statusChangedAt": "2025-01-15T14:32:00Z",
        "callsToday": 28,
        "dispositionCount": 24,
        "campaignName": "Q1 Outreach",
        "statusTimeSec": 180
      }
    }
  ],
  "meta": {
    "total": 8,
    "page": 1,
    "limit": 20,
    "hasMore": false,
    "requestId": "b87c97d0-e1f2-4a34-5678-901234567123"
  }
}

Convoso Connect Receiver

POST /v1/dialer/convoso/{orgToken}

This endpoint receives real-time events directly from Convoso Connect. It uses URL token authentication (not API key Bearer auth) and accepts both JSON and form-encoded payloads.

This is configured in your Convoso account's Connect settings — not called directly from your application code.

Supported Event Types

Event	Description
`disposition`	Agent dispositioned a call
`recording`	Call recording is available
`call_event`	Call started, answered, or ended
`lead_update`	Lead data updated in Convoso
`dnc`	Number added to Do Not Call list

Errors

Status	Code	Description
`400`	`BAD_REQUEST`	Invalid event payload
`403`	`FORBIDDEN`	API key lacks permission
`422`	`VALIDATION_ERROR`	Request body failed validation

Dialer

On this page