---
title: "Create Handoff Connection"
method: POST
path: "/core/handoff/connections"
tags: ["Human Handoff"]
---

# Create Handoff Connection

`POST /core/handoff/connections`

## Request

- Base URL: `https://api.anyreach.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.anyreach.ai/core/handoff/connections`
- Auth: HTTP bearer

Create a handoff connection for the caller's organization.

Credentials go in through ``api.save_handoff_connection`` — the ``api``
view has no writable ``auth_details`` column at all — and the row is read back
through the view, so what comes out has never carried the token.

## Headers

- `x-anyreach-org` string, nullable: Organization ID for user PATs (pat_ prefix tokens)

## Request body

- HandoffConnectionCreateRequest: Body for ``POST /handoff/connections``.
  - `provider` string: Handoff provider. Only 'gladly' is supported today.
  - `name` string, required: Human-readable label for this connection
  - `auth_details` HandoffAuthDetails, required: Credentials for one handoff connection (``handoff_connections.auth_details``). Deliberately stored on the connection row rather than in the agent config: agent configs are versioned and snapshotted onto every conversation, so a token in there would be copied into thousands of rows (PRD §6).
    - `base_url` string, required
    - `username` string, required
    - `api_token` string, required
  - `webhook_secret` string, nullable: Shared secret used to verify inbound webhook signatures
  - `settings` HandoffConnectionSettings: How this helpdesk behaves — as opposed to how to reach it. These sit on the connection rather than on an escalation rule because they describe the HELPDESK, not the route: how fast that team answers and what context it wants to receive. Change one here and every agent routing through this connection follows, which is the point — an SLA is not a per-agent setting. Customer-facing copy deliberately does NOT live here. It is spoken in the agent's voice and language, and one connection is shared by every agent in the org, so a shared waiting message would put the wrong language in front of somebody. That stays on the rule.
    - `no_reply_after_seconds` integer: Post the rule's waiting message when no human has replied for this long.
    - `idle_close_after_minutes` integer: Close an idle handoff — and finalize the conversation — after this long with no activity.
    - `context_mode` 'summary' | 'transcript' | 'both': What the human agent is handed when the handoff opens.
    - `idle_archive_after_minutes` integer: Push every chat and email conversation on an agent that escalates through this helpdesk into it as a CLOSED conversation, once the customer has sent nothing for this long. Only what was not already pushed is sent, under the same customer identity, so a thread that picks up again lands in the same place. 0 turns it off.
    - `topics_workflow_id` string, nullable: Workflow that chooses the helpdesk topics for a conversation. Run once per record the helpdesk receives — when an escalation opens and each time the idle archive files a segment — with the conversation, the segment and the helpdesk's topic catalog as input; its `topicIds` output is added to the helpdesk conversation. Always runs the workflow's live version (else its newest published one), so publishing is deploying. Blank means no topics are set from here.
  - `enabled` boolean

## Response `200`

Successful Response

- HandoffConnectionResponse: A handoff connection as any caller is allowed to see it. Explicitly modelled rather than returning the entity, so no future field added to ``HandoffConnection`` can leak a credential by default. ``auth_details`` here is the ``{base_url, username}`` pair only.
  - `id` string, required
  - `organization_id` string, required
  - `provider` string, required
  - `name` string, required
  - `auth_details` object
  - `has_webhook_secret` boolean
  - `settings` HandoffConnectionSettings: How this helpdesk behaves — as opposed to how to reach it. These sit on the connection rather than on an escalation rule because they describe the HELPDESK, not the route: how fast that team answers and what context it wants to receive. Change one here and every agent routing through this connection follows, which is the point — an SLA is not a per-agent setting. Customer-facing copy deliberately does NOT live here. It is spoken in the agent's voice and language, and one connection is shared by every agent in the org, so a shared waiting message would put the wrong language in front of somebody. That stays on the rule.
    - `no_reply_after_seconds` integer: Post the rule's waiting message when no human has replied for this long.
    - `idle_close_after_minutes` integer: Close an idle handoff — and finalize the conversation — after this long with no activity.
    - `context_mode` 'summary' | 'transcript' | 'both': What the human agent is handed when the handoff opens.
    - `idle_archive_after_minutes` integer: Push every chat and email conversation on an agent that escalates through this helpdesk into it as a CLOSED conversation, once the customer has sent nothing for this long. Only what was not already pushed is sent, under the same customer identity, so a thread that picks up again lands in the same place. 0 turns it off.
    - `topics_workflow_id` string, nullable: Workflow that chooses the helpdesk topics for a conversation. Run once per record the helpdesk receives — when an escalation opens and each time the idle archive files a segment — with the conversation, the segment and the helpdesk's topic catalog as input; its `topicIds` output is added to the helpdesk conversation. Always runs the workflow's live version (else its newest published one), so publishing is deploying. Blank means no topics are set from here.
  - `enabled` boolean
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable
  - `created_by` string, nullable
  - `modified_by` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/anyreach/apis/anyreach-api.md) - [All operations](https://skmtc.dev/anyreach/apis/anyreach-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anyreach/apis/anyreach-api/revisions/2eddf40c8c93?raw)