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": "john@acme.com",
    "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": "john@acme.com",
        "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, register a webhook endpoint and subscribe to the events you care about. Add one in Settings → Developers → Webhooks, or over the API:

curl -X POST https://api.loyva.com/api/v2/webhooks/endpoints \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/loyva",
    "events": ["envelope.completed", "vault.*"]
  }'

The signing secret comes back once — store it immediately.

The event most integrations start with is envelope.completed: it fires when every party has signed, and it carries the values that were filled into the document, so you can write the signed terms straight into your own system.

{
  "event_type": "envelope.completed",
  "event_id": "evt_9f3a2b1c4d5e6f7a8b9c0d1e",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T10:15:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "customer_id": "cust_abc123",
    "completed_at": "2026-04-11T10:15:00.000Z",
    "signers": [
      { "email": "buyer@example.com", "name": "Ada Lovelace", "role": "Buyer" }
    ],
    "fields": [
      { "name": "Monthly Rate", "type": "number", "value": 49.99, "signer_email": "buyer@example.com" },
      { "name": "Start Date", "type": "date", "value": "2026-05-01", "signer_email": "buyer@example.com" }
    ],
    "fields_truncated": false
  }
}

See Signed document field data for the full field contract, and Managing endpoints for event selectors and wildcards.

Verify the X-Loyva-Signature header before acting on any webhook — 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 envelope.completed (with the filled-in field data), then vault.stored and vault.compliance.passed / vault.compliance.failed

Next steps​