> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://reference.flatfile.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://reference.flatfile.com/_mcp/server. # Bulk update records with field values PATCH https://api.x.flatfile.com/v1/sheets/{sheetId}/records/bulk-update Content-Type: application/json Updates multiple records at once with the same field values based on filter criteria. This is similar to a SQL UPDATE statement where you can update specific fields for all records matching certain conditions. Reference: https://reference.flatfile.com/api-reference/records/bulk-update ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `sheetId` (string, required) — ID of sheet ### Query parameters - `filter` (enum, optional) — Options to filter records - Allowed values: `valid`, `error`, `all`, `none` - `filterField` (string, optional) — Name of field by which to filter records - `searchValue` (string, optional) — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("") - `searchField` (string, optional) — Use this to narrow the searchValue results to a specific field - `sortField` (string, optional) — Name of field by which to sort records - `sortDirection` (enum, optional) — Sort direction - asc (ascending) or desc (descending) - Allowed values: `asc`, `desc` - `ids` (string, optional) — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records - `q` (string, optional) — An FFQL query used to filter the result set - `silent` (boolean, optional) — Whether to suppress events for this bulk update ### Body (application/json) This endpoint expects an object. - `fieldUpdates` (map from string to CellValue, required) — A map of field keys to cell values that will be applied to all matching records ## Response ### 200 - `data` (Version, required) ## Types ### CellValue - `valid` (boolean, optional) - `messages` (list of ValidationMessage, optional) - `value` (CellValueUnion, optional) - `layer` (string, optional) - `updatedAt` (datetime, optional) - `metadata` (map from string to any, optional, deprecated) — Deprecated, use record level metadata instead. ### Version - `versionId` (string, required) — Version ID ### ValidationMessage Record data validation messages - `field` (string, optional) - `type` (enum, optional) - Allowed values: `error`, `warn`, `info` - `source` (enum, optional) - Allowed values: `required-constraint`, `unique-constraint`, `custom-logic`, `unlinked`, `invalid-option`, `is-artifact` - `message` (string, optional) - `path` (string, optional) — This JSONPath is based on the root of mapped cell object. ### CellValueUnion ## Examples **Request** ```json { "fieldUpdates": { "status": { "value": "completed" }, "processedAt": { "value": "2023-11-20T16:59:40.286Z" } } } ``` **Response** ```json { "data": { "versionId": "us_vr_YOUR_ID" } } ``` **SDK Code** ```typescript Example0 import { FlatfileClient } from "@flatfile/api"; const client = new FlatfileClient({ token: "YOUR_TOKEN" }); await client.records.bulkUpdate("us_sh_YOUR_ID", { fieldUpdates: { "status": { value: "completed" }, "processedAt": { value: "2023-11-20T16:59:40.286Z" } } }); ``` ```python Example0 import requests url = "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records/bulk-update" payload = { "fieldUpdates": { "status": { "value": "completed" }, "processedAt": { "value": "2023-11-20T16:59:40.286Z" } } } headers = { "X-Disable-Hooks": "true", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```go Example0 package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records/bulk-update" payload := strings.NewReader("{\n \"fieldUpdates\": {\n \"status\": {\n \"value\": \"completed\"\n },\n \"processedAt\": {\n \"value\": \"2023-11-20T16:59:40.286Z\"\n }\n }\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("X-Disable-Hooks", "true") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example0 require 'uri' require 'net/http' url = URI("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records/bulk-update") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["X-Disable-Hooks"] = 'true' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"fieldUpdates\": {\n \"status\": {\n \"value\": \"completed\"\n },\n \"processedAt\": {\n \"value\": \"2023-11-20T16:59:40.286Z\"\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java Example0 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records/bulk-update") .header("X-Disable-Hooks", "true") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"fieldUpdates\": {\n \"status\": {\n \"value\": \"completed\"\n },\n \"processedAt\": {\n \"value\": \"2023-11-20T16:59:40.286Z\"\n }\n }\n}") .asString(); ``` ```php Example0 request('PATCH', 'https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records/bulk-update', [ 'body' => '{ "fieldUpdates": { "status": { "value": "completed" }, "processedAt": { "value": "2023-11-20T16:59:40.286Z" } } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'X-Disable-Hooks' => 'true', ], ]); echo $response->getBody(); ``` ```csharp Example0 using RestSharp; var client = new RestClient("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records/bulk-update"); var request = new RestRequest(Method.PATCH); request.AddHeader("X-Disable-Hooks", "true"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"fieldUpdates\": {\n \"status\": {\n \"value\": \"completed\"\n },\n \"processedAt\": {\n \"value\": \"2023-11-20T16:59:40.286Z\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example0 import Foundation let headers = [ "X-Disable-Hooks": "true", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["fieldUpdates": [ "status": ["value": "completed"], "processedAt": ["value": "2023-11-20T16:59:40.286Z"] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records/bulk-update")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```