> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Executive-assistant call delegation

> Set up boss/admin call delegation — an executive registers assistants as delegates, picks a distribution mode (screen-first, simultaneous, assistant-first, exec-first), scopes each delegate's on-behalf actions, and rotates the roster over time. Covers policy design, testing the ring path, the hand-to-exec flow, lifecycle audit, and a worked law-firm roster rotation.

Executive-assistant delegation is the boss/admin pattern: an executive registers assistants as **delegates** and shares control of their inbound calls. The executive always owns the call; the delegates answer, screen, transfer, place on the executive's behalf, or monitor the executive's line, depending on the actions each one is granted. This page walks the whole lifecycle — from designing the delegation policy, through testing the ring path, to rotating the roster and auditing who delegates to whom.

Delegation on Orbit is self-service: the executive saves their own policy (on the `/me/voice-preferences` page or over the API under `GET/PUT/DELETE /api/v1/voice/delegation/policy`), so an offboarding assistant is cut off the same day, without a supervisor ticket. The policy lives on the executive's own user record, so the same controls that gate your other per-user preferences gate it.

## 1. The delegation model

A delegation policy is owned by exactly one executive and grants one or more assistants (delegates) a subset of **on-behalf actions**:

* `screen` — answer first, announce the caller, then extend (or decline) to the executive. The classic assistant screen.
* `answer` — answer calls on the executive's behalf outright.
* `place` — place outbound calls as the executive (the executive's line is the caller id).
* `transfer` — move the executive's live calls (blind or attended).
* `monitor` — watch the executive's live-call state as an actionable surface, not just a read-only busy lamp.

The executive inherently holds `answer`, `place`, and `transfer` on their own line. Every delegated action is an explicit grant — a delegate performs only the actions their grant lists.

### How this differs from SLA, ring groups, and per-line preferences

Delegation is an **owner-grants-delegate** relationship: one owner, one policy, explicit per-delegate action scopes. It is not a queue (no FIFO hold), not a shared line, and not the generic "delegate to a teammate" coverage arrow in the `/me/voice-preferences` ladder.

* **Shared Line Appearance (SLA)** mirrors one named line onto a roster of devices — members ring, watch a busy lamp, and grab the answered call. A delegation across the whole tenant is still a delegation; getting the executive's *number* to ring on devices is SLA's job, and the two stack naturally.
* **Ring groups / queues** answer "ring these devices" with no ownership and no per-user action scoping.
* **`/me/voice-preferences`** covers per-user rules — delegation is one of the panels there; this page covers the tenant-wide workflow around it.

## 2. Identify the delegation scope per relationship

Decide, per executive–assistant pair, which actions the delegate needs — the policy accepts only what it names, so scoping down is enforcement, not documentation.

* **Full call-handling scope** — the delegate holds every action (`screen`, `answer`, `place`, `transfer`) and behaves as a full assistant.
* **Answer-only** — grant `answer` (optionally with `monitor`); the delegate takes calls but can't move them or place new ones as the executive.
* **Screen-only** — grant `screen`; the delegate answers, announces, and extends, but can't transfer elsewhere or place outbound.
* **Transfer-only** — grant `transfer`; the delegate moves live calls but can't pick them up first.
  A delegate with no grant is denied — the per-leg check is authoritative, so a scoped delegate is genuinely scoped.

Max 10 delegates per executive, and every delegate must be an active user in the executive's own organization (a rejected save names the unknown ids).

## 3. Register a delegate

Build the client picker (or the boss-admin editor) from `GET /api/v1/voice/delegation/capabilities` — it returns the action kinds, ring modes, and bounds (max delegates, screen-timeout and ring-priority ranges). It is static and cacheable.

Preview before saving: `POST /api/v1/voice/delegation/plan` validates a policy and returns the resolved plan (ordered ring stages, per-leg permitted actions, shared-ownership decision) without persisting anything. Once the plan reads the way you want, persist it:

```bash cURL theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/delegation/policy" \
  -H "Authorization: Bearer <session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "executive_user_id": "user_exec_sara_kim",
    "ring_mode": "screen_first",
    "screen_timeout_sec": 20,
    "grants": [
      {
        "assistant_user_id": "user_dana_chen",
        "assistant_label": "Dana (assistant pool)",
        "actions": ["screen", "transfer"],
        "ring_priority": 0
      },
      {
        "assistant_user_id": "user_marc_hill",
        "assistant_label": "Marc (assistant pool)",
        "actions": ["screen", "transfer"],
        "ring_priority": 10
      }
    ]
  }'
```

The response returns the stored policy plus its resolved plan. Rules enforced at save time:

* `executive_user_id` must be the authenticated user (else `403`). This guide uses a sandbox `dv_test_sk_*` header form for server-to-server reads, but the save must be the executive's own session identity.
* Every `assistant_user_id` must be an active user in your organization (else `422` naming the unknown ids).
* `screen_first` needs at least one delegate granted the `screen` action (else `400`/`422`).
* An executive cannot be their own delegate; duplicate delegates and duplicate actions are rejected.

The policy materializes on the executive's user record immediately — there is no separate certificate object to fetch. `GET /api/v1/voice/delegation/policy` returns `{ policy, plan }` or `{ policy: null, plan: null }`.

## 4. Test the ringing path

Call the executive's DID (or dial their extension internally) and watch against the resolved plan:

* **`screen_first`** — stage 0 rings the delegates (`kind: "screen"`); on no answer within `screen_timeout_sec` it rolls to the executive (stage 0 → stage 1). Verify the assistant's softphone rings first and the executive's device rings only if no delegate answers.
* **`simul_ring`** — executive plus every delegate ring together; first answer takes it. Verify all devices light at once.
* **`assistant_first`** — delegates are the primary answer point; roll to the executive on no answer.
* **`exec_first`** — executive rings first, delegates are the no-answer backup.

In every mode, compare what you observe against `stages[].kind` and `stages[].participants[]` in the saved plan — the plan is the exact alert ladder. Tune `screen_timeout_sec` between 5 and 120 seconds (default 20); `ring_priority` orders delegates within a stage (lower rings earlier, ties break on the user id).

## 5. Hand-to-exec flow

With `shared_ownership` enabled (the default), whichever delegate answers shares ownership of the call with the executive — the delegate screens, announces the caller, then extends it to the executive; the caller experiences a bridged live handoff, not a cold transfer with a new ring. Either party can then transfer or end the call. Disable `shared_ownership` and the answering delegate holds the leg until they explicitly extend it — a tighter screen, but a longer stay for the caller.

Against a plain `/api/v1/voice/calls/:id/transfer`, the difference is the relationships: the plane consults the executive's saved delegation plan on the inbound call, so a delegate extends to their own executive without a lookup, while a plain transfer targets any destination with no delegation context.

## 6. Delegate lifecycle

Rotation is a full-policy **replace**, not an append: `PUT /api/v1/voice/delegation/policy` overwrites the grants list — re-PUT the desired roster each time. Deregister one delegate by re-saving without them; revoke everything with `DELETE /api/v1/voice/delegation/policy` (`{ deleted: true }` when a policy existed).

Audit who delegates to whom by reading each executive's `GET /policy` on rotation day and capturing `{ policy, plan }` — the current grants and resolved stage ladder in one payload. Every save, revoke, or re-grant is written to the tenant audit log with actor, timestamp, and the policy payload's before/after diff, so a roster dispute is answered in the log, not in email (see [the audit log guide](/guides/audit-log)). On a role change — for instance when an assistant leaves the pool — revoke their grant the same day; the self-scoped policy means the executive can do it without waiting on an admin.

## 7. Relationship to shared lines

[Shared Line Appearance](/guides/shared-lines-appearance) handles the per-line-attention model: a roster of devices sharing a line's identity, with a busy lamp and a grab action. Delegation (this page) covers the executive-assistant workflow across the whole tenant: who the executive's delegates are, what actions each may take, and the assistant-to-executive handoff. Use them together — SLA for the shared line, delegation for the on-behalf relationship.

Related sibling surfaces: the `/me/voice-preferences` ladder's per-user coverage arrow is narrower (roll-to-one-teammate; see [Self-service calling rules](/guides/me-voice-preferences)), and [inbound DID routing](/guides/inbound-number-routing) is where the executive's number is pointed at the right surface.

## 8. Worked example: a law firm's assistant pool

A firm with 40 partners keeps a shared assistant pool. Partner **Sara Kim** delegates to pool members **Dana** and **Marc**, screen-first, as in [section 3](#3-register-a-delegate). Dana screens, sees the caller is a client Sara will take, and extends — Sara's phone rings with the call already announced.

**Friday rotation:** the firm's rotation script re-PUTs each partner's policy with the next week's pool roster — a put, not an append, so Friday's save replaces Thursday's delegates. `ring_priority` keeps the pool deterministic: Dana at `0`, Marc at `10`, and the pool lead can be bumped to ring earlier for busy partners. An assistant leaving the pool drops out of every pool policy at the next rotation; a partner can also revoke individually the same day. The Friday script captures each partner's `GET /policy` payload, so the firm holds an audit snapshot of who delegates to whom for each rotation week.

***

**See also:** [Shared Line Appearance](/guides/shared-lines-appearance) · [Self-service calling rules](/guides/me-voice-preferences) · [Pick the right inbound routing for a DID](/guides/inbound-number-routing) · [Audit Log](/guides/audit-log)