Tracking requests

There is no webhook/callback yet — poll the request endpoints for results.

Webhooks are coming

The webhooks:write scope is reserved but no delivery exists yet. Until then, poll. See API reference → Not yet available.

List requests

GET /partner/v1/requests

Scope: requests:read · Query params: status?, reference?, limit? (1–100, default 50).

curl "https://locke-api.trylockey.workers.dev/partner/v1/requests?reference=candidate-4821" \
  -H "Authorization: Bearer $LOCKEY_API_KEY"

Fetch one request

GET /partner/v1/requests/:id

Scope: requests:read. Returns one request (or 404 { "error": "not_found" }):

{
  "requestId": "…",
  "status": "partially_fulfilled",
  "purpose": "employment_verification",
  "customPurpose": null,
  "reference": "candidate-4821",
  "items": [
    { "id": "…", "classification": "passport", "label": "Passport", "required": true, "highSensitivity": false, "status": "fulfilled" },
    { "id": "…", "classification": "employment_letter", "label": "Prior employment", "required": false, "highSensitivity": false, "status": "pending" }
  ],
  "createdAt": 1767139200000,
  "expiresAt": 1767225600000
}

The response carries nothing about the subject beyond what you submitted — no account existence, no user id, no delivery state.

Statuses

Request statuses: pending, approved, partially_fulfilled, denied, expired, revoked, completed. (expired is derived from expiresAt at read time.)

Item statuses: pending, fulfilled, denied.

Recommended polling

Back off from ~30s up to a few minutes. Stop when the request reaches a terminal state (completed, denied, revoked, expired) or all required items are fulfilled.

poll interval:  30s → 60s → 120s → 300s (cap)
stop when:      terminal status  OR  all required items fulfilled

Once an item is fulfilled, it becomes a grant you can read — see Reading grants.

Next: Reading grants →