> ## 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.

# Voice Signatures (Verbal Contracts)

> Capture the spoken 'yes, I agree' moment of a call recording as a discrete, indexed compliance artifact tied to an order, loan, or policy reference.

# Voice Signatures (Verbal Contracts)

Regulated tele-sales, lending, and insurance operations must keep the
exact moment a customer verbally agreed to a contract — the spoken
"yes, I agree to the terms" — as a discrete, retrievable piece of
evidence. A voice signature marks that moment on a call recording: a
timed segment `start_ms`/`end_ms` bound to your external transaction
reference (order id, loan-application id, policy number).

<Warning>
  This page describes Orbit's platform controls. It is **not legal
  advice.** Whether a verbal agreement is binding, what a disclosure
  script must contain, and how long evidence must be retained varies
  by jurisdiction and by sector (tele-sales, lending, insurance, debt
  collection carry their own rules). Confirm obligations with
  qualified counsel before you rely on voice signatures in a dispute.
</Warning>

***

## The discrete artifact

A voice signature is a segment marker on an **existing recording** —
not a separate media file and not a free-text note. Each capture
stores:

* **Segment boundaries** — `start_ms` / `end_ms` offsets into the
  parent recording, so the isolated moment can be played back through
  the recording playback surface.
* **Transaction reference** — `transaction_ref`, your external id for
  the order, loan, or policy the customer agreed to. It is a fast
  lookup key, not a foreign key to any Orbit entity.
* **Classification** — `agreement_type`
  (`tele_sales`, `lending`, `insurance`, `debt_collection`,
  `subscription`, or `other`) and `outcome` (`agreed` or `declined`),
  so a compliance report can group evidence per regulated vertical.
* **Optional context** — the verbatim `script_text` read to the
  customer, a `transcript_excerpt` of what the customer said, the
  `language` of the agreement, and the `jurisdiction` it governs.

Bounds are validated server-side: `end_ms` must exceed `start_ms`, and
when the recording's duration is known the segment must fall inside it
(a one-second tolerance applies because duration is stored at second
granularity). A single recording can hold up to 100 voice signatures —
enough for bundled policies or add-ons captured on one call.

***

## Endpoints

All three endpoints live under your tenant's `/compliance` namespace
and require an authenticated session (any role that can read
recordings can read voice signatures).

### Capture a voice signature

`POST /compliance/voice-signatures`

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/compliance/voice-signatures \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_id": "rec_d81f…",
    "transaction_ref": "POLICY-2026-84171",
    "agreement_type": "insurance",
    "outcome": "agreed",
    "start_ms": 183400,
    "end_ms": 195100,
    "script_text": "Do you agree to the terms and authorise the monthly premium of €42?",
    "transcript_excerpt": "Yes, I agree.",
    "language": "en-IE",
    "jurisdiction": "IE",
    "notes": "Agent read the mandated disclosure twice."
  }'
```

| Field                 | Required | Meaning                                                                                                   |
| --------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `recording_id`        | Yes      | The recording the segment belongs to. Must resolve for your tenant and not be deleted.                    |
| `transaction_ref`     | Yes      | Your external transaction id (order / loan / policy), up to 256 chars.                                    |
| `agreement_type`      | No       | `tele_sales` / `lending` / `insurance` / `debt_collection` / `subscription` / `other` (default `other`).  |
| `outcome`             | No       | `agreed` / `declined` (default `agreed`). Capture refusals too — they close disputes the other direction. |
| `start_ms` / `end_ms` | Yes      | Integer segment offsets from recording start. `end_ms` must exceed `start_ms`.                            |
| `script_text`         | No       | Verbatim disclosure that was read to the customer (up to 4000 chars).                                     |
| `transcript_excerpt`  | No       | What the customer actually said (up to 8000 chars).                                                       |
| `language`            | No       | BCP-47 language code of the agreement.                                                                    |
| `jurisdiction`        | No       | Jurisdiction code the agreement falls under (`IE`, `US-CA`, `DE`, …).                                     |
| `notes`               | No       | Free-form operator note (up to 1000 chars).                                                               |

The capture returns `201` with the persisted descriptor. Every capture
is recorded in your audit log as `compliance.voice_signature_captured`
with the recording id, transaction reference, agreement type, outcome,
and segment boundaries.

**Errors.** `404 VOICE_SIGNATURE_RECORDING_NOT_FOUND` when no recording
matches the id for your tenant. `422 VOICE_SIGNATURE_INVALID_RANGE`
when the offsets are incoherent or exceed the recording duration.
`422 VOICE_SIGNATURE_LIMIT_REACHED` when the recording already holds
the maximum of 100 signatures.

### List a recording's voice signatures

`GET /compliance/voice-signatures?recording_id=<id>`

Returns every clip captured against the recording, newest first — an
empty array when the recording exists but none were captured. Returns
`404` when the recording id does not resolve for your tenant.

### Retrieve one voice signature

`GET /compliance/voice-signatures/<signature_id>?recording_id=<id>`

Returns the clip descriptor plus a `segment` block carrying the parent
recording id, the ms boundaries, and the computed duration — pass the
recording id and the boundaries to your existing recording playback or
signed-URL surface to play or download exactly the isolated moment.
Returns `404 VOICE_SIGNATURE_NOT_FOUND` when neither the recording nor
the clip id matches for your tenant.

<Note>
  Neither retrieval endpoint re-derives media. The voice signature is
  a marker; playback continues through the recording playback surface
  you already use, so no second copy of the audio is ever minted.
</Note>

***

## Persistence and lifecycle

Voice signatures persist under the `voice_signatures` key of the
recording's existing metadata — **no separate table and no migration**.
That placement is deliberate: a clip inherits the parent recording's
lifecycle for free.

* **Retention.** Your recording retention window deletes a signature
  with its recording; there is no second TTL to configure.
* **Legal hold.** Holding the recording holds its signatures — a hold
  can never be bypassed by deleting a clip independently.
* **GDPR erasure.** Erasing a recording erases its signatures in the
  same operation, so a data-subject deletion request cannot strand
  verbal-contract evidence.
* **Tenant isolation.** Clips resolve only against your own
  organization id; a recording id from another tenant returns `404`.

***

## How this differs from the other consent artifacts

Orbit holds three separate consent-adjacent artifacts. They answer
different questions and none substitutes for another:

| Artifact                          | Question it answers                                        | Where it lives                                                                         |
| --------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Voice signature** (this page)   | "Did the customer verbally agree to these specific terms?" | Segment marker on a recording, tied to a transaction reference                         |
| **Recording-consent receipt**     | "Did the parties consent to being *recorded*?"             | Per-call consent receipt — see [Call Recording Consent](/compliance/recording-consent) |
| **Free-text verbal-consent note** | "What did an agent note down about a conversation?"        | Unstructured note on the contact record — not timed, not retrievable as a clip         |

Recording consent makes the recording lawful; a voice signature makes
the *content* of the agreement retrievable. Capture both in regulated
flows — the first gates the media, the second proves the contract.

***

## Role gating and audit

Reading and writing voice signatures requires the same authenticated
session as the recordings they annotate. Writes are validated
server-side against the parent recording — a session that cannot reach
the recording cannot attach a signature to it.

Every capture writes an audit log entry
(`compliance.voice_signature_captured`) with the actor, the recording
id, the transaction reference, the agreement type, the outcome, and
the segment boundaries, so a reviewer can reconstruct who marked which
moment on which recording.

***

## Tenant-owned posture

The voice-signature surface is a **control, not a conclusion**. You
decide which calls need a verbal-contract artifact, what disclosure
your agents read, which external systems supply the transaction
reference, and how long evidence is retained. Orbit stores and indexes
the marker and enforces tenant isolation, bounds, and audit — the
regulatory judgement about whether a given capture satisfies a
specific obligation stays with you and your counsel.

***

## Related references

* [Call Recording Consent](/compliance/recording-consent) — lawful
  capture of the recordings a voice signature marks.
* [Legal Hold](/compliance/legal-hold) — freeze a recording and its
  signatures against retention.
* [DSAR and Erasure](/compliance/dsar) — how a deletion request
  propagates to recordings.
* [Evidence Binder](/compliance/evidence-binder) — assemble voice
  signatures into a regulator-facing bundle.