EXR Commercial API

Version: 1.0.0
Base URL: https://cre.exrplatform.com/api/v1
OpenAPI specification: https://cre.exrplatform.com/api/v1/openapi.json

Source precedence

The OpenAPI document is authoritative for operations, parameters, schemas, scopes, and response contracts. This guide explains how to use that contract; do not infer undocumented fields or behavior.

Authentication

Send Authorization: Bearer exr_live_… on every authenticated request. Missing, invalid, or revoked tokens return 401. Documentation is public; API data access still requires a token with the required scope.

Example request

curl -H "Authorization: Bearer exr_live_..." \
  https://cre.exrplatform.com/api/v1/deals?limit=25

Operations

GET `/api/v1/health`

Liveness probe. No authentication required.

• Authentication: None
• Idempotency: Not applicable.
• Success response: object

GET `/api/v1/deals`

Returns deals visible to the token's owning user in exact (updatedAt DESC, id DESC) order. The opaque cursor identifies the final tuple on the previous page; the next page begins strictly below that (updatedAt, id) boundary, so equal timestamps continue by descending id without gaps. Requires the deals:read scope. Financial fields are included only when the token also has deals:financials:read.

- Authentication: Bearer; scope deals:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of deals to return (1–100).
- cursor (query; string) — Opaque (updatedAt, id) boundary from a previous response's nextCursor; pass it back unchanged.
- Success response: object

POST `/api/v1/deals`

Creates a deal owned by the token's user. Requires the deals:write scope. The owner is credited the full 100% commission split; split edits are made via PATCH. Money fields are strings of integer cents. Idempotent via the Idempotency-Key header. financials.leaseTerms is validated against the lease commission calculator's contract (see DealLeaseTerms): out-of-contract values such as a fractional or inconsistent termMonths, negative or fractional cents, out-of-range basis points, or unknown enum values are rejected with 400 invalid_body naming the key, never coerced or stored.

- Authentication: Bearer; scope deals:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: DealCreate
- Success response: object

GET `/api/v1/deals/{id}`

Returns a single deal by id. Responds 404 (not 403) when the deal does not exist OR is not visible to the token, so existence is never disclosed. Requires the deals:read scope.

- Authentication: Bearer; scope deals:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/deals/{id}`

Partially updates a deal. Requires the deals:write scope. Authorizes owner, collaborator, or admin; a missing or not-editable deal responds 404. Only the fields you send are changed. Commission splits are set via the splits block, which must describe exactly the current collaborator set and total 100% (re-validated under a row lock). Fields and splits commit as one logical change with one immutable deal.updated event durably enqueued in the same transaction before asynchronous delivery. A financials.leaseTerms fragment is merged onto the stored terms and validated against the lease commission calculator's contract (see DealLeaseTerms): every key you send must already be in contract, and when the fragment touches termMonths or years the merged record must keep termMonths consistent with the row count; out-of-contract values are rejected with 400 invalid_body naming the key and the stored record is left untouched.

- Authentication: Bearer; scope deals:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: DealUpdate
- Success response: object

DELETE `/api/v1/deals/{id}`

Deletes a deal. Requires the deals:write scope. Owner or admin only; a collaborator or non-member responds 404 to conceal existence.

- Authentication: Bearer; scope deals:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/tenants`

Returns Commercial Tenants visible to the token's owning user, newest first. Cursor-paginated. Requires the tenants:read scope. A tenant with no relationship owner is firm-wide; otherwise visibility is the creator, lead owner, or collaborators (admins see all).

- Authentication: Bearer; scope tenants:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of tenants to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/tenants`

Creates a Commercial Tenant owned by the token's user (its creator). Requires the tenants:write scope. Emits a tenant.created webhook. Send an Idempotency-Key to make retries safe.

- Authentication: Bearer; scope tenants:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: TenantWrite
- Success response: object

GET `/api/v1/tenants/{id}`

Returns a single tenant by id. Responds 404 (not 403) when the tenant does not exist OR is not visible to the token. Requires the tenants:read scope.

- Authentication: Bearer; scope tenants:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/tenants/{id}`

Partially updates a tenant. Requires the tenants:write scope and edit access (creator, lead owner, or admin; firm-wide tenants are editable by any token holder). Responds 404 (not 403) when not found or not editable. Emits a tenant.updated webhook.

- Authentication: Bearer; scope tenants:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: TenantWrite
- Success response: object

DELETE `/api/v1/tenants/{id}`

Deletes a tenant. Requires the tenants:write scope and delete access (creator, lead owner, or admin — stricter than edit). Responds 404 (not 403) when not found or not deletable. Emits a tenant.deleted webhook.

- Authentication: Bearer; scope tenants:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/prospects`

Returns prospects visible to the token's owning user, newest first. Cursor-paginated. Requires the prospects:read scope. Visibility is the current owner (ownerUserId) plus any prospecting-team member (admins see all).

- Authentication: Bearer; scope prospects:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of prospects to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/prospects`

Creates a prospect owned by the token's user. propertyAddress is required. Requires the prospects:write scope. Emits a prospect.created webhook. Send an Idempotency-Key to make retries safe.

- Authentication: Bearer; scope prospects:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: ProspectWrite
- Success response: object

GET `/api/v1/prospects/{id}`

Returns a single prospect by id. Responds 404 (not 403) when it does not exist OR is not visible to the token. Requires the prospects:read scope.

- Authentication: Bearer; scope prospects:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/prospects/{id}`

Partially updates a prospect. Requires the prospects:write scope and access (owner, team member, or admin). Responds 404 (not 403) when not found or not accessible. Emits a prospect.updated webhook.

- Authentication: Bearer; scope prospects:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: ProspectWrite
- Success response: object

DELETE `/api/v1/prospects/{id}`

Hard-deletes a prospect. Requires the prospects:write scope; hard delete is admin-only (non-admins should archive instead). Responds 404 when not accessible, 403 when not an admin. Emits a prospect.deleted webhook.

- Authentication: Bearer; scope prospects:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/clients`

Returns CRM clients visible to the token's owning user, newest first. Cursor-paginated. Requires the clients:read scope. Clients are private: visibility is the owner (ownerUserId), the creator (createdByUserId), or a collaborator (admins see all).

- Authentication: Bearer; scope clients:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of clients to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/clients`

Creates a CRM client. name, clientType, and entityType are required. The creator is the token's user. ownerUserId defaults to the creator when omitted; a non-existent owner → 400 invalid_reference. Requires the clients:write scope. Emits a client.created webhook. Send an Idempotency-Key to make retries safe.

- Authentication: Bearer; scope clients:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: ClientWrite
- Success response: object

GET `/api/v1/clients/{id}`

Returns a single CRM client by id. Responds 404 (not 403) when it does not exist OR is not visible to the token. Requires the clients:read scope.

- Authentication: Bearer; scope clients:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/clients/{id}`

Partially updates a CRM client. Requires the clients:write scope and edit rights (owner, creator, or admin). Collaborators are view-only. Responds 404 (not 403) when not found or not editable. Only the current owner or an admin may change ownerUserId (else 403); a non-existent new owner → 400. Emits a client.updated webhook.

- Authentication: Bearer; scope clients:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: ClientUpdate
- Success response: object

DELETE `/api/v1/clients/{id}`

Hard-deletes a CRM client. Requires the clients:write scope and edit rights (owner, creator, or admin). Responds 404 when not found or not editable. Emits a client.deleted webhook.

- Authentication: Bearer; scope clients:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/workspaces`

Returns workspaces (leasing brochures) visible to the token's owning user, newest first. Cursor-paginated. Requires the workspaces:read scope. Visibility is the creator plus collaborators (admins see all).

- Authentication: Bearer; scope workspaces:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of workspaces to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/workspaces`

Creates a workspace (leasing brochure) owned by the token's user. title and addressLine1 are required. Requires the workspaces:write scope. Emits a workspace.created webhook. Send an Idempotency-Key to make retries safe.

- Authentication: Bearer; scope workspaces:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: WorkspaceWrite
- Success response: object

GET `/api/v1/workspaces/{id}`

Returns a single workspace (leasing brochure) by id. Responds 404 (not 403) when it does not exist OR is not visible to the token. Requires the workspaces:read scope.

- Authentication: Bearer; scope workspaces:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/workspaces/{id}`

Partially updates a workspace (leasing brochure). Requires the workspaces:write scope and edit access (owner, collaborator, or admin). Responds 404 (not 403) when not found or not accessible. Emits a workspace.updated webhook.

- Authentication: Bearer; scope workspaces:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: WorkspaceWrite
- Success response: object

DELETE `/api/v1/workspaces/{id}`

Deletes a workspace (leasing brochure). Requires the workspaces:write scope; deletion is restricted to the owner or an admin (collaborators may edit but not delete). Responds 404 (not 403) when not found or not accessible. Emits a workspace.deleted webhook.

- Authentication: Bearer; scope workspaces:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/brokers`

Returns all brokers, newest first. Cursor-paginated. Brokers are firm-wide visible. Requires the brokers:read scope.

- Authentication: Bearer; scope brokers:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of brokers to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/brokers`

Creates a broker owned by the token's user. Requires the brokers:write scope. brokerageId and brokerSpecialtyId, when sent, must reference existing rows (else 400 invalid_reference).

- Authentication: Bearer; scope brokers:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: BrokerWrite
- Success response: object

GET `/api/v1/brokers/{id}`

Returns a single broker by id. Responds 404 when it does not exist. Requires the brokers:read scope.

- Authentication: Bearer; scope brokers:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/brokers/{id}`

Partially updates a broker. Editable by the creator or an admin; otherwise responds 404. Requires the brokers:write scope.

- Authentication: Bearer; scope brokers:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: BrokerUpdate
- Success response: object

DELETE `/api/v1/brokers/{id}`

Deletes a broker. Editable by the creator or an admin; otherwise responds 404. Requires the brokers:write scope.

- Authentication: Bearer; scope brokers:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey

GET `/api/v1/brokerages`

Returns all brokerages (firms), newest first. Cursor-paginated. Brokerages are firm-wide visible. Requires the brokers:read scope.

- Authentication: Bearer; scope brokers:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of brokerages to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/brokerages`

Creates a brokerage (firm) owned by the token's user. Requires the brokers:write scope.

- Authentication: Bearer; scope brokers:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: BrokerageWrite
- Success response: object

GET `/api/v1/brokerages/{id}`

Returns a single brokerage by id. Responds 404 when it does not exist. Requires the brokers:read scope.

- Authentication: Bearer; scope brokers:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/brokerages/{id}`

Partially updates a brokerage. Editable by the creator or an admin; otherwise responds 404. Requires the brokers:write scope.

- Authentication: Bearer; scope brokers:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: BrokerageUpdate
- Success response: object

DELETE `/api/v1/brokerages/{id}`

Deletes a brokerage. Editable by the creator or an admin; otherwise responds 404. Requires the brokers:write scope.

- Authentication: Bearer; scope brokers:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey

GET `/api/v1/actions`

Returns universal actions (tasks) visible to the token's owning user, newest first. Cursor-paginated. Requires the actions:read scope. Visibility follows the in-app rules; linked targets the token cannot access are stripped from each row.

Optional filters compose with pagination and never widen visibility: status, triage, dueBefore/dueAfter (ISO 8601; match actions with a due date in that window), and targetType/targetId (return only actions linked to a matching record). An unknown enum value or malformed date returns 400 invalid_filter.

Every action carries a triage state layered over source. System-generated actions (Listings Intelligence research and verify-listing-status actions, listing outreach milestones) start as suggested and only become the broker's own work once added in the app (accepted); a dismissed suggestion is dismissed with status canceled and is never regenerated. Broker-created actions are always accepted. Without a triage filter the list keeps returning every visible action regardless of triage state, so existing integrations see no change; pass triage=accepted to read only committed work.

- Authentication: Bearer; scope actions:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of actions to return (1–100).
- cursor (query; string)
- status (query; string) — Filter to actions with this status.
- triage (query; string) — Filter by triage state. accepted returns committed work (broker-created actions and added suggestions), suggested the pending Suggested tray, dismissed suggestions the broker sent away. Omit to return all states.
- dueBefore (query; string) — Only actions with a due date at or before this instant (ISO 8601). Actions with no due date are excluded.
- dueAfter (query; string) — Only actions with a due date at or after this instant (ISO 8601). Actions with no due date are excluded.
- targetType (query; string) — Only actions linked to a target of this type.
- targetId (query; string) — Only actions linked to the record with this id (combine with targetType to scope to a specific record type).
- Success response: object

POST `/api/v1/actions`

Creates an action with one or more linked targets. Requires the actions:write scope plus access to every target referenced (prospect access / contact-of-prospect / readable deal, listing, or landlord), else 403. Emits action.created.

- Authentication: Bearer; scope actions:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: ActionCreate
- Success response: object

GET `/api/v1/actions/{id}`

Returns a single action by id. Responds 404 (not 403) when it does not exist OR is not visible to the token. Requires the actions:read scope.

- Authentication: Bearer; scope actions:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/actions/{id}`

Updates an existing action. Requires the actions:write scope and the same edit rights as the in-app app (creator, assignee, owner, or admin). 404 when not visible. Emits action.updated.

- Authentication: Bearer; scope actions:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: ActionUpdate
- Success response: object

DELETE `/api/v1/actions/{id}`

Deletes an action. Requires the actions:write scope; only the creator or an admin may delete (else 403). 404 when missing. Emits action.deleted.

- Authentication: Bearer; scope actions:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/campaigns`

Returns firm-wide marketing campaign email templates, newest first. Cursor-paginated. Requires the campaigns:read scope.

- Authentication: Bearer; scope campaigns:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of templates to return (1–100).
- cursor (query; string)
- Success response: object

POST `/api/v1/campaigns`

Creates a marketing campaign email template. Requires the campaigns:write scope (NOT admin-gated). Emits campaign.created. This never sends email — it only stores a reusable template.

- Authentication: Bearer; scope campaigns:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: CampaignTemplateCreate
- Success response: object

GET `/api/v1/campaigns/{id}`

Returns a single campaign template by id. Requires the campaigns:read scope. 404 when missing.

- Authentication: Bearer; scope campaigns:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/campaigns/{id}`

Updates a campaign template. Requires the campaigns:write scope. 404 when missing. Emits campaign.updated.

- Authentication: Bearer; scope campaigns:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: CampaignTemplateUpdate
- Success response: object

DELETE `/api/v1/campaigns/{id}`

Deletes a campaign template. Requires the campaigns:write scope. 404 when missing. Emits campaign.deleted.

- Authentication: Bearer; scope campaigns:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/campaign-sends`

Returns read-only marketing campaign send history (one row per blast) with engagement rollups, newest first. Cursor-paginated. Requires the campaigns:read scope. There is no endpoint to trigger a send.

- Authentication: Bearer; scope campaigns:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of sends to return (1–100).
- cursor (query; string)
- Success response: object

GET `/api/v1/campaign-sends/{id}`

Returns a single campaign send by id, including per-recipient delivery rows. Requires the campaigns:read scope. 404 when missing.

- Authentication: Bearer; scope campaigns:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

GET `/api/v1/entities`

Returns landlord-directory entities, newest first. Cursor-paginated. The directory is firm-wide, so any token with entities:read sees every (non-merged) entity. Aliases are omitted from the list — fetch a single entity to get them.

- Authentication: Bearer; scope entities:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of entities to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/entities`

Creates a new landlord-directory entity from a name (canonical + contact aliases are seeded automatically). Requires the entities:write scope. Emits entity.created.

- Authentication: Bearer; scope entities:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: EntityCreate
- Success response: object

GET `/api/v1/entities/{id}`

Returns a single entity by id, including its aliases. Responds 404 when it does not exist. Requires the entities:read scope.

- Authentication: Bearer; scope entities:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/entities/{id}`

Updates editable fields on an entity. Requires the entities:write scope and edit rights (admin, creator, or no recorded creator) — otherwise 404. Emits entity.updated.

- Authentication: Bearer; scope entities:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: EntityUpdate
- Success response: object

POST `/api/v1/entities/{id}/aliases`

Adds a manual alias (alternate name) to an entity. Requires entities:write and edit rights. Returns the updated entity with its alias list. Emits entity.updated.

- Authentication: Bearer; scope entities:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: object
- Success response: object

POST `/api/v1/entities/{id}/aliases/{aliasId}/verify`

Marks an alias as verified. Requires entities:write and edit rights. Emits entity.updated.

- Authentication: Bearer; scope entities:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- aliasId (path; string), required
- IdempotencyKey
- Success response: object

DELETE `/api/v1/entities/{id}/aliases/{aliasId}`

Removes an alias from an entity. Requires entities:write and edit rights. Emits entity.updated.

- Authentication: Bearer; scope entities:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- aliasId (path; string), required
- IdempotencyKey
- Success response: object

GET `/api/v1/agreements`

Returns agreements created by the token's owning user (admins see all), newest first. Cursor-paginated. Requires the agreements:read scope. Recipients are status-only (no sign tokens, signatures, or IPs).

- Authentication: Bearer; scope agreements:read
- Idempotency: Not applicable.
- Parameters:
- limit (query; integer) — Maximum number of agreements to return (1–100).
- cursor (query; string) — Opaque pagination cursor from a previous response's nextCursor.
- Success response: object

POST `/api/v1/agreements`

Creates a draft agreement from a template. Field values are seeded from the template and merged with any provided values; numeric bounds are enforced. Recipients' isSigner is derived server-side from the role. Requires agreements:write. Emits agreement.created.

- Authentication: Bearer; scope agreements:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- IdempotencyKey
- JSON request: AgreementCreate
- Success response: object

GET `/api/v1/agreements/{id}`

Returns a single agreement by id with its recipients. Responds 404 when it does not exist OR is not visible to the token. Requires the agreements:read scope.

- Authentication: Bearer; scope agreements:read
- Idempotency: Not applicable.
- Parameters:
- id (path; string), required
- Success response: object

PATCH `/api/v1/agreements/{id}`

Updates a draft agreement (values, recipients, links, cover note, signing/negotiation mode). Requires agreements:write and edit rights (admin or creator) — otherwise 404. Returns 409 if the agreement is no longer a draft or is already linked elsewhere. Emits agreement.updated.

- Authentication: Bearer; scope agreements:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: AgreementUpdate
- Success response: object

DELETE `/api/v1/agreements/{id}`

Deletes a draft agreement. Requires agreements:write and edit rights (admin or creator) — otherwise 404. Returns 409 if the agreement is no longer a draft (sent agreements must be voided in-app). Emits agreement.deleted.

- Authentication: Bearer; scope agreements:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

POST `/api/v1/agreements/{id}/send`

Transitions a draft agreement to sent and emails its recipients, driving the same in-app state machine and side effects. Requires agreements:write and edit rights (admin or creator) — otherwise 404. Returns 409 when the agreement is not a draft, or 400 when it has no signer recipients. Emits agreement.sent. Idempotent via the Idempotency-Key header.

- Authentication: Bearer; scope agreements:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

POST `/api/v1/agreements/{id}/void`

Voids an agreement (any state except completed), reusing the in-app state machine. Requires agreements:write and edit rights (admin or creator) — otherwise 404. Returns 409 when the agreement is already completed or already voided. Emits agreement.voided. Idempotent via the Idempotency-Key header.

- Authentication: Bearer; scope agreements:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- Success response: object

POST `/api/v1/agreements/{id}/counter-sign`

Applies the EXR counter-signature to a signed agreement, transitioning it to completed and triggering the fully-executed emails, via the in-app state machine. Counter-signing is admin only — a non-admin token that can see the agreement receives 403 (not 404). Requires agreements:write. Returns 409 when the agreement is not awaiting counter-signature, including when requiresCounterSign is false — such agreements complete automatically on the final signature (agreement.signed then agreement.completed fire back-to-back), so there is nothing to counter-sign. Emits agreement.completed. Idempotent via the Idempotency-Key header.

- Authentication: Bearer; scope agreements:write
- Idempotency: Optional Idempotency-Key supported.
- Parameters:
- id (path; string), required
- IdempotencyKey
- JSON request: AgreementCounterSign
- Success response: object

Scopes

Read and write scopes are independent.

• deals:read — Read deal records (financial fields require deals:financials:read).
• deals:financials:read — Include deal commission, split, lease-term, and payment financials.
• deals:write — Create, update, and delete deal records the token's account may edit.
• tenants:read — Read Commercial Tenant records visible to the token.
• tenants:write — Create, update, and delete Commercial Tenant records the token may edit.
• prospects:read — Read prospect records visible to the token.
• prospects:write — Create, update, and delete prospect records the token may access.
• clients:read — Read CRM client records visible to the token.
• clients:write — Create, update, and delete CRM client records the token may access.
• workspaces:read — Read workspace (leasing brochure) records visible to the token.
• workspaces:write — Create, update, and delete workspace records the token may edit.
• brokers:read — Read broker and brokerage records (firm-wide visible).
• brokers:write — Create, update, and delete broker and brokerage records the token may edit.
• actions:read — Read universal actions (tasks) visible to the token.
• actions:write — Create, update, and delete actions the token may edit.
• campaigns:read — Read marketing campaign templates and read-only send history.
• campaigns:write — Create, update, and delete campaign templates; never trigger a send.
• entities:read — Read landlord/entity directory records (firm-wide).
• entities:write — Create and update entities and manage their aliases.
• agreements:read — Read agreements visible to the creator or an admin.
• agreements:write — Create and edit drafts and invoke supported agreement lifecycle transitions.

Pagination

List endpoints accept ?limit=<1..100>&cursor=<opaque>. Responses use { data, nextCursor, hasMore }; return nextCursor unchanged as the next cursor until hasMore is false.

Idempotency

Every POST, PATCH, and DELETE accepts an optional Idempotency-Key. Without it, the request has no replay protection. For the same token, method, concrete path, and canonical JSON body, a retry replays the first response, including 4xx or 5xx. Matching concurrent calls do not execute the mutation twice. Retry 409 idempotency_request_in_progress later with the same key; changed reuse returns 409 idempotency_key_conflict. Pending reservations are never automatically reclaimed.

Error envelope

{ "error": { "code", "message", "details?" } } — details can hold machine-readable field validation errors.

Webhooks

Supported events (36):

• deal.created
• deal.updated
• deal.deleted
• tenant.created
• tenant.updated
• tenant.deleted
• prospect.created
• prospect.updated
• prospect.deleted
• client.created
• client.updated
• client.deleted
• workspace.created
• workspace.updated
• workspace.deleted
• action.created
• action.updated
• action.deleted
• campaign.created
• campaign.updated
• campaign.deleted
• broker.created
• broker.updated
• broker.deleted
• brokerage.created
• brokerage.updated
• brokerage.deleted
• entity.created
• entity.updated
• agreement.created
• agreement.updated
• agreement.deleted
• agreement.sent
• agreement.signed
• agreement.completed
• agreement.voided

• Entities emit entity.created and entity.updated only; merge/dedupe is in-app and there is no entity.deleted event.
• Deal, tenant, prospect, workspace, and agreement CRUD events may originate from in-app or public API writes.
• Broker, brokerage, action, campaign, entity, and client events currently originate only from public API writes.
• Agreement sent, signed, completed, and voided events originate in the shared state machine and may be triggered in-app or through the public API.

Envelope

{ "id": "…", "type": "deal.created", "createdAt": "…", "apiVersion": "v1", "data": { "deal": { "…": "…" } } }

Delivery is attempted 4 times (immediate → +30 s → +2 min → +10 min), with a 10-second timeout per attempt. Any HTTP 2xx response acknowledges a delivery.

Signature verification

signedPayload = <t>.<rawBody>
v1            = HMAC-SHA256(signing_secret, signedPayload)  // hex
header        = X-EXR-Signature: t=<unix-ts>,v1=<hex>

Reject stale timestamps and compare the signature with a timing-safe comparison. Never put signing secrets in source control or browser code.

Request and response schemas

`WebhookDeletedResource`

`Error`

`Deal`

`DealCreate`

Body for creating a deal. Mirrors the read shape but omits server-managed fields. Money values are strings of integer cents.

`DealUpdate`

Body for a partial deal update. Every field is optional; only the fields you send change. Commission splits are set via the splits block.

`DealFinancialsWrite`

Writable financial fields. Money is a string of integer cents.

`DealLeaseTermsYear`

One lease-year row of the commission calculator. Rates are basis points (10000 = 100%, e.g. 300 = 3%); money is integer cents. Each row must be a JSON object; on write, every documented key present must already satisfy the range and precision stated in its description or the request is rejected with 400 invalid_body naming financials.leaseTerms.years[<index>].<key>. Unknown row keys pass through unchanged.

`DealLeaseTerms`

The deal's lease commission calculator terms: a per-year rent schedule where each year has its own escalation, free rent, excluded charges, and commission rate. Conventions: all money fields are integer CENTS; all rates are BASIS POINTS (10000 = 100%, e.g. 300 = 3%) and the commission, referral, and co-brokerage rates may carry one decimal place (312.5 = 3.125%); dates are ISO YYYY-MM-DD strings (empty string when not entered). Commission is charged on net rent (base rent minus free rent minus excluded charges, floored at 0) by default, or on base rent when commissionBasis is base_rent. Writes are validated, never normalized: each documented key you send must already meet the range, precision, and type stated in its description (money as JSON numbers of non-negative integer cents, rates inside their basis-point ranges, the listed enum values, whole-month termMonths from 1 to 720 consistent with the row count, at most 60 years[] rows), otherwise the request is rejected with 400 invalid_body naming the key. Reads echo the stored object as written. Reading this field requires the deals:financials:read scope.

`DealLeaseSchedule`

Read-only, server-computed per-year schedule returned as financials.leaseSchedule on every deal read, write echo, and deal.created / deal.updated webhook payload. It is the exact row-by-row output of the lease commission calculator for the deal's leaseTerms (the same engine that produces grossCommissionCents), so a consumer can display or store the schedule without re-deriving the math: escalation chaining, partial-year proration, free-rent valuation, the excluded-charges deduction, and every rounding point are already applied. Money fields are integer cents rendered as strings; rates are basis points (10000 = 100%); free-rent quantities are numbers. freeRentMode, freeRentUnit, commissionBasis, commissionCalc, and fixedMode are the normalized modes the calculator actually applied, so legacy or invalid leaseTerms values already show their documented fallback here. grossCommissionCents is the schedule's commission total: it equals the sum of rows[].commissionCents (reported as totals.commissionCents) when commissionCalc is sliding or fixedMode is percent. When commissionCalc is fixed with fixedMode months or amount there is no per-year commission: every row's commissionBps and commissionCents are 0, totals.commissionCents is "0", and only grossCommissionCents carries the flat figure. Referral, co-brokerage, and GCI are not part of the schedule; read them from the financials summary. Never write this object back: it is derived from leaseTerms and is not accepted by POST or PATCH. Requires the deals:financials:read scope.

`DealLeaseScheduleRow`

One lease year of DealLeaseSchedule.rows. Every amount is for the months this row covers, so a prorated partial final year carries prorated amounts; the *Annual* names follow the calculator's column names. Money is integer cents as strings; rates are basis points.

`DealLeaseScheduleTotals`

Column totals of DealLeaseSchedule.rows. Money is integer cents as strings.

`DealCommissionSchedule`

Agreement-style commission schedule. A tagged union on mode: sliding (per-year-bracket rates), fixed (one flat commission), or custom (free-form text). Percent values here are STRINGS as entered (e.g. "5" = 5%) — unlike the lease-terms blob, which uses basis points. Reading requires the deals:financials:read scope.

`DealCommissionSlidingRow`

One sliding-schedule bracket: a commission rate covering lease years fromYear–toYear inclusive.

`DealPaymentSchedule`

When the commission is paid. A tagged union on mode: structured (ordered milestone rows whose percents should sum to 100) or custom (free-form text). Legacy values shaped as {rows:[…]} with no mode are read as structured. Reading requires the deals:financials:read scope.

`DealPaymentScheduleRow`

One payment milestone.

`Tenant`

`TenantWrite`

Writable tenant fields. name is required on create. The creator (userId) is set from the token and cannot be supplied.

`DeleteResult`

`Prospect`

`ProspectWrite`

Writable prospect fields. propertyAddress is required on create. The owner (userId) is set from the token. existingAssetClass is a configurable stable string value; unknown or retired values are rejected, while historical stored values remain readable.

`Client`

A CRM client (internally crm_clients). Private to its owner, creator, collaborators, and admins.

`ClientWrite`

Writable fields for a client on create (POST). userId (creator) is server-managed and ignored if sent. name, clientType, and entityType are required. ownerUserId (sent as clientOwnerId) defaults to the creator when omitted and must reference an existing user (else 400 invalid_reference).

`ClientUpdate`

Partial update for a client (PATCH). Same writable fields as ClientWrite, but every field is optional — send only the subset you want to change. Only the current owner or an admin may change clientOwnerId (else 403).

`Workspace`

A leasing brochure (internally leasing_listings).

`WorkspaceWrite`

Writable workspace (leasing brochure) fields. title and addressLine1 are required on create; the owner is set from the token. The address key, share tokens, the linked imported-listing id, and the PLUTO-sync timestamp are server-managed and cannot be set through the API. Monetary fields are integer cents.

`Broker`

A commercial broker (internally brokers).

`BrokerWrite`

Writable fields for a broker on create (POST). userId and linkedImportedBrokerId are server-managed and ignored (stripped) if sent. name is required.

`BrokerUpdate`

Partial update for a broker (PATCH). Same writable fields as BrokerWrite, but every field is optional — send only the subset you want to change. Server-managed fields are ignored (stripped) if sent.

`Brokerage`

A brokerage firm (internally brokerages).

`BrokerageWrite`

Writable fields for a brokerage on create (POST). userId and linkedImportedBrokerageId are server-managed and ignored (stripped) if sent. name is required.

`BrokerageUpdate`

Partial update for a brokerage (PATCH). Same writable fields as BrokerageWrite, but every field is optional — send only the subset you want to change. Server-managed fields are ignored (stripped) if sent.

`ActionTarget`

A record this action is linked to. Targets the token cannot access are stripped from the response.

`Action`

`ActionCreate`

`ActionUpdate`

All fields optional; only provided fields are changed. Setting status to completed records the completer + completion time.

`CampaignTemplate`

A reusable marketing campaign email template. Storing one never sends email.

`CampaignTemplateCreate`

`CampaignTemplateUpdate`

All fields optional; only provided fields are changed.

`CampaignSendRecipient`

`CampaignSend`

Read-only record of a marketing campaign blast with engagement rollups.

`EntityAlias`

An alternate name (spelling/variant) on file for an entity.

`Entity`

A landlord-directory entity (ownership group, owner, manager, brokerage, person, etc.).

`EntityCreate`

`EntityUpdate`

All fields optional; only provided fields are changed. Send null to clear a nullable field.

`AgreementRecipient`

A recipient on an agreement. Status-only — never includes sign tokens, signature images, IPs, or user agents.

`Agreement`

`AgreementRecipientInput`

`AgreementCreate`

`AgreementUpdate`

Draft-only. All fields optional; only provided fields change. A provided recipients array fully replaces the list.

`AgreementCounterSign`

The EXR counter-signature applied to a fully-signed agreement.