Partner Integration

Partners integrate with Loyva by using API keys to authenticate server-to-server requests. Partner endpoints are scoped and isolated — you can only access resources within your organization.

Integration architecture

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│  Partner Backend  │         │    Loyva API      │         │   Loyva Vault    │
│                   │         │                   │         │                  │
│  X-API-Key: lk_.. │────────>│  /partner/*       │────────>│  Storage         │
│                   │<────────│  Scoped by org    │<────────│  Compliance      │
│                   │         │                   │         │                  │
└──────────────────┘         └──────────────────┘         └──────────────────┘
        │                             │
        │   Webhook events            │  Embed tokens (in progress)
        │<────────────────────────────│
        │                             │
        │         ┌──────────────────┐│
        │         │  User's Browser   ││
        │────────>│  Loyva signing    │<─────────────────────
                  │  iframe (WIP)     │  iframe
                  └──────────────────┘

What you get

The full e-sign + e-vault lifecycle is exposed via REST. Embed widgets are an additional UI layer — see the note at the bottom.

E-sign + envelope lifecycle

Feature	Endpoint	Scope required
Create e-sign envelope	POST /partner/envelopes	envelopes:write
Create paper envelope	POST /partner/envelopes (envelope_kind: paper)	envelopes:write
Upload pre-signed PDF	POST /partner/envelopes/:id/upload	envelopes:write
List envelopes (with contract terms), filter by customer or status	GET /partner/envelopes	envelopes:read
Get envelope details, contract terms + signed field values	GET /partner/envelopes/:id	envelopes:read
Check status	GET /partner/envelopes/:id/status	envelopes:read
List customers	GET /partner/customers/list	customers:read
Look up a customer by client id or email	GET /partner/customers	customers:read
Get signing links	GET /partner/envelopes/:id/signing-links	envelopes:read
Send reminders	POST /partner/envelopes/:id/remind	envelopes:write
Void / cancel	POST /partner/envelopes/:id/void	envelopes:write

E-vault — vault-in, retrieval, vault-out

Feature	Endpoint	Scope required
Vault completed e-sign (recovery)	POST /partner/envelopes/:id/vault-in-signed	vault:write
Vault uploaded paper PDF	POST /partner/envelopes/:id/vault-in-upload	vault:write
Download authoritative copy	GET /partner/envelopes/:id/vault/signed-url	vault:read
Download non-authoritative copy	GET /partner/envelopes/:id/vault/copy/signed-url	vault:read
Check UCC §9-105 compliance	GET /partner/envelopes/:id/compliance	compliance:read
Get compliance certificate	GET /partner/envelopes/:id/vault/certificate	compliance:read
Vault-out (release)	POST /partner/envelopes/:id/vault-out	vault:release

Configuration

Feature	Endpoint	Scope required
Manage webhook endpoints	/webhooks/endpoints	Admin JWT (see Managing endpoints)
Update legacy webhook URL / secret	PATCH /partner/webhook	envelopes:write
Mint embed token	POST /embed/token	esign:write or vault:read
Receive webhooks	Outbound to your endpoints	Per-endpoint event subscription

End-to-end flows

There are three end-to-end flows partners can drive entirely from the API:

1. E-sign + auto-vault — Create with template_id, customer signs in DocuSeal, envelope.completed fires with the filled-in field data, the envelope auto-vaults, and vault.stored fires.
2. Paper / pre-signed PDF — Create with envelope_kind: "paper", upload PDF, call vault-in-upload.
3. Vault-out at end of lifecycle — After any vaulted envelope, call vault-out to release the authoritative copy to a recipient (e.g., a secured party at loan funding).

See Partner Endpoints for full request/response examples.

Reading contract data

Contract terms (monthly rate, term, start date, renewal date, and the computed contract value) are returned as a fixed contract object on GET /partner/envelopes and GET /partner/envelopes/:id. You can call these at any time, so you don't need to store them from the envelope.completed webhook. Use the detail endpoint to read back the raw values filled into the signed document (fields).

curl "https://api.stg.loyva.net/api/v2/partner/envelopes/env_x7k9m2p4q1w3" \
  -H "X-API-Key: lk_..."

{
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "status": "vaulted",
    "contract": {
      "monthly_rate_cents": 4999,
      "billing_cycle": "monthly",
      "term_months": 36,
      "start_date": "2026-06-01",
      "renewal_date": "2029-06-01",
      "contract_value_cents": 179964
    }
  }
}

contract is null until the terms are recorded for that envelope. Terms come from template fields captured at signing, from AI extraction that a user reviewed and confirmed, or from manual entry in Loyva. See Contract terms for every field.

Getting started

1. Get an API key from your Loyva point of contact (see API Keys)
2. Test with the API — create an envelope, send it for signing, vault it, retrieve the compliance certificate
3. Configure webhooks — register an endpoint and subscribe to the events you need, starting with envelope.completed
4. Go live — swap dev keys for production keys

Embedded widgets

Embedded signing and vault widgets are on the roadmap. The POST /embed/token endpoint is live (see Embed tokens), but the companion JavaScript SDK and iframe host are not yet published. The full e-sign and e-vault lifecycle (including vault-in and vault-out) can be driven entirely via REST today — embedded widgets are an optional UI layer for partners who want to render Loyva-branded signing inside their own app. Coordinate with your Loyva point of contact if you need embedded signing.