> ## Documentation Index
> Fetch the complete documentation index at: https://www.landbase.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# dialer-sessions
> Create a dialer session from an imported tag and inspect its live status
Create a calling session for the Landbase dialer from an imported contact tag,
optionally assign it to a teammate, and inspect its live contact counts. The
command has two subcommands: `create` and `status`.
`dialer-sessions` is a **platform-mode** command. Before running it:
1. [`landbase-cli auth login`](/docs/reference/auth) — authenticate the session.
2. Optionally run [`landbase-cli account set`](/docs/reference/account) to persist
a target account. Without a saved choice, the CLI auto-selects your only
account. With several accounts it prompts only in an interactive terminal;
non-interactive agents must use `account set` beforehand or pass
`--account=`.
3. [`landbase-cli contacts-import start`](/docs/reference/contacts-import) — import
contacts and wait for the import to produce a tag.
## dialer-sessions create
Create a dialer session from a tag. The command reads the complete session
definition from a JSON file or stdin.
**Usage**
```bash theme={null}
landbase-cli dialer-sessions create --json
```
Path to a JSON file containing the session definition, or `-` to read it
from stdin.
### `create --json` config
```json theme={null}
{
"schemaVersion": 1,
"name": "Q3 outbound calls",
"audience": { "type": "tag", "tagName": "Q3 Leads" },
"enrichmentType": "PHONE"
}
```
| Field | Type | Notes |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schemaVersion` | integer | Required. Currently `1`. |
| `name` | string | Required. Non-empty session name, at most 500 characters, without control characters. |
| `audience` | object | Required. `{ type: "tag", tagName \| tagId }`. Specify exactly one of `tagName` or a positive integer `tagId`. |
| `assignedUserId` | string | Optional. Non-blank, control-free `identityId` from [`account users`](/docs/reference/account#account-users), at most 28 characters. The assigned user becomes the session owner; omit it to own the session yourself. |
| `enrichmentType` | string | Optional. One of `PHONE`, `ALL`, `EMAIL`, or `NONE`. Defaults to `PHONE`. |
The audience currently supports imported tags only. Use exactly one tag
identifier:
* `tagName` is the human-readable tag name you supplied to `contacts-import`.
* `tagId` is the numeric tag id. Use it when a tag name is ambiguous; the
`tag_name_ambiguous` error includes matching candidates under
`error.meta.tags[]`. Copy a candidate's `id` into `audience.tagId`.
If both values are present, or both are omitted, the CLI exits with
`INVALID_INPUT` before sending the request.
### Enrichment modes
| Value | Behavior |
| ------- | ------------------------------------------------------------------------------------ |
| `PHONE` | Enrich phone numbers for contacts that do not already have one. This is the default. |
| `ALL` | Enrich both phone numbers and email addresses. |
| `EMAIL` | Enrich email addresses only. |
| `NONE` | Use only data already present on the contacts; do not enrich. |
### Assign the session to a teammate
List assignable users and copy the target user's `identityId` into
`assignedUserId` in the create config:
```bash theme={null}
landbase-cli account users
```
```json theme={null}
{ "assignedUserId": "idn_01H..." }
```
Account Owners can assign a session to any current member returned by
`account users`; everyone else may only self-assign. The assigned user must
have the dialer channel permission. Unlike email and LinkedIn readiness,
dialer readiness is checked by the server when the session is created and is
not included as a flag in `account users`.
### Create response
```json theme={null}
{
"sessionId": 9,
"name": "Q3 outbound calls",
"status": "new",
"contactsCount": 42
}
```
See [Output schemas](/docs/reference/output-schemas#dialer-sessions) for the response
field reference.
`contactsCount: 0` is a successful create, not an API failure. The session
exists, but dialer selection produced no primary contact rows. Check that the
tag contains contacts whose phone availability is `AVAILABLE` or
`TO_ENRICH`. The selected enrichment mode changes how those contacts are
processed; it does not decide whether they are counted.
After creation, use the returned numeric id to inspect the session:
```bash theme={null}
landbase-cli dialer-sessions status 9
```
***
## dialer-sessions status
Return the current owner, enrichment mode, and live contact counts for a
dialer session.
**Usage**
```bash theme={null}
landbase-cli dialer-sessions status
```
Positive numeric session id returned by `dialer-sessions create`. The CLI
accepts 1–12 decimal digits.
**Response**
```json theme={null}
{
"sessionId": 9,
"name": "Q3 outbound calls",
"status": "new",
"createdAt": "2026-08-20T12:00:00Z",
"createdBy": "idn_creator",
"enrichmentType": "PHONE",
"owner": {
"identityId": "idn_owner",
"firstName": "Ann",
"lastName": "Lee",
"email": "ann@example.com"
},
"contacts": {
"total": 42,
"byDialStatus": {
"new": 30,
"to_enrich": 10,
"answered": 2
}
}
}
```
See [Output schemas](/docs/reference/output-schemas#dialer-sessions) for the response
field reference.
`createdBy` is the caller's `identityId` for sessions created through the CLI.
It can be `null` for sessions created in the web app.
`contacts.byDialStatus` is a live breakdown by server-provided dial status;
use it to monitor progress or investigate a low contact count.
## Errors
Local CLI checks use stable uppercase codes. Gateway and back-end validation
errors without a typed Landbase envelope surface as `http_422` or `http_400`.
Typed back-end errors pass through verbatim and are safe to inspect as
`error.code`:
| `error.code` | Meaning | What to do |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `INVALID_INPUT` | Missing/malformed `--json`; wrong `schemaVersion`; missing/non-string `name`; missing/wrong audience type; both/neither tag refs; or a status id outside the 1–12 digit CLI shape | Correct the local JSON or command argument and retry. |
| `http_422` | Gateway validation rejected a non-positive `tagId`/session id, a name over 500 characters or containing control characters, or a blank/over-28-character/control-containing `assignedUserId` | Correct the field constraint reported by the gateway. |
| `http_400` | Back-end validation rejected a forwarded value, such as an unsupported `enrichmentType` | Correct the request value reported by the back end. |
| `tag_not_found` | The selected tag does not exist in the active account | Verify `tagName` or `tagId`. |
| `session_not_found` | The numeric dialer session id does not exist in the active account | Verify the id passed to `status`. |
| `user_not_found` or `assigned_user_not_found` | The caller or assignee could not be resolved | Re-authenticate or choose a current member from `account users`. |
| `tag_name_ambiguous` | More than one account tag has the selected name | Copy `error.meta.tags[].id` into `audience.tagId` and retry. |
| `assignment_not_allowed` | The caller may not assign this session to another user | Only an account Owner may assign another user. Self-assign or omit `assignedUserId`. |
| `assigned_user_not_in_account` | The assignee is not a current member of the active account | Choose a current member from `landbase-cli account users`. |
| `dialer_channel_permission_required` | The session owner does not have dialer access | Choose a user with dialer access or update their permissions in Landbase. |
| `AUTH_FAILED` | Missing or expired platform session | Run `landbase-cli auth login`. |
To create a session from a new CSV, complete `contacts-import` first, then use
the resulting tag in the create config.
## Related
* [contacts-import](/docs/reference/contacts-import) — create the source tag
* [account users](/docs/reference/account#account-users) — find an `assignedUserId`
* [Output schemas](/docs/reference/output-schemas#dialer-sessions) — response field reference
* [Error codes](/docs/reference/error-codes) — stable CLI error codes