--- title: "Set a cell value by hand" method: PATCH path: "/vaults/{id}/documents/{documentId}/cells/{fieldKey}" tags: ["Contract Intelligence"] --- # Set a cell value by hand `PATCH /vaults/{id}/documents/{documentId}/cells/{fieldKey}` ## Request - Base URL: `https://app.gc.ai/api/external/v1` - URL: `https://app.gc.ai/api/external/v1/vaults/{id}/documents/{documentId}/cells/{fieldKey}` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Overwrite one extracted value in a vault with a value of your own. The cell keeps showing your value, and hides the citations and reasoning behind the extracted one, until you put it back with `POST /vaults/{id}/documents/{documentId}/cells/{fieldKey}/revert`. `value` is always a string, whatever the column holds. Text, enum, email, URL, number, and percentage columns take the value as written. A checkbox column takes `true` or `false`. A date column takes `YYYY-MM-DD`. Multi-select and list columns take a JSON array of strings, for example `["Delaware","New York"]`. Currency, duration, date-range, party, and related-agreement columns take the same JSON the read path returns for that column, so the safest way to build one is to read the cell first and edit what comes back. An enum or multi-select value outside the column's configured options returns `400`, and so does any column GC AI writes itself: the folder columns synced from a connected drive, and a Document Name column the vault manages through its naming template. Editing a cell while its document is still being scanned is allowed. Your value wins: an extraction that lands afterwards does not overwrite it, so there is no need to poll for the scan to finish first. A document that belongs to another vault returns `404`, even when the caller can reach both vaults, and so does a column key this vault does not have. Read the keys from `GET /vaults/{id}/columns`. Requires the `editor` or `owner` role in the vault and the organization-level permission to manage vaults. An archived vault returns `409`: restore it first. A document that was deleted, or auto-removed as a duplicate copy, also returns `409`, and so does a document stored before GC AI split bundled uploads, which has no cells of its own to write. 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 - `documentId` string, uuid, required: The `document_id` of a row from `GET /vaults/{id}/documents`. - `fieldKey` string, required: Column key, as the vault reports it for its columns. A key, not a label: `governingLaw`, not `Governing law`. Percent-encode it if it holds a character a URL path reserves. ## Request body - VaultDocumentCellUpdateRequest - `value` string, required: The value to store. Send an empty string to clear the cell. ## Response `200` The stored cell - VaultDocumentCellResponse - `document_id` string, uuid, required: Document the cell belongs to - `field_key` string, required: Column key for the cell - `cell` object, required: The cell after the write, in the same shape `GET /vaults/{id}/documents` reports under `values`. - `value` string, nullable, required: The extracted value, always a string. Structured column types carry JSON in this string: a currency cell holds `{"amount","currency"}`, a date range holds `{"start","end"}`, a multi-select or list holds a JSON array of strings, and a party list holds a JSON array of `{"name","entityType"}`. A date holds `YYYY-MM-DD`. `null` means the scan found no value for this column, so a caller never has to tell an empty answer from an absent one. - `is_edited` boolean, required: True when a person replaced the scanned value by hand. The `value` is theirs, not the scan output. - `edited_at` string, nullable, required: ISO 8601 timestamp of the hand edit, or null. - `edited_by` string, nullable, required: Display name of the person who made the edit, or null. - `edited_by_user_id` integer, nullable, required: GC AI user ID of the person who made the edit, or null. Matches the `user_id` that `GET /vaults/{id}/members` reports. - `has_citations` boolean, required: True when the scan recorded where in the document it read this value. Read the citations in the app; v1 does not return them. - `extracted_at` string, nullable, required: ISO 8601 timestamp of the last write that set a value on this cell. A revert restores the scanned value without restamping it, so after a revert this is still the time of the edit that was undone, not the time of the original scan. ## Other responses - `400`: Invalid request body, a value outside the column's configured options, or a column GC AI writes itself - `401`: Missing or malformed API key - `403`: Contract Intelligence is not enabled for this account. Contact support to request access., or the caller's vault role cannot edit data - `404`: Vault or document not found, the document belongs to another vault, or access denied - `409`: The vault is archived, the document has been deleted or removed as a duplicate, or the document predates bundled-upload splitting and has no cells to write - `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)