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	GET /partner/envelopes	envelopes:read
Check status	GET /partner/envelopes/:id/status	envelopes: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
Update webhook URL / secret	PATCH /partner/webhook	envelopes:write
Mint embed token	POST /embed/token	esign:write or vault:read
Receive webhooks	Outbound to your URL	Configured per key

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, queue worker auto-vaults, vault.stored webhook 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.

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 — get real-time updates on envelope events
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.