Integration APIs

Kwik Vault exposes a REST API with OpenAPI 3.0 documentation. Integrators authenticate with service user tokens (see API Keys) and call endpoints for ingest, search, approvals, and audit export.

Interactive docs: https://<vault-host>/docs (machine-readable schema at /openapi.json).

Overview

All integrators use the same Ingest Payload contract. Source systems (VKYC, Document Service, branch scans) push documents with explicit category and department for deterministic classification.

Integrators connect through the API gateway (Core Platform API) at https://<vault-host>/api/v1/*. The gateway terminates TLS, validates bearer tokens, and routes to ingest, search, and download services. See Operations Guide for gateway setup and Security and Compliance for TLS requirements.

Push and Pull Operations

Performance targets

API replicas scale horizontally for high pull volume. Use paginated search to list document IDs, then parallelize downloads. Cold-tier blobs may have longer retrieval times per Storage and Lifecycle.

Ingest Contract

{
  "source_tag": "vkyc",
  "external_id": "session-123",
  "document_category": "kyc_vkyc",
  "department": "retail",
  "customer_refs": {
    "cif": "12345678",
    "pan": "ABCDE1234F",
    "account_number": "9876543210"
  },
  "custom_attributes": {},
  "file": "<binary>"
}

Same Business Key (source_tag + external_id) creates a new Version on the existing Document without overwriting prior versions. Otherwise a new Document with a new DMS ID is created. See Architecture for the version state machine.

Ingest API

POST /api/v1/ingest
Content-Type: multipart/form-data
Authorization: Bearer <access_token>

curl -X POST 'https://vault.example.com/api/v1/ingest' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Approver-Department: retail' \
  -F 'file=@./document.pdf' \
  -F 'metadata={"source_tag":"vkyc","external_id":"session-123","document_category":"kyc_vkyc","department":"retail","customer_refs":{"cif":"12345678"}}'

Response

{
  "document_id": "439031ac-e5c3-4ad6-8f1e-69c4b0f8a11b",
  "version_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "business_key": "vkyc:session-123",
  "version_number": 1,
  "approval_state": "pending",
  "file_name": "document.pdf"
}

Search APIs

Customer search (Tier 1)

GET /api/v1/search/customer?cif=12345678
GET /api/v1/search/customer?pan=ABCDE1234F
GET /api/v1/search/customer?account_number=9876543210

At least one of CIF, PAN, or account number is required.

Document listing

GET /api/v1/search/documents

Query parameters support DMS ID, file name, category, date range, and department filters.

Approval APIs

GET /api/v1/approvals/pending
POST /api/v1/approvals/{version_id}/approve
POST /api/v1/approvals/{version_id}/reject

Approvers must belong to the document's department.

Document APIs

GET /api/v1/documents/{document_id}
GET /api/v1/documents/{document_id}/download
DELETE /api/v1/documents/{document_id}
DELETE /api/v1/documents/{document_id}/permanent

Audit API

GET /api/v1/audit/export

Export audit entries as CSV for the authenticated scope and date range.

Configuration API

GET /api/v1/config
PUT /api/v1/config

Read and update tenant configuration (super admin).

Identity APIs

GET /api/v1/identity/status
POST /api/v1/identity/users
POST /api/v1/identity/service-users
POST /api/v1/identity/access-token

Infrastructure APIs

GET /api/v1/infra/status
POST /api/v1/infra/calculate

Health Checks

GET /health
GET /ready

Authentication

Integrators authenticate with a bearer token minted on the API Keys page:

Authorization: Bearer <access_token>

Getting Started

1. Review Documentation: Understand the ingest contract and approval workflow.
2. API Integration: Create a service user and mint an access token on API Keys.
3. Data Preparation: Format metadata according to tenant Configuration schema.
4. Testing: Validate ingest, search, and approval in the test environment.
5. Production: Go live with full audit and approval automation.

Benefits

• Self-service integration: OpenAPI docs and cURL examples on the Upload page.
• Uniform contract: VKYC, Document Service, and branch scans use the same payload.
• Version safety: Re-ingest creates versions without duplicate DMS IDs.
• Low-latency pull: Sub-second search and hot-tier download for production integrations.
• Gateway simplicity: Single HTTPS host for all push and pull operations.

Next Steps

• Operations Guide: CR process and department onboarding
• Upload: manual ingest and cURL panel
• API Keys: service user and token management
• Approvals: approval workflow after ingest
• Architecture: platform module design