---
title: "Create a parallel-dialer session in PAUSED state"
method: POST
path: "/voice/dialer/sessions"
tags: ["Voice"]
---

# Create a parallel-dialer session in PAUSED state

`POST /voice/dialer/sessions`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/voice/dialer/sessions`
- Auth: HTTP bearer

Create a new parallel-dialer session bound to the caller's org.

The session is created in ``PAUSED`` state - no calls are placed
until the SDR opens the dialer UI and joins the Twilio conference.
The chat caller can then use ``PATCH /voice/dialer/sessions/{id}/status``
or any frontend control to pause / resume / stop later.

Org and user are pinned server-side from the API key. The caller
cannot override them.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- DialerSessionCreateRequest: Body for creating a parallel-dialer session in PAUSED state. The session is created paused so the SDR can open the dialer UI and start dialing on their own time. Org and user are pinned server-side from the API key - any value supplied here is ignored. Required: ``name``, ``from_phone``. Optional: ``list_id`` / ``list_title`` (carried in session metadata), ``agent_id`` (V2 agent UUID - use ``GET /voice/dialer/agents`` to look up), ``studio_campaign_id`` (Campaign Builder UUID for studio campaign linkage).
  - `name` string, required: Session display name.
  - `from_phone` string, required: Caller-ID phone number. Must be one of the org's dialer numbers.
  - `list_id` string, nullable: Contact list ID the SDR will dial from. Stored in session metadata.
  - `list_title` string, nullable: Display title for the list (e.g. 'Q4 ICP'). Stored in metadata.
  - `agent_id` string, nullable: Voice agent UUID. Use GET /voice/dialer/agents to look up.
  - `agent_name` string, nullable: Legacy V1 agent name fallback (defaults to "default_agent" upstream).
  - `entity_type` string, nullable: V2 agent entity type ("agent" or "twin"). Optional.
  - `studio_campaign_id` string, nullable: Campaign Builder (Studio) campaign UUID. Optional linkage.
  - `user_timezone` string, nullable: IANA timezone for analytics grouping (e.g. "America/New_York").
  - `skip_voicemails` boolean, nullable: Per-session override for voicemail-skip behaviour. None = use SDR default.
  - `parallel_count` integer, nullable: Legs to dial per batch once the SDR opens the dialer UI (1 = power mode, 2-5 = parallel). None keeps voice's own default (2). Bug fix (graph8-com/g8 dev-API voice parity): this field previously had no effect - it was accepted by neither this DTO nor the upstream call, so any value a caller sent was silently dropped rather than forwarded.
  - `dialing_mode` 'power' | 'parallel', nullable: Override the session's dialing mode. None keeps voice's default ('power'). Same bug-fix note as parallel_count above - now forwarded instead of dropped.

## Response `201`

Successful Response

- ApiResponseDialerSessionCreateResponse
  - `data` DialerSessionCreateResponse, required: Echo of the voice service's ``ParallelDialResponse`` for a paused-create. We deliberately drop ``twilio_token`` from the public shape - it is SDR-frontend-specific and is regenerated by the dialer UI on join, so re-publishing it here would only confuse a chat caller.
    - `session_id` string, required
    - `status` string, required
    - `name` string, nullable
    - `org_id` string, nullable
    - `user_id` string, nullable
    - `user_email` string, nullable
    - `from_phone` string, nullable
    - `session_metadata` object, nullable
    - `total_calls` integer
    - `created_at` unknown
    - `message` string, nullable
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/89fc11143b70?raw)