Core Concepts

The key building blocks of Aptly and how they relate to each other

Overview

Aptly is a flexible workspace for property management teams. Before making your first API call, it helps to understand the core building blocks and how they fit together.

---

Board

A Board is a collection of records organized around a specific workflow or data set. Property management teams typically create boards to track things like units, leases, maintenance requests, prospects, or vendors.

Every board has its own schema, its own set of stages, and its own API key. When you connect to Aptly via the API, you are always connecting to a specific board.Pagination starts at page 0.

Card

A Card is a single record on a board. If a board represents your unit inventory, each card is one unit. If a board tracks maintenance requests, each card is one request.

Cards contain field values that match the schema of the board they belong to. You create, update, and retrieve cards using the Aptly API.

Stage

A Stage represents the current status or phase of a card within a board’s workflow. Stages are defined per board and might represent things like New, In Progress, Pending Approval, or Closed.

When posting a card via the API, you can set or update its stage by passing the stage name as a field value.

Schema

A Schema describes the structure of a board, specifically the fields it contains, their names, and their UUIDs. Before posting data to a board, it is useful to fetch the schema so you know exactly what field names to use in your request payload.

Field names in the API must match the board schema exactly. You can retrieve the schema for any board using the Get Board Schema endpoint.

Card Source

A Card Source is a configured integration that brings data into a board. The REST API is one type of card source. When you enable the API on a board, Aptly generates a unique API key and POST URL scoped to that board.

Card Sources also control behavior like whether incoming records create new cards or update existing ones, and whether new fields are automatically added to the board schema.

API Key

Each board generates its own API key when the REST API card source is enabled. The key is passed as the x-token header on every request and scopes your access to that specific board.

API keys are managed per board under Card Sources > API in the Aptly UI. If a key is compromised, it can be regenerated from the same screen.

Webhook

A Webhook is an outbound notification that Aptly sends to a URL you provide whenever a card on a board is created, updated, or deleted. Webhooks allow your systems to react to changes in real time without polling the API.

Webhooks are configured per board under Card Sources > API alongside the REST API settings.