# Documents API

> Documents in the Broker & Agent API: list documents; get a document's facts; download a document's file.

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 documents](#list-documents): `GET /documents`
- [Get a document's facts](#get-a-document-s-facts): `GET /documents/{id}`
- [Download a document's file](#download-a-document-s-file): `GET /documents/{id}/file`

## List documents

`GET /documents`

The documents the credential's person can see, newest first: a deal's follow the deal, a contact's follow the contact.

Scope: `crm.read`

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `contactId` | query | string or null | Only this contact's documents. Cut to 64 characters. |
| `transactionId` | query | string or null | Only this deal's documents. Cut to 64 characters. |
| `kind` | query | `contract`, `disclosure`, `inspection`, `pre-approval`, `addendum`, `policy`, `form-template`, `filled-form`, `site`, `other` |  |
| `q` | query | string or null | Name contains, any case. Cut to 200 characters. |
| `limit` | query | integer | How many to answer with, 1 to 100. Default `25`. |
| `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/documents \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | A page of documents. | { `documents`: array of [Document](https://brokerandagent.com/developers/api/reference/objects#document), `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). |  |

## Get a document's facts

`GET /documents/{id}`

Scope: `crm.read`

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `id` (required) | path | string |  |

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

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The document. | { `document`: [Document](https://brokerandagent.com/developers/api/reference/objects#document) } |
| `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). |  |

## Download a document's file

`GET /documents/{id}/file`

Always an attachment, in the file's own type (Content-Type). 404 when the document has no file stored.

Scope: `crm.read`

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `id` (required) | path | string |  |

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

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The file. |  |
| `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). |  |

---

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