Skip to main content

API Integration

The Locker API gives you programmatic access to the core Locker workflows. Use it to upload documents, list and read records, download files, run AI chat and search, and extract obligations from contracts.

Who this guide is for

This guide is for developers and organization admins integrating Locker into automated workflows. It covers concepts and surfaces. Refer to the Locker API Reference for full endpoint paths, request schemas, response shapes, and error codes.

Getting Started​

Step 1: Get Your API Credentials​

API access uses OAuth 2.0. See Settings for how to provision client credentials and the API Authentication guide for the OAuth flow and scope details.

Step 2: Authenticate Your Requests​

Include your access token as a Bearer token in the Authorization header of every request. For detailed authentication flows, token expiry, and refresh patterns, see the API Authentication guide.

caution

Never expose API credentials in client-side code or commit them to version control. All Locker API calls must be made from a secure server-side environment.

Step 3: Confirm Your Plan and Permissions​

All Locker API requests are scoped to the organization that owns the access token. Beyond OAuth scopes (locker:read, locker:write, locker:admin), some endpoints additionally require that your plan includes the corresponding feature:

  • Document upload — your plan must include Locker upload
  • AI search, AI chat, and obligation extraction — your plan must include Locker AI

If a request is denied with HTTP 403, check both the OAuth scope and that your plan includes the required Locker feature. If you're unsure, contact your account team.

See Permissions for what each access level allows.

Uploading Documents​

The Locker API accepts uploaded documents for storage and, when AI is included in your plan, for AI indexing. Refer to the Locker API Reference for the supported request shapes (multipart and base64 JSON) and example payloads.

In all cases, the file is stored under your organization's tenant boundary, a Locker document record is created, and (if AI features are part of your plan) the document is queued for AI indexing.

Upload accepts PDF, DOCX, XLSX, DOC, XLS, and TXT, up to 50 MB per file. PDF, DOCX, and TXT are AI-indexed; XLSX, XLS, and DOC are stored but skip AI indexing. OCR for scanned image-only PDFs is not supported today.

Editing Document Metadata​

You can update a document's metadata after upload:

  • Name, description, tags, and document type — any combination of these fields, all optional
  • Folder assignment — move a document into a folder, or pass null to remove it from its current folder

Editing requires locker:write.

Deleting Documents​

The API supports two deletion modes:

  • Soft delete (default) — archives the document by setting an archivedAt timestamp. The record and file remain in storage. Requires locker:write.
  • Purge (?purge=true) — permanently removes the document record, all related data (obligations, shares, versions, AI index entries), and the stored file. Requires locker:admin.

Soft-deleting an already-archived document is idempotent (returns success without error).

Listing, Reading, and Downloading Documents​

  • List — return the documents your account is allowed to see in the org, with metadata, indexing status, and tags
  • Read — fetch a single document's metadata by ID
  • Download — stream the file bytes for a document you have read access to (the access event is recorded for audit)

All read operations are gated by locker:read.

  • AI Chat — streaming or single-shot chat over your indexed documents, with citations
  • AI Search — keyword-style search that uses the same vector index for semantic matches

Both surfaces are scoped to your organization's documents. Both require AI to be part of your Locker plan. Per-query token usage and a best-effort cost estimate are available on the response so you can monitor consumption.

Extracting Obligations​

The Locker API exposes an obligation-extraction endpoint that runs over a single indexed document and returns structured obligation records. The endpoint requires:

  • AI to be part of your Locker plan
  • The OAuth scope appropriate for AI queries
  • The document to belong to your organization
  • The document to have completed AI indexing (extractions on documents that are still pending or have failed indexing return HTTP 409)

You can choose between a read-only mode (returns the extracted obligations without persisting them) and a commit mode (additionally saves the extracted obligations as records linked to the document so they appear in the Obligations dashboard). Refer to the Locker API Reference for the exact request shape.

What Is Not Yet Exposed via API​

The following workflows are not currently available as Locker API endpoints. They are tracked as roadmap items:

  • Document version upload, listing, and restore — see Version Control for what's available today and the planned model
  • Per-document share links — see Access & Sharing for current sharing options
  • Restore from archive — soft-deleted documents cannot yet be restored via API
  • Folder hierarchy as a product surface — Locker is tag- and metadata-based; see Organizing Documents
  • Audit-log export specific to Locker — document view and download events are recorded today; a customer-facing export endpoint is planned
  • Native legal hold for Locker documents — see Legal Hold for what's enforced today
  • Manual obligation create, update, and complete via API — only AI-driven extraction is currently exposed; the Obligations dashboard is read-only today

If any of these workflows is a hard requirement for your integration, contact your account team so the priority is recorded.

Webhooks​

Locker propagates inbound events from Sign and DocuSign automatically — completed Sign agreements and DocuSign envelopes land in Locker with their audit trail. Outbound Locker-event webhooks (such as "document indexed") are not currently a public surface.

API Reference​

The full Locker API reference, including endpoint paths, request schemas, response shapes, and error codes, is published alongside the rest of the Propper API documentation at docs.propper.ai. The base URL for production is https://api.propper.ai.

In the meantime:

  • Use this guide for workflow context and field descriptions
  • Authenticate using the API Authentication guide
  • Contact your account team or check the developer portal for early API reference access