List documents

​

Lists your documents, newest first, a page at a time. Templates are not documents and never appear here; find them with GET /public-api/v1/templates?filter[type]=Doc.

Each document comes back exactly as POST /public-api/v1/docs returns it: its status, who is seated on it and how far each of them has got, the roles nobody fills yet, and its link in the app. Signing links are never included.

Filtering

  • filter[status] — one or more of draft, sent, completed and expired.
  • filter[company_id] — one or more client company ids. Matches the documents a recipient represents that company on.
  • filter[contact_id] — one or more contact ids. Matches the documents that contact is a recipient on.
  • filter[project_id] — one or more project ids. Only projects your role can see match.
  • filter[deal_id] — one or more deal ids.
  • filter[created_from] and filter[created_to] — a window over the day each document was created, in UTC like created_at. Both bounds are inclusive, and either works alone.

A document has to match every filter you pass. A filter given several values matches a document carrying any one of them.

Query Parameters

  • page[number]
    Type: integer
    min:  
    1

    Page to return, starting at 1.

  • page[size]
    Type: integer
    min:  
    1
    max:  
    100

    Records per page. Defaults to 25; anything above 100 is reduced to 100.

  • filter[status]
    Type: string

    One or more statuses, comma-separated or repeated: draft, sent, completed, expired.

  • filter[company_id]
    Type: string

    One or more client company ids, comma-separated or repeated. Returns the documents a recipient represents one of those companies on.

  • filter[contact_id]
    Type: string

    One or more contact ids, comma-separated or repeated. Returns the documents one of those contacts is a recipient on.

  • filter[project_id]
    Type: string

    One or more project ids, comma-separated or repeated. Returns the documents linked to one of those projects; a project your role cannot see matches nothing.

  • filter[deal_id]
    Type: string

    One or more deal ids, comma-separated or repeated. Returns the documents linked to one of those deals.

  • filter[created_from]
    Type: stringFormat: date

    Return documents created on or after this day, in UTC.

  • filter[created_to]
    Type: stringFormat: date

    Return documents created on or before this day, in UTC.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/public-api/v1/docs
curl 'https://app.hellobonsai.com/public-api/v1/docs?filter[status]=draft&filter[company_id]=42&filter[contact_id]=7&filter[project_id]=1203&filter[deal_id]=918&filter[created_from]=2026-05-01&filter[created_to]=2026-05-31' \
  --globoff \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "id": 5120,
      "title": "Web Design Proposal - Acme Corp",
      "doc_number": "DOC-42",
      "deal_id": 918,
      "created_at": "2026-04-14T09:12:04.000Z",
      "updated_at": "2026-04-14T09:12:04.000Z",
      "status": "draft",
      "project_ids": [
        1203
      ],
      "recipients": [
        {
          "status": "pending",
          "role": {
            "name": "Receiver",
            "kind": "receiver"
          },
          "contact_id": 7,
          "company_member_id": 314,
          "company_id": 42,
          "name": "Jane Cooper",
          "email": "jane@acme.test"
        }
      ],
      "unassigned_roles": [
        {
          "name": "Receiver",
          "kind": "receiver"
        }
      ],
      "url": "https://app.hellobonsai.com/docs/b3c1f0a9d2e4"
    }
  ],
  "meta": {
    "request_id": "b1f0d2c4-7a9e-4c3b-8d5f-1e2a3b4c5d6e",
    "pagination": {
      "page": 1,
      "page_size": 25,
      "has_more": true
    }
  }
}

A page of documents, newest first.