Partner Endpoints

Partner endpoints live under /api/v2/partner/* and are authenticated with X-API-Key. They mirror the internal endpoints but are scoped to your organization.

Endpoints

E-sign + envelope lifecycle

Method	Path	Scope	Description
GET	`/partner/envelopes`	`envelopes:read`	List envelopes
GET	`/partner/envelopes/:id`	`envelopes:read`	Get envelope
GET	`/partner/envelopes/:id/status`	`envelopes:read`	Get status only (lightweight polling)
POST	`/partner/envelopes`	`envelopes:write`	Create envelope (e-sign or paper)
POST	`/partner/envelopes/:id/upload`	`envelopes:write`	Upload pre-signed PDF (paper flow)
POST	`/partner/envelopes/:id/void`	`envelopes:write`	Void / cancel envelope
POST	`/partner/envelopes/:id/remind`	`envelopes:write`	Send signing reminder(s)
GET	`/partner/envelopes/:id/signing-links`	`envelopes:read`	Get per-signer signing URLs

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

Method	Path	Scope	Description
POST	`/partner/envelopes/:id/vault-in-signed`	`vault:write`	Vault a completed e-sign envelope (manual / recovery)
POST	`/partner/envelopes/:id/vault-in-upload`	`vault:write`	Vault a paper / uploaded PDF
GET	`/partner/envelopes/:id/vault/signed-url`	`vault:read`	Download URL (authoritative)
GET	`/partner/envelopes/:id/vault/copy/signed-url`	`vault:read`	Download URL (non-authoritative copy)
GET	`/partner/envelopes/:id/vault/certificate`	`compliance:read`	UCC §9-105 compliance certificate JSON
GET	`/partner/envelopes/:id/compliance`	`compliance:read`	Run compliance check synchronously
POST	`/partner/envelopes/:id/vault-out`	`vault:release`	Release authoritative copy out of the live vault

Configuration

Method	Path	Scope	Description
PATCH	`/partner/webhook`	`envelopes:write`	Update webhook URL / secret
POST	`/embed/token`	`esign:write` / `vault:read`	Mint embed token

How partner endpoints work

Auth: All partner endpoints use X-API-Key: lk_...
Scoping: Every response is automatically scoped to the organization tied to the key
No org header required: The organization is derived from the API key
Scoped by permission: Each endpoint requires an explicit scope on your key — see Scopes

Creating an envelope

POST /partner/envelopes supports two flows:

envelope_kind: "esign" (default) — DocuSeal-driven signing. Pass template_id and an optional signers[] array for multi-signer deals. Returns a sign_url.
envelope_kind: "paper" — Partner-uploaded pre-signed PDF. Skips DocuSeal. Next step is POST /partner/envelopes/:id/upload.

E-sign flow

{
  "customer_email": "buyer@example.com",
  "customer_name": "Jane Buyer",
  "template_id": "tmpl_abc123",
  "signers": [
    { "email": "buyer@example.com", "name": "Jane Buyer", "role": "Buyer" },
    { "email": "cosigner@example.com", "name": "John Cosigner", "role": "Co-Signer" }
  ]
}

customer_email and customer_name are always required (used for customer record lookup/upsert). The signers array, when provided, determines the DocuSeal submitter list — each entry maps to one signing URL returned by GET .../signing-links.

tip

When using signers[], the role values must match the submitter role names defined in your DocuSeal template. If omitted, roles default to Signer 1, Signer 2, etc.

Paper / pre-signed PDF flow

{
  "customer_email": "buyer@example.com",
  "customer_name": "Jane Buyer",
  "envelope_kind": "paper"
}

Returns an envelope with status: "uploaded" and envelope_kind: "paper". Then upload the PDF (see below).

Uploading a paper PDF

POST /partner/envelopes/:id/upload accepts multipart/form-data with field file. Allowed types: application/pdf, image/png, image/jpeg. Max 50 MB.

curl -X POST "https://api.stg.loyva.net/api/v2/partner/envelopes/env_abc/upload" \
  -H "X-API-Key: lk_..." \
  -F "file=@./signed-contract.pdf"

Response (201 Created):

{
  "data": {
    "path": "org_abc/env_abc/upload_20260427120000.pdf",
    "hash": "<sha256>",
    "size": 184320,
    "content_type": "application/pdf"
  }
}

The PDF lives in ucc-uploads until you trigger vault-in (next section).

Vault-in — moving a document into the UCC vault

There are two vault-in endpoints, picked based on how the document was acquired.

`POST /partner/envelopes/:id/vault-in-signed` — for completed e-sign envelopes

Use when the envelope was signed via DocuSeal. The queue worker normally vaults automatically once the submission.completed webhook fires; this endpoint is a manual trigger / recovery path if the queue missed the message. Idempotent — returns 200 with the existing envelope row if vault_file_path is already set.

The pipeline runs synchronously: download signed PDF → SHA-256 → upload authoritative + non-authoritative copies → generate UCC §9-105 compliance certificate → generate vault custody record PDF → assign custodian → set status to vaulted. The vault.stored webhook fires.

`POST /partner/envelopes/:id/vault-in-upload` — for paper / uploaded PDFs

Use after POST /envelopes/:id/upload. Same pipeline, no DocuSeal step. Requires is_upload: true and a non-null upload_file_path on the envelope.

Both endpoints return the updated envelope row:

{
  "data": {
    "envelope_id": "env_abc",
    "status": "vaulted",
    "...": "..."
  }
}

Vault-out — releasing the authoritative copy

POST /partner/envelopes/:id/vault-out is the end-of-lifecycle action: it releases the authoritative package out of the live vault to a designated recipient (typically a secured party at loan funding).

Irreversible

Vault-out copies the live vault package into an immutable archive prefix (vault-out-archive/{stamp}/) and deletes the live authoritative path as part of UCC single-locus enforcement. Status becomes vaulted_out and live vault pointers are cleared. The archive is preserved for audit but cannot be re-vaulted.

Request body — all fields required, two acknowledgments must be the literal true:

{
  "recipient_name": "First National Bank",
  "recipient_organization": "First National Bank, N.A.",
  "recipient_email": "loans@first-national.example",
  "purpose_of_release": "Loan funded — release to secured party",
  "acknowledge_authoritative_copy": true,
  "acknowledge_chain_of_custody": true,
  "authorized_signature": "Jane Doe, Operations Manager"
}

Response — four short-lived (1 hr) signed URLs into the archive:

{
  "data": {
    "authoritative_signed_url": "https://...",
    "authoritative_filename": "authoritative.pdf",
    "certified_vaulted_copy_signed_url": "https://...",
    "certified_vaulted_copy_filename": "certified-vaulted-copy.pdf",
    "compliance_certificate_signed_url": "https://...",
    "compliance_certificate_filename": "ucc-compliance-certificate.json",
    "vault_custody_record_signed_url": "https://...",
    "vault_custody_record_filename": "vault-custody-record.pdf"
  }
}

The four artifacts:

authoritative_signed_url — the signed PDF that was vaulted (now released).
certified_vaulted_copy_signed_url — human-readable release certificate (PDF) capturing recipient, purpose, chain of custody, and authorized signature.
compliance_certificate_signed_url — UCC §9-105 compliance certificate JSON, captured at vault-in time.
vault_custody_record_signed_url — vault custody record PDF (historical record from vault-in).

URLs expire after 1 hour. Re-call the endpoint to mint fresh URLs.

Voiding an envelope

POST /partner/envelopes/:id/void cancels the envelope. Terminal envelopes (status completed, declined, or already voided) return a 409.

{ "reason": "Customer withdrew before signing" }

The reason field is optional. An envelope.voided webhook event is dispatched to your configured endpoint immediately after the void.

Sending signing reminders

POST /partner/envelopes/:id/remind re-sends the DocuSeal invitation email to pending signers. Only works for envelopes with status sent or viewed.

{ "signer_email": "buyer@example.com" }

Omit signer_email to remind all pending signers at once. Returns the list of reminded addresses and an envelope.reminder_sent webhook event.

{
  "data": {
    "reminded": ["buyer@example.com"],
    "count": 1
  }
}

Managing your webhook

PATCH /partner/webhook lets you update your delivery URL and HMAC signing secret without contacting Loyva. Changes take effect on the next delivery.

{
  "webhook_url": "https://your-app.com/webhooks/loyva",
  "webhook_secret": "a-random-string-at-least-16-chars"
}

Pass null for either field to clear it. The response confirms what changed but never echoes the secret value. See Webhooks for signature verification details.

End-to-end flows

E-sign + auto-vault (typical)

POST /partner/envelopes with template_id → returns sign_url
Customer signs via DocuSeal
vault.stored webhook fires automatically
GET /partner/envelopes/:id/vault/signed-url to download the authoritative PDF
(Optional) POST /partner/envelopes/:id/vault-out at end of lifecycle

E-sign with manual vault recovery

If the queue worker missed the submission.completed event:

... envelope reaches status: "completed" but vaulted: false
POST /partner/envelopes/:id/vault-in-signed → re-runs the pipeline

Paper / pre-signed PDF

POST /partner/envelopes with envelope_kind: "paper" → envelope created with status: "uploaded"
POST /partner/envelopes/:id/upload (multipart) → PDF stored in ucc-uploads
POST /partner/envelopes/:id/vault-in-upload → vaulted, certificate generated
(Optional) POST /partner/envelopes/:id/vault-out at end of lifecycle

Endpoints​

E-sign + envelope lifecycle​

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

Configuration​

How partner endpoints work​

Creating an envelope​

E-sign flow​

Paper / pre-signed PDF flow​

Uploading a paper PDF​

Vault-in — moving a document into the UCC vault​

POST /partner/envelopes/:id/vault-in-signed — for completed e-sign envelopes​

POST /partner/envelopes/:id/vault-in-upload — for paper / uploaded PDFs​

Vault-out — releasing the authoritative copy​

Voiding an envelope​

Sending signing reminders​

Managing your webhook​

End-to-end flows​

E-sign + auto-vault (typical)​

E-sign with manual vault recovery​

Paper / pre-signed PDF​