> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/introduction/overview.md).

# Overview

Learn about the REST API

The Listener API is the primary interface for managing **People** (contacts) and **Records** (stack entries) in your workspace. It provides a RESTful JSON API for creating, reading, updating, and deleting entities, as well as managing consent preferences, querying relationships, and filtering by attribute values.

### Core Resources

#### People

People represent contacts in your system. Each person has built-in fields (`first_name`, `last_name`, `email`, etc.) and can have custom attributes defined by your workspace configuration. People are identified by either a **UUID** (internal ID) or an **external ID** that you assign.

See the People endpoints for all available operations.

#### Records

Records are entries within a **Stack** — a configurable data structure in your workspace (e.g., orders, tickets, products). Each record belongs to a specific stack and is identified by either a **record ID** (MongoDB ObjectID) or an **external ID**.

Stacks come in two types:

* **Item stacks** — Records can be created, updated, and deleted.
* **Event stacks** — Records are immutable after creation (no updates or deletes).

See the Records endpoints for all available operations.

### Guides

Before integrating with the API, review these guides for essential information on how requests and responses work:

* Base URL — Versioned base path and request timeout
* Authentication — JWT token usage and header format
* Scopes — Which token scopes are required for each operation
* Request Format — Content type, data binding, and automatic string trimming
* Response Format — Standard response envelope and status codes
* Pagination — Cursor-based pagination for list, filter, and related-entity endpoints
* PUT vs PATCH — Full replacement vs partial update semantics
* Attribute Normalization — How relationship attribute values are automatically normalized
* Auto-Create — Automatic creation of referenced entities that don't yet exist