Vault Fields API

The Vault Fields API allows you to view custom fields defined for a vault.

Overview

Vault Fields are custom metadata fields that can be attached to packages. Each vault can define its own set of fields to capture business-specific information such as loan numbers, borrower names, or property addresses.

Key concepts: A Field Definition is the schema for a custom field (name, display name, visibility). A Field Value is the actual data stored on a package. The Source Name is the internal field identifier used when importing packages. The Display Name is the human-readable name shown in the UI.

Required scopes

Scope	Description
`vault-fields:read`	View field definitions
`vault-fields`	Full access (same as read)

Note: Creating and modifying vault fields requires Organization Administrator privileges and is not available via Access Keys. Only the list endpoint is accessible via Access Keys.

List Vault Fields

Retrieve all field definitions for a vault.

GET /api/vaults/{vaultId}/fields

Required scope: vault-fields:read. Path parameter vaultId (guid, required). Note: When using an Access Key, the vaultId must match the vault the Access Key is assigned to.

Response (200 OK)

[
  {
    "id": "field-001-guid",
    "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sourceName": "loanNumber",
    "name": "Loan Number",
    "visible": true
  },
  {
    "id": "field-002-guid",
    "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sourceName": "borrowerName",
    "name": "Borrower Name",
    "visible": true
  },
  {
    "id": "field-003-guid",
    "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sourceName": "internalNotes",
    "name": "Internal Notes",
    "visible": false
  }
]

Error responses: 403 — Access key vault mismatch; 404 — Vault not found.

Response models (Vault Fields API)

VaultFieldViewModel

Field	Type	Description
`id`	guid	Unique identifier
`organizationId`	guid	Organization ID
`vaultId`	guid	Vault ID
`sourceName`	string	Internal field name (for API/imports)
`name`	string	Display name (human-readable)
`visible`	boolean	Whether field is visible in reports

Using vault fields

With draft packages

When creating or updating draft packages, use the field's id as the key in the fields object:

{
  "name": "Loan Package",
  "fields": {
    "field-001-guid": "LN-2024-001",
    "field-002-guid": "John Smith"
  }
}

With package field updates

When updating existing package fields, use the fieldId property:

{
  "fields": [
    { "fieldId": "field-001-guid", "value": "LN-2024-002" }
  ]
}

In package search

When searching packages by field values, use the sourceName (for example, loanNumber) rather than the field ID:

{
  "fields": [
    { "name": "loanNumber", "value": "LN-2024" }
  ]
}

Field visibility

The visible property controls whether a field appears in package list views and exports, CSV reports, and search result displays. Hidden fields (visible: false) are still stored on packages, searchable via the API, and visible to Organization Administrators. This allows you to store internal metadata without cluttering user-facing views.