openapi: 3.2.0
info:
  version: 1.0.1
  title: Document Vault Activities API
  description: "The Document Vault API lets you create a secure, shareable container of documents — a **Document Vault** — and manage its contents programmatically. It lets you exchange the right paperwork with the other side of the transaction without rekeying or trading email attachments.\n\nUsed with **Contract Pack Vault** for conveyancing firms (see [Contract Pack Vault](#section/Contract-Pack-Vault)).\n\n# Overview\n\nUse this API from your case management system to assemble a contract pack, then open **Contract Pack Vault** to check it and share it with the buyer's conveyancer. The API builds and maintains the vault; reviewing and sharing happen in the web app.\n\n1. **Create a Document Vault** — supply the property address and as much detail as you have. You get back a vault `id`; use it in every follow-up call and to open the vault in the web app. Optionally set a `reference` (your case reference), which must be unique within your account.\n2. **Add documents**, one per call. Each file is virus-scanned and analysed in the background. Its `status` is `Pending` while that runs, then `Available` or `Quarantined` if it failed the virus scan.\n3. **Keep details current** — update the reference, property, or recipient organisation, and add or remove recipients. Setting up recipients is not the same as sharing; you share the vault from the web app.\n4. **Check progress** with `Get Document Vault` or `Get Activities` for the audit history.\n5. **Open the web app** to review the analysis and share the vault. See [Contract Pack Vault](#section/Contract-Pack-Vault).\n\n# Getting started\n\nREST API over HTTPS with JSON responses; file uploads use `multipart/form-data`.\n\n**UAT** (building and testing): `https://uat-api.landmarkcloudservices.com/document-vaults`\n\n**Auth:** `https://lmkmaster-uat.eu.auth0.com/oauth/token`\n\n**Production** (live integration only; vaults are real and may incur a cost): `https://api.landmarkcloudservices.com/document-vaults`\n\n**Auth:** `https://lmkmaster.eu.auth0.com/oauth/token`\n\n## Authentication\n\nOAuth 2.0 client credentials. Each conveyancing firm is onboarded individually with Landmark and receives its own client ID, secret, and `Account-Id` (sent as a header on every request). Credentials are issued separately for **UAT** (building and testing; not charged) and **Production** (live integration only). If you integrate via a case management system, that system typically holds the firm's credentials on its behalf.\n\nAudience is fixed per environment:\n\n- UAT: `https://uat-api.landmarkcloudservices.com`\n- Production: `https://api.landmarkcloudservices.com`\n\n**1. Get an access token** by POSTing to the auth endpoint for your environment:\n\n```json\n{\n  \"client_id\": \"your-client-id\",\n  \"client_secret\": \"your-client-secret\",\n  \"audience\": \"https://uat-api.landmarkcloudservices.com\",\n  \"grant_type\": \"client_credentials\"\n}\n```\n\nUse the Production audience when calling the Production auth endpoint.\n\nThe response contains an `access_token` (a JWT) and an `expires_in` value. Cache and reuse the token until it is close to expiry.\n\n**2. Send on every API request:**\n- `Authorization: Bearer <access_token>`\n- `Account-Id: <your account id>`\n\nA `403` means your credentials are not entitled to that operation; contact support.\n\n## Billing\n\nA charge applies per vault when the first document is added to it.\n\n## Limits, errors and support\n\nOne document per upload; up to 60 per vault; PDF, DOC, DOCX, JPEG, PNG; 25 MB per file. API rate limits: up to 1,000 calls per minute per caller.\n\nStandard HTTP status codes apply (`400` validation, `401`/`403` authentication, `404` not found, `409` conflict, `413` too large, `429` rate limited, `5xx` server error). Error bodies use `problem+json`. Include the `lgsTraceResponse` header value when contacting support.\n\n**Support:** support@ochresoft.com | +44 (0)3300 366 700\n\n# Contract Pack Vault\n\n**Contract Pack Vault** is a conveyancing product on LandmarkConnect. You assemble a contract pack from your CMS and share it securely with the buyer's conveyancer. The API handles the building; the web app is where you review the pack and share it.\n\n## AI-assisted checking\n\nAs each document is added, it is automatically analysed so you can spot problems before the pack goes out. The checks include:\n\n- identifying and tagging each document by type,\n- flagging missing pages,\n- checking signatures are present where expected,\n- cross-checking addresses, names, dates and title/reference numbers against the case.\n\nThe results appear as a checklist in the web app for you to review and act on. They are not currently returned by the API.\n\n## Reviewing and sharing\n\nIn the web app you can review the checklist and analysis, preview, download or remove documents, update vault details, and share the vault with the buyer's conveyancer. The buyer's conveyancer receives secure access through a link once they have verified their email address.\n\n## Opening a vault from your CMS\n\nLink straight to a vault from your CMS using the vault `id` from `Create Document Vault`, so your team does not have to search for it in the web app. Open the relevant URL in a browser, replacing `{documentVaultId}`:\n\n- UAT: `https://uat-connect.landmark.co.uk/case/{documentVaultId}`\n- PRD: `https://connect.landmark.co.uk/case/{documentVaultId}`\n\n## API Specification Versions\n- **1.0.1** (16/07/2026)\n  - Added `filename` property to `Add Document` endpoint body to show file name restrictions\n  - Added `minLength` values to various schemas for clarity\n- **1.0.0** (08/07/2026)\n  - Initial release\n"
  contact:
    name: API Support
    email: support@ochresoft.com
    x-phone-number: +44 (0)3300 366 700
servers:
- url: https://api.landmarkcloudservices.com/
  description: Production API
- url: https://uat-api.landmarkcloudservices.com/
  description: UAT API
security:
- bearerAuth: []
tags:
- name: Activities
  description: Read a vault's audit history.
paths:
  /{documentVaultId}/activities:
    get:
      tags:
      - Activities
      summary: Get Activities
      description: Returns all audit events for a vault, the same history shown in the web app activity log.
      operationId: document-vault-activities-list
      x-external-entitlement: external:document-vault:activities:list
      parameters:
      - name: Account-Id
        in: header
        required: true
        schema:
          $ref: '#/components/schemas/accountId'
      - name: documentVaultId
        in: path
        description: The Document Vault ID
        required: true
        schema:
          $ref: '#/components/schemas/lgsUuid'
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getActivitiesResponse'
              examples:
                Document Vault Created:
                  value:
                    activities:
                    - action: Case created
                      createdBy: John Michael Smith
                      createdDate: '2026-06-17T12:10:14.222813Z'
                Reference Updated:
                  value:
                    activities:
                    - action: Reference updated
                      detail: Reference updated to NEW/REF
                      createdBy: John Michael Smith
                      createdDate: '2026-06-17T12:10:14.222813Z'
                Document Added:
                  value:
                    activities:
                    - action: Document added
                      detail: test-document.pdf (40.06 KB)
                      createdBy: John Michael Smith
                      createdDate: '2026-06-17T12:10:14.222813Z'
                      metadata:
                        documentId: 52ece8cc-ec3a-4e78-907b-ba7d7f977ea8
                Document Deleted:
                  value:
                    activities:
                    - action: Document deleted
                      detail: test-document.pdf (40.06 KB)
                      createdBy: John Michael Smith
                      createdDate: '2026-06-17T14:03:59.999076Z'
                      metadata:
                        documentId: 52ece8cc-ec3a-4e78-907b-ba7d7f977ea8
                Property Details - All Fields Updated:
                  value:
                    activities:
                    - action: Property updated
                      createdBy: Jane Elizabeth Smith
                      createdDate: '2026-06-17T14:07:00.716564Z'
                      metadata:
                        previousAddress: 21 Test Street, Reading, RG2 0TD
                        updatedAddress: 22 Test Street, Reading, Berkshire, RG2 0TD
                        previousRegistered: false
                        updatedRegistered: true
                        previousSellingCapacity: Trustee
                        updatedSellingCapacity: LegalAndBeneficialOwner
                        previousTenure: Leasehold
                        updatedTenure: Freehold
                Property Details - Single Field Updated:
                  value:
                    activities:
                    - action: Property updated
                      createdBy: Jane Elizabeth Smith
                      createdDate: '2026-06-17T14:07:00.716564Z'
                      metadata:
                        previousSellingCapacity: Attorney
                        updatedSellingCapacity: PersonalRepresentative
                Property Details - Field Updated From No Previous Data:
                  value:
                    activities:
                    - action: Property updated
                      createdBy: Jane Elizabeth Smith
                      createdDate: '2026-06-17T14:07:00.716564Z'
                      metadata:
                        updatedTenure: Commonhold
                Recipient Organisation Details - All Fields Updated:
                  value:
                    activities:
                    - action: Recipient Organisation updated
                      createdBy: Jane Elizabeth Smith
                      createdDate: '2026-06-17T14:07:00.716564Z'
                      metadata:
                        previousName: Test Organisation 123 Ltd
                        updatedName: Test Organisation 456 Ltd
                        previousReference: OLD/REF
                        updatedReference: NEW/REF
                Recipient Organisation Details - Single Field Updated:
                  value:
                    activities:
                    - action: Recipient Organisation updated
                      createdBy: Jane Elizabeth Smith
                      createdDate: '2026-06-17T14:07:00.716564Z'
                      metadata:
                        previousReference: Some-Ref
                        updatedReference: SOME-REF
                Recipient Organisation Details - Field Updated From No Previous Data:
                  value:
                    activities:
                    - action: Recipient Organisation updated
                      createdBy: Jane Elizabeth Smith
                      createdDate: '2026-06-17T14:07:00.716564Z'
                      metadata:
                        updatedName: Example Organisation Name
          headers:
            lgsTraceResponse:
              $ref: '#/components/headers/lgsTraceResponse'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
components:
  responses:
    400BadRequest:
      description: Bad Request
      headers:
        traceresponse:
          $ref: '#/components/headers/lgsTraceResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/lgsErrorResponse'
          examples:
            Invalid content type supplied:
              value:
                status: '400'
                code: '40000'
                title: Invalid content type supplied
            Validation error:
              value:
                status: '400'
                code: '40001'
                title: Validation error
            Invalid traceparent http header:
              value:
                status: '400'
                code: '40002'
                title: Invalid trace header
            No matching data found:
              value:
                status: '400'
                code: '40003'
                title: No matching data found
            Invalid header:
              value:
                status: '400'
                code: '40004'
                title: Invalid header
            Third party error:
              value:
                status: '400'
                code: '40005'
                title: Third party error
    500InternalServerError:
      description: Internal Server Error
      headers:
        traceresponse:
          $ref: '#/components/headers/lgsTraceResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/lgsErrorResponse'
          examples:
            Resource not found:
              value:
                status: '500'
                code: '50000'
                title: Internal server error
                messages:
                - message: Sorry, something has gone wrong whilst processing your request. An error has been logged and our support team will investigate this shortly. Please try again later and if the issue persists, please contact your Account Manager referencing the value 00-199c8ce55dc743a88661498aa8eb2cfc--00.
    404NotFound:
      description: Not Found
      headers:
        traceresponse:
          $ref: '#/components/headers/lgsTraceResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/lgsErrorResponse'
          examples:
            Entity not found:
              value:
                status: '404'
                code: '40400'
                title: Entity not found
    401Unauthorized:
      description: Unauthorized
      headers:
        traceresponse:
          $ref: '#/components/headers/lgsTraceResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/lgsErrorResponse'
          examples:
            Invalid identity:
              value:
                status: '401'
                code: '40100'
                title: Invalid identity
    429TooManyRequests:
      description: Too Many Requests
      headers:
        traceresponse:
          $ref: '#/components/headers/lgsTraceResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/lgsErrorResponse'
          examples:
            Rate Limit Exceeded:
              value:
                status: '429'
                code: '42900'
                title: Rate limit exceeded
    403Forbidden:
      description: Forbidden
      headers:
        traceresponse:
          $ref: '#/components/headers/lgsTraceResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/lgsErrorResponse'
          examples:
            Invalid Entitlement:
              value:
                status: '403'
                code: '40300'
                title: Invalid Entitlement
            No Entitlement:
              value:
                status: '403'
                code: '40301'
                title: No Entitlement
            No permission to entity:
              value:
                status: '403'
                code: '40302'
                title: No permission to entity
            User not registered:
              value:
                status: '403'
                code: '40303'
                title: User not registered
            Usage limit reached:
              value:
                status: '403'
                code: '40304'
                title: Usage limit reached
            Email account not verified:
              value:
                status: '403'
                code: '40305'
                title: Email account not verified
            Token expiry too long:
              value:
                status: '403'
                code: '40306'
                title: Token expiry too long
  schemas:
    activity:
      type: object
      required:
      - action
      - createdBy
      - createdDate
      additionalProperties: false
      properties:
        action:
          type: string
          description: The context of the activity
        detail:
          type: string
          description: The activity message
        createdBy:
          type: string
          description: The full name of the person who created the activity
        createdDate:
          type: string
          format: date-time
          maxLength: 38
        metadata:
          type: object
          description: Additional metadata for the activity
          additionalProperties: true
    accountId:
      description: Your Landmark account ID - this will be provided to you during onboarding
      allOf:
      - $ref: '#/components/schemas/lgsUuid'
    getActivitiesResponse:
      description: The activities relating to the associated document vault
      type: object
      required:
      - activities
      additionalProperties: false
      properties:
        activities:
          type: array
          items:
            $ref: '#/components/schemas/activity'
    lgsUuid:
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[4][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$
    lgsErrorResponse:
      type: object
      additionalProperties: false
      required:
      - status
      - code
      - title
      properties:
        status:
          type: string
          minLength: 3
          maxLength: 3
          pattern: ^[0-9]{3}$
        code:
          type: string
          minLength: 5
          maxLength: 5
          pattern: ^[0-9]{5}$
        title:
          type: string
          minLength: 1
          maxLength: 100
        messages:
          type: array
          maxItems: 100
          items:
            type: object
            additionalProperties: false
            required:
            - message
            properties:
              property:
                type: string
                minLength: 1
                maxLength: 1000
              message:
                type: string
                minLength: 1
                maxLength: 1000
  headers:
    lgsTraceResponse:
      description: Trace context providing an unique identifier for an individual requests
      schema:
        type: string
        minLength: 39
        maxLength: 39
        pattern: ^[0-9a-fA-F]{2}-[0-9a-fA-F]{32}--[0-9a-fA-F]{2}$
      examples:
        Example traceresponse:
          value: 00-199c8ce55dc743a88661498aa8eb2cfc--00
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-tagGroups:
- name: Document Vault API
  tags:
  - Document Vaults
  - Documents
  - Activities