API Integration
The Locker API gives you programmatic access to every Locker capability, including several workflows not yet available in the UI. If you need to upload document versions, manage obligations, update metadata, archive documents, or place legal holds today, the API is the way to do it.
This guide is for developers and organization admins integrating Locker into automated workflows, or using features ahead of the UI. It covers workflows and concepts, refer to the Locker API Reference (coming soon) for full endpoint details and request schemas.
Getting Started
Step 1: Get Your API Credentials
API keys are managed at Locker → Settings → API Keys. See Settings for how to generate and manage them.
Step 2: Authenticate Your Requests
Include your API 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.
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 Permissions
All Locker API requests are scoped to your organization. The account making the request needs the appropriate Locker access level for the operation, view access for reads, upload access for writes, and admin access for deletions, archival, and legal holds.
See Permissions for what each access level allows.
Uploading Document Versions
The UI supports uploading new documents but not adding a new version to an existing document record. Version uploads are available via the API today.
When to use this:
- Uploading an amended contract to the same document record, preserving history
- Replacing a draft with a final executed copy
- Updating a policy document without creating a separate record
How it works:
- Identify the document record by its ID (visible in the Locker UI or via the Documents API).
- Make a version upload request with the new file attached to that document ID.
- Locker creates the new version as the current default and retains all prior versions.
The version counter increments automatically. All prior versions remain accessible via the API and will be browsable in the UI once version history is available there.
See Version History for how versioning and retention behavior works.
Updating Metadata
Editing document metadata, name, category, owner, tags, and custom fields, from the document detail panel is not yet available in the UI. Metadata updates are available via the API today.
Common uses:
- Bulk-tagging documents after a large import
- Updating ownership when a team member changes roles
- Setting a renewal date on imported contracts
- Correcting a category applied during upload
Send a PATCH request to the document record with the fields you want to update. Individual fields can be updated without affecting others. Tags use a key: value format. See Metadata for the full list of available fields.
Custom metadata field definitions are also managed via the API. Contact your account team or refer to the API Reference for field definition endpoints.
Managing Obligations
The Obligations dashboard is live and read-only in the UI today. Creating, editing, and completing obligations are available via the API.
Creating an Obligation
To attach a deadline to a document:
- Identify the document ID.
- POST an obligation with a title, due date, owner, and the document ID.
- The obligation appears immediately in the Obligations dashboard at Locker → Obligations.
Required fields:
| Field | Description |
|---|---|
title | Short label for the obligation, e.g., "Send renewal notice" |
dueDate | ISO 8601 date when the obligation is due |
ownerId | User ID of the person responsible |
documentId | The document this obligation belongs to |
Updating an Obligation
Send a PATCH request to the obligation record to change the title, due date, owner, or description. Updates reflect immediately in the dashboard.
Marking an Obligation Complete
Send a completion request to the obligation record. The obligation moves to Completed status and no further reminders are sent.
Obligation notification emails are a planned feature. Until they're available, track upcoming deadlines from the Obligations dashboard at Locker → Obligations.
Screenshot: api-obligation-on-dashboard, the Obligations dashboard showing an obligation created via the API with its title, due date, owner, and Pending status visible
See Tracking Obligations for the full dashboard view.
Archiving and Unarchiving Documents
Archival normally happens automatically via your retention policy. Manual archival and unarchiving are available via the API today.
Manually Archiving a Document
Send an archive request to the document record. The document moves to Archived status, is removed from the default document list and search results, and the event is logged in the Audit Log.
Requires admin access.
Unarchiving a Document
Send an unarchive request to the document record. The document returns to Active status and is immediately available in the document list and search.
Documents under Legal Hold cannot be archived, the API returns an error if you attempt to archive a held document.
Managing Legal Holds
Placing and removing legal holds from the document detail UI is not yet available. Legal hold management is fully available via the Retention API today.
Legal holds are serious compliance operations. Only place or remove holds with proper authorization. All hold actions are permanently and irreversibly logged in the Audit Log.
Placing a Legal Hold
Send a hold request to the document record with a required reason field. The document immediately moves to Legal Hold status, is blocked from archival and deletion, and the hold event is logged with the timestamp, reason, and acting user.
Screenshot: api-legal-hold-result, a document in the Locker document list showing the Legal Hold status badge after a hold was placed via the API
Requires admin access.
Removing a Legal Hold
Send a release request to the hold record. The hold is lifted and the document re-enters its normal lifecycle. If its retention period has already elapsed, Locker processes it at the next scheduled retention run.
See Legal Hold for the full hold lifecycle, GDPR interaction, and the UI alternative at Organization → Retention → Legal Holds.
Webhooks
Subscribe to Locker events via webhooks to build reactive workflows, for example, triggering an obligation creation when an agreement arrives from Propper Sign, or notifying a system when a document is archived.
Locker webhook events cover document uploads, version uploads, status changes (archival, deletion, legal hold placed and released), and obligation state changes.
Configure webhooks at Locker → Settings → Webhooks. See the Webhooks API guide for how to register endpoints and verify payloads.
API Reference
The full Locker API Reference, endpoint paths, request schemas, response shapes, and error codes, is coming soon.
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
Related
- Settings: Manage API keys
- Permissions: Access levels required for each operation
- Version History: How document versioning works
- Obligations: Deadline tracking
- Legal Hold: Freeze documents from archival and deletion
- Retention Policies: Automated document lifecycle
- API Authentication: Platform authentication reference