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 checklists
  • read:agents: Agent roster
  • read:commissions: Finalized commissions and disbursements
  • read:billing: Agent billing lines and balances
  • read:listings: Listings and offers
  • read:earnest: Earnest money and trust balances
  • write: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": "..." }. Pass cursor to get the next page. next_cursor is null on the last page.
  • limit is 1 to 100, 50 by default.
  • Lists are ordered by when each record last changed, oldest first. updated_since=2026-11-18T00:00:00Z returns records changed since then.
  • Paging with cursor never 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_since next 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-id to 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);
  });
}