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

# Preview a mutation

POST https://api.x.flatfile.com/v1/jobs/preview-mutation
Content-Type: application/json

Preview the results of a mutation

Reference: https://reference.flatfile.com/api-reference/jobs/preview-mutation

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects a MutateJobConfig.

- `sheetId` (string, required) — Sheet ID
- `mutateRecord` (string, required) — A JavaScript function that will be run on each record in the sheet, it should return a mutated record.
- `mutationId` (string, optional) — If the mutation was generated through some sort of id-ed process, this links this job and that process.
- `snapshotLabel` (string, optional) — If specified, a snapshot will be generated with this label
- `snapshotId` (string, optional) — The generated snapshotId will be stored here
- `filter` (enum, optional) — Options to filter records
  - Allowed values: `valid`, `error`, `all`, `none`
- `filterField` (string, optional) — Use this to narrow the valid/error filter results to a specific field
- `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
- `q` (string, optional)
- `ids` (list of 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

## Response

### 200

- `data` (list of DiffRecord, required) — List of DiffRecord objects

## Types

### DiffRecord

- `id` (string, required) — Record ID
- `values` (map from string to DiffValue, required)
- `commitId` (string, optional) — Commit ID
- `config` (RecordConfig, optional) — Configuration of a record or specific fields in the record
- `metadata` (map from string to any, optional)
- `resolves` (list of Resolve, optional)
- `valid` (boolean, optional) — Auto-generated value based on whether the record contains a field with an error message. Cannot be set via the API.
- `messages` (list of ValidationMessage, optional, deprecated) — This record level `messages` property is deprecated and no longer stored or used. Use the `messages` property on the individual cell values instead. This property will be removed in a future release.
- `versionId` (string, optional, deprecated) — Deprecated, use `commitId` instead.

### DiffValue

- `clipValue` (CellValueUnion, optional)
- `layer` (string, optional)
- `messages` (list of ValidationMessage, optional)
- `snapshotValue` (CellValueUnion, optional)
- `updatedAt` (datetime, optional)
- `valid` (boolean, optional)
- `value` (CellValueUnion, optional)
- `warning` (boolean, optional)
- `warnings` (list of string, optional)
- `metadata` (map from string to any, optional, deprecated) — Deprecated, use record level metadata instead.

### RecordConfig

Configuration of a record or specific fields in the record

- `readonly` (boolean, optional)
- `fields` (map from string to CellConfig, optional)
- `markedForDeletion` (boolean, optional)

### Resolve

Conflict resolutions for a record

- `field` (string, optional)
- `type` (enum, optional)
  - Allowed values: `conflict`, `resolve`
- `resolveTo` (enum, optional)
  - Allowed values: `clip`, `main`, `snapshot`
- `clip_value_reference` (string, optional)
- `main_value_reference` (string, optional)
- `removedFromMainResolution` (enum, optional)
  - Allowed values: `ignore`, `restore`

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

### CellConfig

CellConfig

- `readonly` (boolean, optional)

## Examples

**Request**

```json
{
  "sheetId": "sheetId",
  "mutateRecord": "mutateRecord"
}
```

**Response**

```json
{
  "data": [
    {
      "id": "id",
      "values": {
        "values": {
          "clipValue": "clipValue",
          "layer": "layer",
          "messages": [
            {
              "field": "field",
              "type": "error",
              "source": "required-constraint",
              "message": "message",
              "path": "path"
            },
            {
              "field": "field",
              "type": "error",
              "source": "required-constraint",
              "message": "message",
              "path": "path"
            }
          ],
          "snapshotValue": "snapshotValue",
          "updatedAt": "2024-01-15T09:30:00Z",
          "valid": true,
          "value": "value",
          "warning": true,
          "warnings": [
            "warnings",
            "warnings"
          ],
          "metadata": {
            "metadata": {
              "key": "value"
            }
          }
        }
      },
      "commitId": "commitId",
      "config": {
        "readonly": true,
        "fields": {
          "fields": {
            "readonly": true
          }
        },
        "markedForDeletion": true
      },
      "metadata": {
        "metadata": {
          "key": "value"
        }
      },
      "resolves": [
        {
          "field": "field",
          "type": "conflict",
          "resolveTo": "clip",
          "clip_value_reference": "clip_value_reference",
          "main_value_reference": "main_value_reference",
          "removedFromMainResolution": "ignore"
        },
        {
          "field": "field",
          "type": "conflict",
          "resolveTo": "clip",
          "clip_value_reference": "clip_value_reference",
          "main_value_reference": "main_value_reference",
          "removedFromMainResolution": "ignore"
        }
      ],
      "valid": true,
      "messages": [
        {
          "field": "field",
          "type": "error",
          "source": "required-constraint",
          "message": "message",
          "path": "path"
        },
        {
          "field": "field",
          "type": "error",
          "source": "required-constraint",
          "message": "message",
          "path": "path"
        }
      ],
      "versionId": "versionId"
    },
    {
      "id": "id",
      "values": {
        "values": {
          "clipValue": "clipValue",
          "layer": "layer",
          "messages": [
            {
              "field": "field",
              "type": "error",
              "source": "required-constraint",
              "message": "message",
              "path": "path"
            },
            {
              "field": "field",
              "type": "error",
              "source": "required-constraint",
              "message": "message",
              "path": "path"
            }
          ],
          "snapshotValue": "snapshotValue",
          "updatedAt": "2024-01-15T09:30:00Z",
          "valid": true,
          "value": "value",
          "warning": true,
          "warnings": [
            "warnings",
            "warnings"
          ],
          "metadata": {
            "metadata": {
              "key": "value"
            }
          }
        }
      },
      "commitId": "commitId",
      "config": {
        "readonly": true,
        "fields": {
          "fields": {
            "readonly": true
          }
        },
        "markedForDeletion": true
      },
      "metadata": {
        "metadata": {
          "key": "value"
        }
      },
      "resolves": [
        {
          "field": "field",
          "type": "conflict",
          "resolveTo": "clip",
          "clip_value_reference": "clip_value_reference",
          "main_value_reference": "main_value_reference",
          "removedFromMainResolution": "ignore"
        },
        {
          "field": "field",
          "type": "conflict",
          "resolveTo": "clip",
          "clip_value_reference": "clip_value_reference",
          "main_value_reference": "main_value_reference",
          "removedFromMainResolution": "ignore"
        }
      ],
      "valid": true,
      "messages": [
        {
          "field": "field",
          "type": "error",
          "source": "required-constraint",
          "message": "message",
          "path": "path"
        },
        {
          "field": "field",
          "type": "error",
          "source": "required-constraint",
          "message": "message",
          "path": "path"
        }
      ],
      "versionId": "versionId"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.x.flatfile.com/v1/jobs/preview-mutation"

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

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

print(response.json())
```

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

const client = new FlatfileClient({ token: "YOUR_TOKEN" });
await client.jobs.previewMutation({
    sheetId: "sheetId",
    mutateRecord: "mutateRecord"
});

```

```go
package main

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

func main() {

	url := "https://api.x.flatfile.com/v1/jobs/preview-mutation"

	payload := strings.NewReader("{\n  \"sheetId\": \"sheetId\",\n  \"mutateRecord\": \"mutateRecord\"\n}")

	req, _ := http.NewRequest("POST", 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
require 'uri'
require 'net/http'

url = URI("https://api.x.flatfile.com/v1/jobs/preview-mutation")

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

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

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

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

HttpResponse<String> response = Unirest.post("https://api.x.flatfile.com/v1/jobs/preview-mutation")
  .header("X-Disable-Hooks", "true")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sheetId\": \"sheetId\",\n  \"mutateRecord\": \"mutateRecord\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.x.flatfile.com/v1/jobs/preview-mutation', [
  'body' => '{
  "sheetId": "sheetId",
  "mutateRecord": "mutateRecord"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Disable-Hooks' => 'true',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.x.flatfile.com/v1/jobs/preview-mutation");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Disable-Hooks", "true");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"sheetId\": \"sheetId\",\n  \"mutateRecord\": \"mutateRecord\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Disable-Hooks": "true",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "sheetId": "sheetId",
  "mutateRecord": "mutateRecord"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.x.flatfile.com/v1/jobs/preview-mutation")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```