Skip to main content

Quickstart

This guide walks you through creating an envelope, getting signer links, and checking its status — all from the command line.

Prerequisites: You need a Loyva partner API key. See API Keys for provisioning.

1. Create an envelope​

Partners create envelopes by passing the customer's email and name. Loyva provisions the customer on the fly if needed. If your envelope must satisfy UCC §9-105 compliance, populate secured_party now so Check 8 passes automatically.

curl -X POST https://api.stg.loyva.net/api/v2/partner/envelopes \
  -H "X-API-Key: lk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope_name": "Q1 Sales Agreement",
    "customer_email": "[email protected]",
    "customer_name": "John Smith",
    "template_id": "tmpl_lease_v2",
    "secured_party": {
      "name": "First National Bank",
      "role": "secured_party",
      "address": "123 Main St, NY"
    }
  }'

Response:

{
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "envelope_name": "Q1 Sales Agreement",
    "status": "sent",
    "customer_id": "cust_abc123",
    "created_at": "2026-04-11T10:00:00.000Z"
  }
}

A template_id is required when you want Loyva to dispatch the envelope for signing via the partner API. Envelopes created without a template remain in pending status until a document is attached by a Loyva operator.

Pull the short-lived signing URL for each recipient:

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

Response:

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

You can email these URLs to signers directly.

info

A drop-in Embed SDK that renders the signing widget inside your own app is in progress. The POST /embed/token endpoint already mints the short-lived JWT, but the matching JavaScript SDK and iframe host are not yet published — contact your Loyva point of contact if you need embedded signing now.

3. Check envelope status​

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

Response:

{
  "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"
  }
}

4. Listen for webhooks​

Instead of polling, configure a webhook to get notified in real-time. The event_type field identifies the event; check which events are actually dispatched in the events reference.

{
  "event_type": "vault.stored",
  "event_id": "evt_9f3a2b1c4d5e6f7a8b9c0d1e",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T10:15:00.000Z",
  "data": {
    "path": "ucc-vault/org_abc123/env_x7k9m2p4q1w3/signed.pdf",
    "hash": "a1b2c3d4e5f6..."
  }
}

Verify the X-Loyva-Signature header before acting on webhook events — see Verification.

What happens next​

After signing completes, Loyva automatically:

  1. Fetches the signed PDF from the signing provider
  2. Computes a SHA-256 hash of the watermarked authoritative bytes
  3. Stores the authoritative copy in the vault and a non-authoritative copy in the backup bucket
  4. Generates a UCC §9-105 compliance certificate (all 8 checks) and transitions the envelope to vaulted
  5. Auto-assigns the initial custodian (satisfies Check 3)
  6. Fires vault.stored and vault.compliance.passed / vault.compliance.failed webhook events

Next steps​