Guides / Call Lists API

Call Lists API

Build, page, edit and archive dialer call lists through the Goliath developer API

About

A call list is a fixed, ordered set of contacts for the power dialer. Build one from contact ids or a saved contact filter, page through its progress, add or remove contacts, and end or delete it when the campaign is over. Dialing itself happens in the app: the API hands you the link that opens a list in the dialer.

All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Reading lists (`READ` scope)

operationId	Scope	What it does
`listCallLists`	`READ`	The lists the key owner can open — their own and team-shared, newest first, at most 50. Narrow with `status`, `mine`, or `orgVisible`. Each row carries progress counts, the frozen build rules, the creator, who is dialing it right now, and `dialPath`.
`getCallList`	`READ`	One list with its progress and a position-keyed page of its contacts in dial order. `limit` defaults to 50 (max 200); pass the returned `nextFromPosition` as `fromPosition` to page on, and `statuses` to filter slots. A list that is gone or private to someone else is refused with an error.
`getCallListDialLink`	`READ`	The in-app path (`/contacts?callListId=…`) that opens the list in the dialer, for rendering as a button, plus who is dialing it now.

Building lists (`WRITE` scope)

operationId	Scope	What it does
`createCallList`	`WRITE`	Build a list from `contactIds` in the order given. Contacts the list cannot call are left off and counted in `cannotCallCount`; anything past 10,000 is dropped and counted in `truncatedCount`. Optional `name`, `visibilityScope` (`USER` by default), `maxNumbersPerContact`, `includeRelatives`, `overrideDnc`, `overrideLitigator`, and `reachedTagId`.
`createCallListFromContactFilter`	`WRITE`	The same build from a saved contact filter (`filterId`): its current matches for the key owner, up to 10,000.

Both accept buildAttemptKey: a retry with the same key returns the list the first attempt built instead of building a second one.

Editing lists (`WRITE` scope)

Only the list’s creator or an org admin can edit a list. Edits to an ENDED list are refused.

operationId	Scope	What it does
`addCallListContacts`	`WRITE`	Append `contactIds` after the last position. Contacts already on the list, uncallable, or over the cap are left off and counted.
`removeCallListContacts`	`WRITE`	Close not-yet-called contacts’ slots as skipped by hand (`USER`). Slots being dialed, already called, or up next for a rep working the list are left alone and counted in `notRemovedCount`. A removed contact keeps its slot and cannot be re-added.
`renameCallList`	`WRITE`	Rename a list.
`endCallList`	`WRITE`	Archive a list: it becomes `ENDED`, stays readable, and can no longer be dialed or edited.
`deleteCallList`	`WRITE`	Soft-delete a list: it disappears from Call lists for everyone. Calls already made stay on each contact’s timeline.

Example

Build a list from a saved contact filter, then fetch the link that opens it in the dialer:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-list-2026-10-28" \
  -d '{ "operationId": "createCallListFromContactFilter", "variables": { "filterId": "FILTER_ID", "name": "Absentee owners — October" } }'

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "getCallListDialLink", "variables": { "callListId": "CALL_LIST_ID" } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.