# Transactions API

> Transactions in the Broker & Agent API: list deals; open a deal; get a deal; change or move a deal.

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [List deals](#list-deals): `GET /transactions`
- [Open a deal](#open-a-deal): `POST /transactions`
- [Get a deal](#get-a-deal): `GET /transactions/{id}`
- [Change or move a deal](#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 is every deal.

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. |

```bash
curl https://workspace.brokerandagent.com/api/public/v1/transactions \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | Deals. | { `transactions`: array of [Transaction](https://brokerandagent.com/developers/api/reference/objects#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 for that property.

Scope: `crm.write` · Role: agent or above

**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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
curl https://workspace.brokerandagent.com/api/public/v1/transactions/ID \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The deal. | { `transaction`: [Transaction](https://brokerandagent.com/developers/api/reference/objects#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 an admin may.

Scope: `crm.write` · Role: transaction-coordinator or above

**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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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). |  |

---

Source: https://brokerandagent.com/developers/api/reference/transactions
