Transactions API
Transactions in the Broker & Agent API: list deals; open a deal; get a deal; change or
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- List deals:
GET /transactions - Open a deal:
POST /transactions - Get a deal:
GET /transactions/{id} - Change or move a deal:
PATCH /transactions/{id}
List deals#
GET /transactions
Every deal the credential can see, closed ones included, closing soonest first. Pass limit to page; without it the answer
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
limit |
query | integer | How many to answer with, 1 to 200; without it, all of them. |
cursor |
query | string or null | The nextCursor of the page before; absent for the first page. Cut to 200 characters. |
curl https://workspace.brokerandagent.com/api/public/v1/transactions \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
Deals. | { transactions: array of Transaction, nextCursor: string or null } |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Open a deal#
POST /transactions
Refused with 422 when closing comes before the contract, or the client already has an open deal
Scope: crm.write · Role:
Body
| Field | Type | |
|---|---|---|
contactId (required) |
string | Cut to 64 characters. |
property (required) |
string | Cut to 300 characters. |
side (required) |
buyer, seller |
|
price |
number | |
contractDate |
string | |
closingDate |
string |
curl -X POST https://workspace.brokerandagent.com/api/public/v1/transactions \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"contactId":"ct_…","property":"41 Oak St","side":"buyer"}'Responses
| Status | Returns | |
|---|---|---|
201 |
The deal. | { transaction: Transaction } |
400 |
The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). | |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
409 |
A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress). | |
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Get a deal#
GET /transactions/{id}
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
curl https://workspace.brokerandagent.com/api/public/v1/transactions/ID \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
The deal. | { transaction: Transaction } |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Change or move a deal#
PATCH /transactions/{id}
Closing a deal runs the same automatic, undoable close as the app; moving it back out of Closed undoes it. Only the deal’s agent, whoever supervises them, a coordinator or
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
property |
string | Cut to 300 characters. |
side |
buyer, seller |
|
price |
number or null | |
contractDate |
string or null | |
closingDate |
string or null | |
status |
active, pending-close, closed, fell-through |
|
customStage |
string or null |
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/transactions/ID \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"property":"41 Oak St","side":"buyer"}'Responses
| Status | Returns | |
|---|---|---|
200 |
The deal as it now stands. | { transaction: Transaction or null } |
400 |
The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). | |
401 |
No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). | |
403 |
The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience). |
|
404 |
No such record, or one the credential’s person can’t see (not_found). | |
422 |
A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Something missing or wrong? Email support@brokerandagent.com and