> 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.

# Finds and replaces field values matching search criteria


PUT https://api.x.flatfile.com/v1/sheets/{sheetId}/find-replace
Content-Type: application/json

Searches for all values that match the 'find' value (globally or for a specific field via 'fieldKey') and replaces them with the 'replace' value. Wrap 'find' value in double quotes for exact match (""). Returns a commitId for the updated records

Reference: https://reference.flatfile.com/api-reference/records/find-and-replace

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, 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
- `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

### Body (application/json)

This endpoint expects an object.

- `fieldKey` (string, required) — A unique key used to identify a field in a sheet
- `find` (CellValueUnion, optional) — A value to find for a given field in a sheet. For exact matches, wrap the value in double quotes ("Bob")
- `replace` (CellValueUnion, optional) — The value to replace found values with

## Response

### 200

- `data` (Version, required)

## Types

### CellValueUnion

### Version

- `versionId` (string, required) — Version ID

## Examples

**Request**

```json
{
  "fieldKey": "email"
}
```

**Response**

```json
{
  "data": {
    "versionId": "us_vr_YOUR_ID"
  }
}
```

**SDK Code**

```python Example0
import requests

url = "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/find-replace"

payload = { "fieldKey": "email" }
headers = {
    "X-Disable-Hooks": "true",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```typescript Example0
import { FlatfileClient } from "@flatfile/api";

const client = new FlatfileClient({ token: "YOUR_TOKEN" });
await client.records.findAndReplace("us_sh_YOUR_ID", {
    fieldKey: "email"
});

```

```go Example0
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/find-replace"

	payload := strings.NewReader("{\n  \"fieldKey\": \"email\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-Disable-Hooks", "true")
	req.Header.Add("Authorization", "Bearer <token>")
	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/find-replace")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-Disable-Hooks"] = 'true'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fieldKey\": \"email\"\n}"

response = http.request(request)
puts response.read_body
```

```java Example0
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/find-replace")
  .header("X-Disable-Hooks", "true")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fieldKey\": \"email\"\n}")
  .asString();
```

```php Example0
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/find-replace', [
  'body' => '{
  "fieldKey": "email"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    '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/find-replace");
var request = new RestRequest(Method.PUT);
request.AddHeader("X-Disable-Hooks", "true");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"fieldKey\": \"email\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Example0
import Foundation

let headers = [
  "X-Disable-Hooks": "true",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["fieldKey": "email"] 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/find-replace")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```