Packages API

The Packages API allows you to retrieve and manage document packages stored in your vault.

Overview

A Package in Concord eVault represents a collection of related documents stored as a single unit. Packages are the primary way documents are organized and managed within a vault.

Key concepts: A Package is a container for one or more related files. A Package File is an individual document within a package. Folders can organize packages for better structure. Metadata (custom fields) can be attached to packages. A Package Type is one of AuthoritativeCopy, Receipt, or Upload. A Merge means two packages can be combined into one, consolidating their files and attachments.

List Recent Packages

Retrieve a paginated list of the most recently imported packages.

GET /api/packages/recent

Required scope: packages:read.

Query parameters

Response (200 OK)

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
      "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Loan Document Package",
      "packageType": "AuthoritativeCopy",
      "source": "Api",
      "numberOfFiles": 3,
      "totalFileSize": 1245678,
      "vaultFolder": {
        "id": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "2024 Q1 Loans"
      },
      "fields": [
        { "id": "field-001-guid", "name": "loanNumber", "value": "LN-2024-001" },
        { "id": "field-002-guid", "name": "borrowerName", "value": "John Smith" }
      ],
      "importedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "metadata": { "page": 1, "pageSize": 10, "totalCount": 1 }
}

Search Packages

Search packages by name, type, source, date range, and custom field values.

POST /api/packages/search

Required scope: packages:read.

Request body

Response (200 OK): Returns a paginated list of PackageViewModel objects matching the criteria.

Get Package

Retrieve details for a specific package.

GET /api/packages/{id}

Required scope: packages:read.

Path parameters: id (guid, required) — Package ID.

Response (200 OK)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
  "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Loan Document Package",
  "packageType": "AuthoritativeCopy",
  "source": "Api",
  "numberOfFiles": 3,
  "totalFileSize": 1245678,
  "vaultFolder": {
    "id": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "2024 Q1 Loans"
  },
  "fields": [
    { "id": "field-001-guid", "name": "loanNumber", "value": "LN-2024-001" },
    { "id": "field-002-guid", "name": "borrowerName", "value": "John Smith" }
  ],
  "importedAt": "2024-01-15T10:30:00Z"
}

Error responses: 404 — Package not found in current vault.

List Folder Packages

List all packages within a specific folder.

GET /api/vault/folders/{vaultFolderId}/packages

Required scope: packages:read.

Path parameters: vaultFolderId (guid, required) — Folder ID.

Query parameters: page (integer, default 1) — page number; pageSize (integer, default 50, max 100) — items per page.

List Package Files

Retrieve all files within a package.

GET /api/packages/{vaultPackageId}/files

Required scope: packages:read.

Path parameters: vaultPackageId (guid, required) — Package ID.

Query parameters: page (integer, default 1), pageSize (integer, default 10, max 100).

Response (200 OK)

{
  "data": [
    {
      "id": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
      "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
      "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
      "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "fileName": "promissory_note.pdf",
      "fileType": "application/pdf",
      "fileSize": 245678
    }
  ],
  "metadata": { "page": 1, "pageSize": 10, "totalCount": 1 }
}

Download Package File

Download a specific file from a package. Files are returned with an appropriate watermark based on the package type.

GET /api/packages/{vaultPackageId}/files/{id}

Required scope: packages:read.

Path parameters: vaultPackageId (guid, required) — Package ID; id (guid, required) — File ID.

Response: Returns the file content as a PDF with appropriate Content-Type and Content-Disposition headers. A watermark is applied based on package type (AuthoritativeCopy, Receipt, UploadReceipt, or Upload). Note: File downloads are logged in the activity trail.

List Package Events

Retrieve the activity event history for a package.

GET /api/packages/{vaultPackageId}/events

Required scope: packages:read.

Path parameters: vaultPackageId (guid, required).

Query parameters: page (integer, default 1), pageSize (integer, default 25, max 100).

Response (200 OK)

{
  "data": [
    {
      "id": "9fa85f64-5717-4562-b3fc-2c963f66afa6",
      "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
      "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
      "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "eventType": "PackageImported",
      "metadata": {},
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "metadata": { "page": 1, "pageSize": 25, "totalCount": 1 }
}

Event types

Error responses: 404 — Package not found (includes packages that have been merged or rescinded).

Update Package Fields

Update custom field values for a package.

PATCH /api/packages/{id}/fields

Required scope: packages:write.

Path parameters: id (guid, required) — Package ID.

Request body

Each field update contains fieldId (guid) — the vault field ID — and value (string) — the new value (an empty string removes the field).

Response (200 OK): Returns the updated PackageViewModel with all fields.

Error responses: 400 — cannot update Receipt-type packages; 404 — package not found.

Merge Packages

Merge one package (the source) into another (the target). All files and attachments from the source are copied onto the target, and the source is marked as Merged. Once merged, the source package is hidden from all list, search, and folder endpoints, while a durable link back to the target is retained for audit purposes.

POST /api/packages/{id}/merge

Required scope: packages:write.

Path parameters: id (guid, required) — the source package to merge away.

Request body

{
  "mergeIntoVaultPackageId": "550e8400-e29b-41d4-a716-446655440001"
}

Allowed package type combinations

Response (202 Accepted): The response includes a Location header pointing to the target package (/api/packages/{mergeIntoVaultPackageId}).

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mergedIntoVaultPackageId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "Merged",
  "filesCopied": 2,
  "attachmentsCopied": 1
}

Error responses

A 400 is returned when any of the following apply: mergeIntoVaultPackageId is missing; the source and target are the same package; either package is not Active; a Receipt package is involved (as source or target); an AuthoritativeCopy package is being merged into an Upload package; either package has already been merged; or the source package has existing transfers.

Note: The merge is recorded as a PackageMergedInto event in the target package's activity trail, retrievable via GET /api/packages/{id}/events. The source package is no longer accessible after the merge — requesting its events returns 404 — so its PackageMerged event cannot be retrieved through the API.

Add Packages to Folder

Move multiple packages to a specific folder.

POST /api/vault/folders/{vaultFolderId}/packages

Required scope: packages:write.

Path parameters: vaultFolderId (guid, required) — Target folder ID.

Request body

Response (204 No Content): Packages already in the target folder are skipped. Activity is logged for each package moved.

Export Packages Report

Generate a CSV report of packages matching the specified criteria.

POST /api/packages/report

Required scope: packages:read.

Request body: Same filter parameters as the Search Packages endpoint.

Response: Returns a CSV file with package data including all visible vault fields as columns.

Response models (Packages API)

PackageViewModel

PackageFieldViewModel

MergePackageResponse

PackageFileViewModel

PackageEventViewModel

Next: Draft Packages API.