Get records

GET

https://api.x.flatfile.com/v1/sheets/:sheetId/records

GET

/v1/sheets/:sheetId/records

curl https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records \
     -H "X-Disable-Hooks: true" \
     -H "Authorization: Bearer <token>"

{
  "data": {
    "records": [
      {
        "id": "us_rc_YOUR_ID",
        "values": {
          "firstName": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "John"
          },
          "lastName": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "Smith"
          },
          "email": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "john.smith@example.com"
          }
        },
        "valid": true,
        "metadata": {},
        "config": {}
      }
    ],
    "success": true,
    "commitId": "us_vr_YOUR_ID",
    "counts": {
      "total": 1000,
      "valid": 1000,
      "error": 0
    },
    "versionId": "us_vr_YOUR_ID"
  }
}

Returns records from a sheet in a workbook

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

sheetIdstringRequired

ID of sheet

Query parameters

versionIdstringOptionalDeprecated

Deprecated, use commitId instead.

commitIdstringOptional

Commit ID

sinceVersionIdstringOptionalDeprecated

Deprecated, use sinceCommitId instead.

sinceCommitIdstringOptional

Commit ID

sortFieldstringOptional

Name of field by which to sort records

sortDirectionenumOptional

Sort direction - asc (ascending) or desc (descending)

Allowed values:

filterenumOptional

Options to filter records

Allowed values:

filterFieldstringOptional

Name of field by which to filter records

searchValuestringOptional

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

searchFieldstringOptional

Use this to narrow the searchValue results to a specific field

idsstringOptional

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. Maximum of 100 allowed.

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. Maximum of 100 allowed.

pageSizeintegerOptional

Number of records to return in a page (default 10,000)

pageNumberintegerOptional

Based on pageSize, which page of records to return (Note - numbers start at 1)

includeCountsbooleanOptionalDeprecated

DEPRECATED Use GET /sheets/:sheetId/counts

includeLengthbooleanOptional

The length of the record result set, returned as counts.total

includeLinksbooleanOptional

If true, linked records will be included in the results. Defaults to false.

includeMessagesbooleanOptional

Include error messages, defaults to false.

fieldsstringOptional

A list of field keys to include in the response. If not provided, all fields will be included.

forstringOptional

if "for" is provided, the query parameters will be pulled from the event payload

qstringOptional

An FFQL query used to filter the result set

Response

This endpoint returns an object.

dataobject

A list of records with optional record counts

Errors

400

Bad Request Error

404

Not Found Error

Authentication

Path parameters

Headers

Query parameters

Response

Errors