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

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
POST	/partner/envelopes	envelopes:write	Create envelope (single or multi-signer)
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
GET	/partner/envelopes/:id/compliance	compliance:read	Compliance check
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	Compliance certificate JSON
PATCH	/partner/webhook	envelopes:write	Update webhook URL / secret
POST	/embed/token	esign:write / vault:read	Mint embed token

How partner endpoints work

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

Creating an envelope

POST /partner/envelopes accepts an optional signers array for multi-signer deals. If omitted, the envelope defaults to a single signer using customer_email / customer_name.

{
  "customer_email": "[email protected]",
  "customer_name": "Jane Buyer",
  "template_id": "tmpl_abc123",
  "signers": [
    { "email": "[email protected]", "name": "Jane Buyer", "role": "Buyer" },
    { "email": "[email protected]", "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.

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": "[email protected]" }

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": ["[email protected]"],
    "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.