# Lookup tables

Source: https://neondeerdata.com/docs/api/lookup-tables/

Read lookup tables, query rows, and maintain table data with a permitted API key.

## Read and maintain your tables

Lookup tables hold shared data such as account owners, territories, and routing rules. The API lets your applications read and maintain the same tables your workflows use.

[Create a key](https://neondeerdata.com/docs/api/authentication/) and follow the [quickstart](https://neondeerdata.com/docs/api/quickstart/), or try a request in the [Playground](https://neondeerdata.com/docs/api/testing/). Read operations, including POST queries, do not change data. Write operations require **Read & write** permission.

## Endpoints

Use `https://api.neondeerdata.com` with an `Authorization: Bearer <API key>` header. The key's saved table and field permissions apply to every request.

| Method | Path                                         | Reference                                                                          |
| ------ | -------------------------------------------- | ---------------------------------------------------------------------------------- |
| GET    | `/v1/lookup-tables`                          | [List tables](https://neondeerdata.com/docs/api/lookup-tables/list-tables/)        |
| GET    | `/v1/lookup-tables/{table_id}`               | [Get a table](https://neondeerdata.com/docs/api/lookup-tables/get-table/)          |
| GET    | `/v1/lookup-tables/{table_id}/rows`          | [List rows](https://neondeerdata.com/docs/api/lookup-tables/list-rows/)            |
| GET    | `/v1/lookup-tables/{table_id}/rows/{row_id}` | [Get a row](https://neondeerdata.com/docs/api/lookup-tables/get-row/)              |
| POST   | `/v1/lookup-tables/{table_id}/rows/query`    | [Query rows](https://neondeerdata.com/docs/api/lookup-tables/query-rows/)          |
| POST   | `/v1/lookup-tables/{table_id}/rows`          | [Add a row](https://neondeerdata.com/docs/api/lookup-tables/create-row/)           |
| PATCH  | `/v1/lookup-tables/{table_id}/rows/{row_id}` | [Update a row](https://neondeerdata.com/docs/api/lookup-tables/update-row/)        |
| POST   | `/v1/lookup-tables/{table_id}/rows/upsert`   | [Add or update rows](https://neondeerdata.com/docs/api/lookup-tables/upsert-rows/) |
| DELETE | `/v1/lookup-tables/{table_id}/rows/{row_id}` | [Delete a row](https://neondeerdata.com/docs/api/lookup-tables/delete-row/)        |

## Configure tables and import data

- [Table settings](https://neondeerdata.com/docs/api/lookup-tables/settings/): create, rename, archive, or delete a table.
- [Fields](https://neondeerdata.com/docs/api/lookup-tables/fields/): maintain field definitions and workflow access.
- [Workflow lookups](https://neondeerdata.com/docs/api/lookup-tables/lookups/): define how a workflow finds a row and preview its answer.
- [Library and synced tables](https://neondeerdata.com/docs/api/lookup-tables/sources/): install a starter or sync an Attio status table.
- [CSV imports](https://neondeerdata.com/docs/api/lookup-tables/imports/): upload, check, preview, apply, and follow an import.

Row permissions do not automatically grant access to table settings. Imports use the required row permissions. See [permissions](https://neondeerdata.com/docs/api/permissions/).

## Guides

- [Tables and fields](https://neondeerdata.com/docs/api/lookup-tables/concepts/): field keys, value formats, and permissions.
- [Filtering](https://neondeerdata.com/docs/api/lookup-tables/filtering/): find rows with equality, membership, and combined conditions.
- [Pagination](https://neondeerdata.com/docs/api/lookup-tables/pagination/): read every page or split a large read into parallel segments.

## Writing rows

Use a custom table to add or delete rows. On tables synced from Attio or maintained by an app, update your own fields on existing rows; the source controls row membership and synced values. Writes affect Neon Deer lookup tables, not Attio records.

Follow the [write guide](https://neondeerdata.com/docs/api/lookup-tables/writing/) for permissions, value formats, version checks, and retry handling.

## Response format

A single item returns `data` as an object. A list returns `data` as an array, with `pagination.next_cursor`. Keep reading until the cursor is `null`.

Most field names use snake_case; record references use `objectId` and `recordId`. Tables, field definitions, and rows include an `object` identifier. Value maps and pagination objects do not. Treat IDs and cursors as opaque strings.

Use only documented parameters. A GET request can repeat `fields` or separate its keys with commas; other parameters appear once. Integer parameters use whole-number digits, without signs or leading zeros.

Errors include `error.code`, `error.message`, optional `error.param`, and `request_id`. Authenticated requests return `X-Request-Id`, `Cache-Control: no-store`, and [rate-limit headers](https://neondeerdata.com/docs/api/rate-limits/). Unsupported paths or methods can return `404 resource_not_found`. See [Errors](https://neondeerdata.com/docs/api/errors/) for recovery.

## OpenAPI

The public [OpenAPI 3.1 document](https://api.neondeerdata.com/v1/openapi.json) describes the schemas and accepted parameter ranges. No key is required. The document can be cached and does not carry rate-limit headers.