Developers
Last updated November 18, 2026
The Freedom Transactions API gives a brokerage’s own apps read access to its deals, roster, commissions, agent billing, earnest money and checklists. Webhooks tell those apps when something happens. The broker makes keys and webhooks in FT under API and webhooks.
Authentication
Send the key in every request. Keys start with ft_. FT shows a key once, when it’s made. Keep it on your server, never in a browser or app.
curl https://transactions.freedomidaho.com/api/v1/deals -H "Authorization: Bearer ft_…"
A key reads one brokerage, and only what its scopes allow:
read:deals: Deals and checklistsread:agents: Agent rosterread:commissions: Finalized commissions and disbursementsread:billing: Agent billing lines and balancesread:listings: Listings and offersread:earnest: Earnest money and trust balanceswrite:webhooks: Manage webhook endpoints
Errors are JSON: { "error": { "code": "missing_scope", "message": "…" } }, with 401 for a missing or revoked key, 403 for a missing scope, 404, and 429.
Endpoints
All answers are JSON. Money is in cents. Dates are YYYY-MM-DD; times are UTC, ISO 8601.
GET /api/v1/me: The key's brokerage and scopes. (any)GET /api/v1/deals: Deals: address, side, status, stage, price, acceptance and closing dates, agents, office. (read:deals)GET /api/v1/deals/{id}: One deal, with its deadlines. (read:deals)GET /api/v1/checklists: Each deal's checklist items and review status. (read:deals)GET /api/v1/checklists/{deal_id}: One deal's checklist. (read:deals)GET /api/v1/agents: The roster. (read:agents)GET /api/v1/agents/{id}: One agent. (read:agents)GET /api/v1/commissions: Finalized commissions, a line per agent per side. (read:commissions)GET /api/v1/commissions/{deal_id}: One deal's finalized commission. (read:commissions)GET /api/v1/billing/lines: Charges, credits, payments and deductions on agents' accounts. (read:billing)GET /api/v1/billing/balances: Each agent's balance today (not paged). (read:billing)GET /api/v1/earnest: Each deal's earnest money status and trust balance. (read:earnest)GET /api/v1/earnest/{deal_id}: One deal's earnest money. (read:earnest)GET /api/v1/trust: The trust account's total today. (read:earnest)GET /api/v1/listings: Listings. (read:listings)GET /api/v1/offers: Offers, without buyer names. (read:listings)GET /api/v1/webhooks: Your webhook endpoints. (write:webhooks)POST /api/v1/webhooks: Add an endpoint: { url, events, description }. The secret is in this response only. An event name FT doesn't know gets a 422 naming it. (write:webhooks)DELETE /api/v1/webhooks/{id}: Delete an endpoint. (write:webhooks)
Privacy: the API never returns client names, emails or phone numbers, review notes, or documents. Deals list the brokerage’s own agents.
Pagination and syncing
- Lists return
{ "data": [...], "next_cursor": "..." }. Passcursorto get the next page.next_cursoris null on the last page. limitis 1 to 100, 50 by default.- Lists are ordered by when each record last changed, oldest first.
updated_since=2026-11-18T00:00:00Zreturns records changed since then. - Paging with
cursornever skips a saved change: a change still being saved when you ask is held back until it’s done, then comes after your cursor. So a change can show up a moment after it was made. - To stay in sync, save the time you start each sync and pass it as
updated_sincenext time, less a few minutes. A record can appear twice; use its id. - A deal moves up when it, its contract, its agents, or its address or MLS number change. Renaming an office or a team doesn’t move the deals or agents that show it; fetch them again if you need the new name.
- An admin can reopen a finalized commission to correct it. Until it’s finalized again it drops out of
/commissions(and/commissions/{deal_id}answers 404). - Deleted records aren’t listed. Deals that fall through stay, with status
cancelled.
Rate limits
120 requests a minute per key. Each answer has X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Past the limit you get 429 with Retry-After in seconds.
Webhooks
FT POSTs JSON to your HTTPS URL when one of these happens:
deal.created: A deal is started from a contract (needs read:deals to subscribe through the API)deal.confirmed: A deal's terms are confirmed (needs read:deals to subscribe through the API)deal.closed: A deal closes (needs read:deals to subscribe through the API)deal.fell_through: A deal falls through (needs read:deals to subscribe through the API)commission.finalized: A commission is finalized (needs read:commissions to subscribe through the API)disbursement.approved: A disbursement form is approved (needs read:commissions to subscribe through the API)earnest.status_changed: Earnest money changes status (needs read:earnest to subscribe through the API)checklist.item_rejected: A checklist item is rejected (needs read:deals to subscribe through the API)listing.created: A listing is added (needs read:listings to subscribe through the API)offer.accepted: An offer is accepted (needs read:listings to subscribe through the API)
Every event has the same shape. data holds ids and a few small fields; fetch the record from the API for the rest.
{
"id": "6f1c2a40-0b7e-4c43-9d55-2f8f1f6e9a11",
"type": "deal.closed",
"created_at": "2026-11-18T20:14:03.512Z",
"brokerage_id": "2a9e0c7d-41f2-4d0b-8a77-5c1b3e9f0d22",
"data": { "deal_id": "b3d4e5f6-0718-4a2b-9c3d-4e5f60718293", "closed_on": "2026-11-18" }
}- Answer with any 2xx within 10 seconds. Anything else is a failure. Redirects aren’t followed.
- Failures are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then dropped.
- An endpoint that fails 10 times in a row, over at least 24 hours, is turned off, and the broker is told.
- Events can arrive more than once or out of order. Use
webhook-idto skip ones you’ve seen. - Your URL must be public: FT won’t send to private, loopback or link-local addresses.
Checking signatures
FT signs every request the Standard Webhooks way, so their libraries work too. Headers: webhook-id, webhook-timestamp (Unix seconds) and webhook-signature (v1, and a base64 HMAC-SHA256 of id.timestamp.body, keyed with the bytes of your secret after whsec_). Refuse anything older than five minutes.
import crypto from "node:crypto";
// secret: the whsec_... value FT showed when you added the endpoint.
// body: the raw request body, as a string, before any JSON parsing.
export function verifyFt(secret, headers, body) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signature = headers["webhook-signature"];
if (!id || !timestamp || !signature) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = "v1," + crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
const want = Buffer.from(expected);
return signature.split(" ").some((given) => {
const got = Buffer.from(given);
return got.length === want.length && crypto.timingSafeEqual(got, want);
});
}