How integration works

The Partner API is built around one primitive: you request documents from a subject, and read the approved result as a grant. Everything else — auth, polling, viewing sessions — supports that flow.

The model in one line

You request documents from a subject → the subject approves in the Lockey app → you read the result as a grant (a hosted, watermarked, view-only session). Recipients never download originals, and neither do you.

Key concepts

Term	Meaning
Org (partner)	Your company's account in Lockey. Starts pending, becomes active after KYB verification.
API key	Bearer credential for the machine API. Scoped, environment-bound (sandbox / live), shown once at creation.
Document Request	You ask a subject for one or more documents, for a stated purpose.
Subject	The person you're requesting from, identified by exactly one of email or phone.
Grant	A document the subject approved for you — read via a watermarked, view-only session.
Scope	A capability on a key (requests:write, requests:read, grants:read, …).

The end-to-end flow

  Your system                 Lockey                     Subject (person)
  ───────────                 ─────                     ────────────────
      │  POST /requests          │                            │
      │ ───────────────────────► │   notifies subject         │
      │  201 { requestId }       │ ─────────────────────────► │
      │                          │                            │  approves &
      │  GET /requests/:id        │                            │  fulfills items
      │  (poll)                  │ ◄───────────────────────── │
      │ ───────────────────────► │                            │
      │  status: fulfilled       │                            │
      │                          │                            │
      │  GET /grants/:id          │                            │
      │  POST /grants/:id/sessions│                            │
      │ ───────────────────────► │  renders watermarked pages │
      │  watermarked page images │                            │
      │ ◄─────────────────────── │                            │

1. Create a request. You call POST /partner/v1/requests with a subject (one email or phone), a purpose, and the list of documents you want.
2. The subject approves. Lockey notifies them; they review the ask in the Lockey app and approve (or deny) each item. You are never told whether the contact was already a Lockey user — see the privacy note below.
3. Poll for results. There are no webhooks yet, so you poll GET /partner/v1/requests/:id until items become fulfilled.
4. Read the grant. Each fulfilled item becomes a grant. Open the hosted viewerUrl, or mint a fresh watermarked session with POST /partner/v1/grants/:id/sessions and render the page images yourself.

The privacy guarantee (no existence oracle)

POST /requests returns the same response, timing, and side effects whether or not the contact already has a Lockey account. Lockey stores only a hash of the subject's contact; delivery and audit happen after the response is returned.

You cannot use the API to test whether someone has a Lockey account. This is deliberate and worth designing around: don't build flows that assume you can detect account existence.

What you never touch

• The original file — you only ever get watermarked page images, rendered and stamped server-side.
• A download — there is no download path, for recipients or partners.
• The subject's account state — responses never disclose whether the subject is a user, their billing, or delivery status.

Environments

You build against sandbox first (key prefix lk_test_), which never contacts a real person or touches real accounts, then switch to live (lk_live_) once your org is verified. Same base URL for both — the key prefix alone selects the behavior. See Getting started.

Next: Getting started →