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

# Get a sheet

GET https://api.x.flatfile.com/v1/sheets/{sheetId}

Returns a sheet in a workbook

Reference: https://reference.flatfile.com/api-reference/sheets/get

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

## Response

### 200

- `data` (Sheet, required) — A place to store tabular data

## Types

### Sheet

A place to store tabular data

- `id` (string, required) — The ID of the Sheet.
- `workbookId` (string, required) — The ID of the Workbook.
- `name` (string, required) — The name of the Sheet.
- `slug` (string, required) — The slug of the Sheet.
- `config` (SheetConfig, required) — Describes shape of data as well as behavior
- `updatedAt` (datetime, required) — Date the sheet was last updated
- `createdAt` (datetime, required) — Date the sheet was created
- `metadata` (any, optional) — Useful for any contextual metadata regarding the sheet. Store any valid json
- `namespace` (string, optional) — The scoped namespace of the Sheet.
- `lockedBy` (string, optional) — The actor who locked the Sheet.
- `lockedAt` (datetime, optional) — The time the Sheet was locked.
- `recordCounts` (RecordCounts, optional) — The precomputed counts of records in the Sheet (may not exist).
- `createdFrom` (string, optional) — The sheet id of the template that was used to create this sheet
- `lastPropagatedAt` (datetime, optional) — The last time the sheet template configuration was propagated to this sheet
- `treatments` (list of enum, optional) — An array of treatments that define the behavior of the sheet.
  - Allowed values: `CLIPPED_FROM_SHEET`, `ENUM_REFERENCE`
- `collection` (string, optional) — Collection in which to group the sheet

### SheetConfig

Describes shape of data as well as behavior

- `name` (string, required) — The name of your Sheet as it will appear to your end users.
- `fields` (list of Property, required) — Where you define your Sheet's data schema.
- `description` (string, optional) — A sentence or two describing the purpose of your Sheet.
- `slug` (string, optional) — A unique identifier for your Sheet.
- `readonly` (boolean, optional) — A boolean specifying whether or not this sheet is read only. Read only sheets are not editable by end users.
- `allowAdditionalFields` (boolean, optional) — Allow end users to add fields during mapping.
- `mappingConfidenceThreshold` (double, optional) — The minimum confidence required to automatically map a field
- `access` (list of enum, optional) — Control Sheet-level access for all users.
  - Allowed values: `*`, `add`, `edit`, `delete`, `import`
- `actions` (list of Action, optional) — An array of actions that end users can perform on this Sheet.
- `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json
- `constraints` (list of SheetConstraint, optional) — An array of constraints that end users can perform on this Sheet.
- `treatments` (list of enum, optional) — An array of treatments that define the behavior of the sheet.
  - Allowed values: `CLIPPED_FROM_SHEET`, `ENUM_REFERENCE`
- `collection` (string, optional) — Collection in which to group the sheet

### RecordCounts

- `total` (integer, required)
- `valid` (integer, required)
- `error` (integer, required)
- `byField` (map from string to FieldRecordCounts, optional) — Counts for valid, error, and total records grouped by field key
- `errorsByField` (map from string to integer, optional, deprecated)

### Property

- `type`: `string`
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `config` (StringConfig, optional)
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
- `type`: `number`
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `config` (NumberConfig, optional)
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
  - `isArray` (boolean, optional, deprecated) — Will allow multiple values and store as an array. Use enum-list type instead.
- `type`: `boolean`
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `config` (BooleanPropertyConfig, optional)
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
- `type`: `date`
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
- `type`: `enum`
  - `config` (EnumPropertyConfig, required)
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
  - `isArray` (boolean, optional, deprecated) — Will allow multiple values and store as an array. Use enum-list type instead.
  - `multi` (boolean, optional, deprecated) — Will allow multiple values and store / provide the values in an array if set. Not all field types support arrays. Use enum-list type instead.
- `type`: `reference`
  - `config` (ReferencePropertyConfig, required)
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
  - `isArray` (boolean, optional, deprecated) — Will allow multiple values and store as an array. Use enum-list type instead.
- `type`: `reference-list`
  - `config` (ReferenceListPropertyConfig, required)
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
  - `isArray` (boolean, optional, deprecated) — Will allow multiple values and store as an array. Use enum-list type instead.
- `type`: `string-list`
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.
- `type`: `enum-list`
  - `config` (EnumPropertyConfig, required)
  - `key` (string, required)
  - `actions` (list of Action, optional) — An array of actions that end users can perform on this Column.
  - `alternativeNames` (list of string, optional)
  - `appearance` (FieldAppearance, optional) — Control the appearance of this field when it's displayed in a table or input
  - `constraints` (list of Constraint, optional) — A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
  - `description` (string, optional) — A short description of the field. Markdown syntax is supported.
  - `label` (string, optional) — User friendly field name
  - `metadata` (any, optional) — Useful for any contextual metadata regarding the schema. Store any valid json here.
  - `readonly` (boolean, optional)
  - `treatments` (list of string, optional) — A unique presentation for a field in the UI.

### Action

- `label` (string, required) — The text on the Button itself
- `confirm` (boolean, optional) — Whether to show a modal to confirm the action
- `constraints` (list of ActionConstraint, optional) — A limitation or restriction on the action.
- `createdFrom` (string, optional) — The action that this action was cloned from
- `deletedAt` (datetime, optional) — The time this action was deleted
- `description` (string, optional) — The text that appears in the dialog after the action is clicked.
- `guardrail` (Guardrail, optional)
- `guide` (Guide, optional)
- `icon` (string, optional) — Icon will work on primary actions. It will only accept an already existing Flatfile design system icon.
- `inputForm` (InputForm, optional) — Adds an input form for this action after it is clicked.
- `invalidConditionalMessaging` (boolean, optional) — When enabled, shows dynamic confirmation messages based on record validation status instead of the static description
- `invalidRecordsMessage` (string, optional) — Custom message to show when there are invalid records (only used when invalidConditionalMessaging is true)
- `lastPropagatedAt` (datetime, optional) — The last time this action was propagated to a workbook
- `messages` (list of ActionMessage, optional)
- `mode` (enum, optional) — Foreground and toolbarBlocking action mode will prevent interacting with the resource until complete
  - Allowed values: `foreground`, `background`, `toolbarBlocking`
- `mount` (ActionMount, optional)
- `operation` (string, optional) — This will become the job operation that is triggered
- `primary` (boolean, optional) — A primary action will be more visibly present, whether in Sheet or Workbook.
- `schedule` (enum, optional) — Determines if the action should happen on a regular cadence.
  - Allowed values: `weekly`, `daily`, `hourly`
- `tooltip` (string, optional) — A tooltip that appears when hovering the action button
- `type` (string, optional) — **This is deprecated.**
- `validRecordsMessage` (string, optional) — Custom message to show when all records are valid (only used when invalidConditionalMessaging is true)
- `requireAllValid` (boolean, optional, deprecated) — **This is deprecated. Use `constraints` instead.**
- `requireSelection` (boolean, optional, deprecated) — **This is deprecated. Use `constraints` instead.**
- `slug` (string, optional, deprecated) — **This is deprecated. Use `operation` instead.**

### SheetConstraint

- `type`: `unique`
  - `fields` (list of string, required) — The fields that must be unique together
  - `name` (string, required) — The name of the constraint
  - `strategy` (enum, required)
    - Allowed values: `hash`, `concat`
  - `config` (CompositeUniqueConstraintConfig, optional) — Configuration options for the composite unique constraint
  - `requiredFields` (list of string, optional) — Fields that, when empty, will cause this unique constraint to be ignored
- `type`: `external`
  - `validator` (string, required)
  - `config` (any, optional)
  - `fields` (list of string, optional) — The fields that must be unique together

### FieldRecordCounts

- `total` (integer, required)
- `valid` (integer, required)
- `error` (integer, required)
- `empty` (integer, required)

### FieldAppearance

Control the appearance of this field when it's displayed in a table or input

- `size` (enum, optional) — The default visual sizing. This sizing may be overridden by a user
  - Allowed values: `xs`, `s`, `m`, `l`, `xl`

### StringConfig

- `size` (enum, required) — How much text should be storeable in this field
  - Allowed values: `tiny`, `normal`, `medium`, `long`

### Constraint

- `type`: `required`
  - `config` (RequiredConstraintConfig, optional)
- `type`: `unique`
  - `config` (UniqueConstraintConfig, optional)
- `type`: `computed`
- `type`: `external`
  - `validator` (string, required)
  - `config` (any, optional)
  - `description` (string, optional) — A full description of what this constraint configuration does
  - `label` (string, optional) — A short description of what this constraint constraint should do, example - values between 1 and 100
- `type`: `stored`
  - `validator` (string, required) — Must match the constraint validator name.
  - `config` (any, optional)
  - `description` (string, optional) — A full description of what this constraint configuration does
  - `label` (string, optional) — A short description of what this constraint constraint should do, example - values between 1 and 100
  - `version` (integer, optional) — The version of the stored constraint to use. (Defaults to version 1.)

### NumberConfig

- `decimalPlaces` (integer, optional, deprecated) — Number of decimal places to round data to

### BooleanPropertyConfig

- `allowIndeterminate` (boolean, required) — Allow a neither true or false state to be stored as `null`

### EnumPropertyConfig

- `options` (list of EnumPropertyOption, required)
- `allowCustom` (boolean, optional) — Permit the user to create new options for this specific field.
- `sortBy` (enum, optional) — Sort the options by the value of this property. Defaults to `label`.
  - Allowed values: `label`, `value`, `ordinal`

### ReferencePropertyConfig

- `ref` (string, required) — Full path reference to a sheet configuration. Must be in the same workbook.
- `key` (string, required) — Key of the property to use as the reference key. Defaults to `id`
- `filter` (ReferenceFilter, optional) — Optional filter to narrow the set of records in the reference sheet used as valid values
- `relationship` (enum, optional, deprecated) — The type of relationship this defines
  - Allowed values: `has-one`, `has-many`

### ReferenceListPropertyConfig

- `ref` (string, required) — Full path reference to a sheet configuration. Must be in the same workbook.
- `key` (string, required) — Key of the property to use as the reference key. Defaults to `id`
- `filter` (ReferenceFilter, optional) — Optional filter to narrow the set of records in the reference sheet used as valid values

### ActionConstraint

- `type`: `hasAllValid`
  - `ignoreSelection` (boolean, optional)
- `type`: `hasSelection`
- `type`: `hasData`
- `type`: `hasColumnEnabled`

### Guardrail

- `content` (string, required) — Markdown guardrail for this action

### Guide

- `content` (string, required) — Markdown guidance for this action

### InputForm

- `type` (enum, required)
  - Allowed values: `simple`
- `fields` (list of InputField, required)

### ActionMessage

- `type` (enum, required)
  - Allowed values: `error`, `info`
- `content` (string, required)

### ActionMount

- `type`: `sheet`
  - `slugs` (list of string, optional)
- `type`: `workbook`
  - `slugs` (list of string, optional)
- `type`: `field`
  - `keys` (list of string, optional)
- `type`: `document`
- `type`: `file`

### CompositeUniqueConstraintConfig

- `message` (string, optional) — Custom validation message to display when the constraint fails
- `level` (enum, optional) — Validation level (error, warn, info). Defaults to error.
  - Allowed values: `error`, `warn`, `info`

### RequiredConstraintConfig

- `message` (string, optional) — Custom validation message to display when the constraint fails
- `level` (enum, optional) — Validation level (error, warn, info). Defaults to error.
  - Allowed values: `error`, `warn`, `info`

### UniqueConstraintConfig

- `caseSensitive` (boolean, optional) — Ignore casing when determining uniqueness
- `ignoreEmpty` (boolean, optional) — Do not flag empty values as duplicate
- `message` (string, optional) — Custom validation message to display when the constraint fails
- `level` (enum, optional) — Validation level (error, warn, info). Defaults to error.
  - Allowed values: `error`, `warn`, `info`

### EnumPropertyOption

- `value` (any, required) — The value or ID of this option. This value will be sent in egress. The type is a string | integer | boolean.
- `label` (string, optional) — A visual label for this option
- `description` (string, optional) — A short description for this option
- `color` (string, optional) — An optional color to assign this option
- `icon` (string, optional) — A reference pointer to a previously registered icon
- `meta` (map from string to any, optional) — An arbitrary JSON object to be associated with this option and made available to hooks
- `alternativeNames` (list of string, optional) — Alternative names to match this enum option to
- `ordinal` (integer, optional) — The order of this option in the list. SortBy must be set to `ordinal` to use this.

### ReferenceFilter

If provided, the reference filter will narrow the set of records in the reference sheet used as the set of valid values for the record. Only rows where the value in the reference sheet's refField matches the value in this record's recordField will be used.

- `refField` (string, required) — The field key of the reference sheet to filter with
- `recordField` (string, required) — The field key of the record used to filter the reference field

### InputField

- `key` (string, required) — Unique key for a Field.
- `label` (string, required) — Visible name of a Field.
- `type` (string, required) — Field Types inform the user interface how to sort and display data.
- `description` (string, optional) — Brief description below the name of the Field.
- `defaultValue` (any, optional) — Default value for a Field.
- `config` (InputConfig, optional) — Additional configuration for enum Fields.
- `constraints` (list of InputConstraint, optional) — Indicate additional validations that will be applied to the Field.

### InputConfig

- `options` (list of InputEnumPropertyOption, required)

### InputConstraint

- `type` (enum, required)
  - Allowed values: `required`

### InputEnumPropertyOption

- `value` (any, required) — The value or ID of this option. This value will be sent in egress. The type is a string | integer | boolean.
- `label` (string, optional) — A visual label for this option, defaults to value if not provided
- `description` (string, optional) — A short description for this option
- `color` (string, optional) — An optional color to assign this option
- `icon` (string, optional) — A reference pointer to a previously registered icon
- `meta` (map from string to any, optional) — An arbitrary JSON object to be associated with this option and made available to hooks

## Examples

**Response**

```json
{
  "data": {
    "id": "us_sh_YOUR_ID",
    "workbookId": "us_wb_YOUR_ID",
    "name": "Contacts",
    "slug": "contacts",
    "config": {
      "name": "Contacts",
      "fields": [
        {
          "type": "string",
          "key": "firstName",
          "label": "First Name"
        },
        {
          "type": "string",
          "key": "lastName",
          "label": "Last Name"
        },
        {
          "type": "string",
          "key": "email",
          "label": "Email"
        }
      ],
      "slug": "contacts",
      "mappingConfidenceThreshold": 0.5
    },
    "updatedAt": "2021-08-31T18:00:00Z",
    "createdAt": "2021-08-31T18:00:00Z",
    "metadata": {
      "rowHeaders": [
        4
      ]
    }
  }
}
```

**SDK Code**

```python Example0
import requests

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

headers = {
    "X-Disable-Hooks": "true",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

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

const client = new FlatfileClient({ token: "YOUR_TOKEN" });
await client.sheets.get("us_sh_YOUR_ID");

```

```go Example0
package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Disable-Hooks", "true")
	req.Header.Add("Authorization", "Bearer <token>")

	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")

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

request = Net::HTTP::Get.new(url)
request["X-Disable-Hooks"] = 'true'
request["Authorization"] = 'Bearer <token>'

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.get("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID")
  .header("X-Disable-Hooks", "true")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    '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");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Disable-Hooks", "true");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Example0
import Foundation

let headers = [
  "X-Disable-Hooks": "true",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```