Skip to main content

Customers

Customer endpoints let a partner resolve a Loyva customer_id from an email address, and store general-purpose documents against a customer outside the e-sign/vault lifecycle.

All partner customer endpoints are mounted under /api/v2/partner/* and authenticated with X-API-Key: lk_.... Every successful response is wrapped in { "data": ... }.

Look up a customer by email​

GET /partner/customers

Required scope: customers:read

Query parameters: email (required).

Returns a partner-safe subset of customer fields for the org owning the API key. Internal-only fields (notes, stripe_customer_id, properties, revenue metrics) are never returned.

Response:

{
  "data": {
    "customer_id": "cust_abc123",
    "name": "Jane Buyer",
    "email": "[email protected]",
    "phone": "555-0100",
    "company": "Acme Corp",
    "job_title": "Operations Manager",
    "entity_type": "individual",
    "client_id": null,
    "category": null,
    "industry": null,
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "state": null,
    "postal_code": null,
    "country": null,
    "website_url": null,
    "primary_contact_name": null,
    "created_at": "2026-03-01T09:00:00.000Z",
    "updated_at": "2026-03-01T09:00:00.000Z"
  }
}

If no customer with that email exists for your org, this returns 404:

{ "error": "Customer not found" }

Upload a document to a customer's general folder​

POST /partner/customers/:customer_id/documents

Required scope: envelopes:write

Accepts multipart/form-data with a single file field. Allowed types: application/pdf, image/png, image/jpeg. Max 50 MB.

Use this for documents that aren't part of an e-sign or vaulting flow — e.g. a scanned intake form or an externally-signed contract you just want stored against the customer. They land in the customer's "General Files" view in the Loyva dashboard.

curl -X POST "https://api.stg.loyva.net/api/v2/partner/customers/cust_abc123/documents" \
  -H "X-API-Key: lk_..." \
  -F "file=@./intake-form.pdf"

Response: 201 Created

{
  "data": {
    "customer_id": "cust_abc123",
    "envelope_id": "env_x7k9m2p4q1w3",
    "path": "org_abc/env_x7k9m2p4q1w3/upload_20260427120000.pdf",
    "hash": "<sha256>",
    "size": 184320,
    "contentType": "application/pdf"
  }
}

Internally this creates an envelope record (status: "uploaded", is_upload: true, directory_id: null) to hold the file — it will appear in GET /partner/envelopes like any other envelope — but it is never dispatched through DocuSeal and is not vaulted unless you separately call one of the vault-in endpoints.

If customer_id doesn't belong to your org (or doesn't exist), this returns 404:

{ "error": "Customer not found" }