---
title: "Update a vault column"
method: PATCH
path: "/vaults/{id}/columns/{columnId}"
tags: ["Contract Intelligence"]
---

# Update a vault column

`PATCH /vaults/{id}/columns/{columnId}`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/vaults/:id/columns/:columnId/patch.ts> (a function with typed inputs; its response is checked against the schema)

Change a column's label, instructions, value type, option list, fill mode, or placement. Send only the fields you want to change; everything you leave out keeps its current value. `field_key` is not one of them: it is frozen at creation so the values already extracted stay attached.

Changing the value type of an `ai` column makes the values already extracted for it stale, because they were stored as text read under the old type. GC AI queues a re-scan of the documents that hold one and reports it in `auto_rescan`. The column is saved whatever `auto_rescan` says, so treat that field as news about the re-scan and not as an error. When the vault is waiting on a scan review, the re-scan waits for that approval instead of starting now.

Only a `custom` column accepts changes. A `system` column (Document Name, Document Status, Document Title) returns `400`, and so does a column a connected spreadsheet owns if you try to move it in or out of `import`.

Requires the `editor` or `owner` role in the vault and the organization-level permission to manage vaults.

Requires a user-scoped API key (`u:gcai_...`). A vault is shared with named people, so an organization-scoped key has no identity to resolve vault access with.

## Path parameters

- `id` string, uuid, required: The vault ID
- `columnId` string, uuid, required: The column ID from `GET /vaults/{id}/columns`. Built-in columns report `id: null` and cannot be addressed here.

## Request body

- UpdateVaultColumnRequest
  - `label` string: New column heading. The `field_key` does not follow a rename, so every value already extracted stays attached.
  - `instructions` string: New instructions.
  - `field_type` 'text' | 'date' | 'date_range' | 'enum' | 'multi_enum' | 'boolean' | 'number' | 'currency' | 'percentage' | 'duration' | 'email' | 'url' | 'list' | 'rich_text': New value shape. Send `field_meta` in the same request when the new type needs a different option list.
  - `field_meta` union: New option list. Send `null` to clear it. Omit it to leave the current one in place.
    - object
      - `type` 'enum', required
      - `options` string[], required: The values this column can hold. Between 2 and 12, all different.
    - object
      - `type` 'multi_enum', required
      - `options` string[], required: The values this column can hold. Between 2 and 12, all different. A document can carry more than one.
    - unknown
  - `extraction_mode` 'ai' | 'manual': New fill mode. A column a spreadsheet owns cannot move in or out of `import`, and a column a connected source owns cannot move in or out of `connector`, so those columns reject this field.
  - `sort_order` integer: New placement weight.

## Response `200`

The updated column

- VaultColumnUpdateResponse
  - `id` string, uuid, nullable, required: Unique column identifier, or null for a built-in column. A built-in column has no row of its own in this vault, so it has no ID and cannot be changed or deleted.
  - `field_key` string, required: The stable key extracted values are stored under. It is set once, when the column is created, and never changes, so renaming the column keeps every value already extracted for it.
  - `label` string, required: The column heading shown in the vault table
  - `instructions` string, required: For an `ai` column, the prompt extraction reads each document with. For a `manual`, `import`, or `connector` column, a note to whoever reads the column.
  - `field_type` 'text' | 'date' | 'date_range' | 'enum' | 'multi_enum' | 'boolean' | 'number' | 'currency' | 'percentage' | 'duration' | 'email' | 'url' | 'list' | 'rich_text' | 'party_list' | 'related_agreement_list', required: The shape of the values in this column. Built-in columns can report `party_list` and `related_agreement_list`, which you cannot set yourself.
  - `field_meta` union, required: The option list for an `enum` or `multi_enum` column. Null for every other type.
    - object
      - `type` 'enum', required
      - `options` string[], required: The values extraction can assign to this column.
      - `legacy_options` string[]: Values that documents extracted under an older version of this option list still hold. They stay readable and filterable, and extraction never assigns them again.
    - object
      - `type` 'multi_enum', required
      - `options` string[], required: The values extraction can assign to this column.
    - unknown
  - `extraction_mode` 'ai' | 'manual' | 'import' | 'connector', required: How the column gets filled. `ai`: extraction reads it out of each document. `manual`: a person types it and no scan ever touches it. `import`: values come from a connected spreadsheet, which owns the column. `connector`: values come from a connected document source, which owns the column. You can create `ai` and `manual` columns. An `import` column is created by connecting a spreadsheet in the app. A `connector` column is created when a source such as Ironclad fills it.
  - `kind` 'built_in' | 'system' | 'custom', required: What this column is. `built_in`: merged into every vault by GC AI, with no ID and no way to change it. `system`: owned by this vault but managed by GC AI (Document Name, Document Status, Document Title), so it has an ID but rejects every change and every delete. `custom`: yours, and the only kind `PATCH` and `DELETE` accept.
  - `editable` boolean, required: True when this column can be changed with `PATCH /vaults/{id}/columns/{columnId}`. Built-in and system columns report `false`: GC AI owns their name, type, options, and prompt. One exception, on both surfaces: `sort_order` is list position rather than identity, so it can be set on any column that has an ID.
  - `sort_order` number, nullable, required: Placement weight for this column, or null for a built-in one. The table orders columns by `sort_order` first and creation time second.
  - `created_at` string, nullable, required: ISO 8601 creation timestamp, or null for a built-in column
  - `updated_at` string, nullable, required: ISO 8601 last-update timestamp, or null for a built-in column
  - `auto_rescan` union, required: What happened to the re-scan a type change triggered, or null when the change needed none. A non-null value never means the update failed.
    - object
      - `status` 'queued', required
      - `queued` number, required: Documents committed to the re-scan. Zero means no document held a value for this column, or every one that did was already queued.
      - `total_files` number, required: Documents that hold a value for this column, including any already queued.
    - object
      - `status` 'failed', required: The column was saved and the re-scan could not be queued. Trigger a re-scan from the app when you want fresh values.
    - object
      - `status` 'deferred_to_sample', required
      - `run_id` string, nullable, required: The scan review this vault is waiting on. The re-scan runs when that review is approved.
    - object
      - `status` 'limit_reached', required
      - `used_today` number, required: Re-analysis actions this vault has spent today.
      - `limit` number, required: Re-analysis actions this vault gets per day.
      - `org_blocked` boolean, required: True when re-analysis is turned off for the whole account, so waiting for tomorrow will not help.
    - unknown

## Other responses

- `400`: Invalid request body, an option list that is not 2 to 12 unique values, an `ai` column left with no instructions, a column GC AI manages, or a spreadsheet-owned column whose fill mode cannot change
- `401`: Missing or malformed API key
- `403`: Contract Intelligence is not enabled for this account. Contact support to request access., or the caller cannot manage this vault's columns
- `404`: Vault or column not found, or access denied
- `409`: The vault is archived. Restore it with `POST /vaults/{id}/restore` before changing it.
- `422`: Vault access is per-user and requires a user-scoped API key (u:gcai_...).
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)