Envelopes

Envelopes are the core resource in Loyva. An envelope represents a document sent for electronic signature.

All partner envelope endpoints are mounted under /api/v2/partner/* and authenticated with X-API-Key: lk_.... Every successful response is wrapped in { "data": ... }. List responses include a meta page object.

Envelope lifecycle

pending → uploaded/preparing → sent → viewed → completed → vaulted
                                     ↘ declined
                                     ↘ voided
                                     ↘ expired

Status	Description
pending	Created but not yet prepared
uploaded / preparing	Upload or wizard in progress
sent	Sent to signers, awaiting action
viewed	At least one signer has opened the document
completed	All signers have signed; vault pipeline may still be running
vaulted	Authoritative copy stored + compliance certificate generated
declined / voided / expired	Terminal non-success states

---

List envelopes

GET /partner/envelopes

Required scope: envelopes:read

Query parameters: page, limit (max 100), customer_id, status (any lifecycle value).

Response:

{
  "data": [
    {
      "envelope_id": "env_x7k9m2p4q1w3",
      "envelope_name": "Q1 Sales Agreement",
      "status": "completed",
      "customer_id": "cust_abc123",
      "external_id": "ext_order_4521",
      "created_at": "2026-04-01T10:00:00.000Z",
      "updated_at": "2026-04-05T14:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 42 }
}

---

Get envelope

GET /partner/envelopes/:id

Required scope: envelopes:read

Metadata is filtered to a partner-safe subset.

{
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "envelope_name": "Q1 Sales Agreement",
    "status": "vaulted",
    "customer_id": "cust_abc123",
    "external_id": "ext_order_4521",
    "template_id": "tmpl_lease_v2",
    "created_at": "2026-04-01T10:00:00.000Z",
    "updated_at": "2026-04-11T10:16:10.000Z",
    "vaulted": true,
    "compliant": true,
    "metadata": { /* partner-safe subset */ }
  }
}

---

Get status

GET /partner/envelopes/:id/status

Required scope: envelopes:read

Lightweight status + vault summary — use this for polling.

{
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "status": "vaulted",
    "vaulted": true,
    "compliant": true,
    "signed_at": "2026-04-11T10:14:55.000Z",
    "updated_at": "2026-04-11T10:16:10.000Z"
  }
}

The compliant flag reflects whether a certificate has been generated. Call GET /partner/envelopes/:id/compliance for the full 8-check result.

---

Create envelope

POST /partner/envelopes

Required scope: envelopes:write

Partners identify the customer by email + name. Loyva provisions the customer on the fly if needed.

Field	Type	Required	Description
envelope_name	string	Yes	Display name
customer_email	string	Yes	Customer email
customer_name	string	Yes	Customer display name
template_id	string	No	Template to use
external_id	string	No	Your system's reference ID
prefilled_data	object	No	Template field pre-fill
secured_party	object	No	{ name, role?, address?, email?, identifier? } — populate for UCC Check 8

Response: 201 Created with { "data": { "envelope_id": "...", ... } }. Also fires the envelope.created webhook.

---

Get signing links

GET /partner/envelopes/:id/signing-links

Required scope: envelopes:read

Returns one short-lived embed URL per signer. Use these to redirect the signer to the Loyva signing page, or email the URLs to recipients.

{
  "data": {
    "signers": [
      {
        "email": "[email protected]",
        "name": "John Smith",
        "slug": "abc123",
        "embed_url": "https://embed.stg.loyva.net/sign/env_x7k9m2p4q1w3",
        "status": "pending"
      }
    ]
  }
}