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 ofdraft,sent,awaiting_payment,completedandexpired.expiredmatches the sent documents whose deadline has passed, andsentleaves them out. -
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]andfilter[created_to]— a window over the day each document was created, in UTC likecreated_at. Both bounds are inclusive, and either works alone. -
filter[expires_from]andfilter[expires_to]— a window over the last day to sign, in your account's timezone likeexpires_at. Both bounds are inclusive, and either works alone. A document without a deadline never matches; addfilter[status]=sentto keep the ones still open for signing.
A document has to match every filter you pass. A filter given several values matches a document carrying any one of them.
Query Parameters
- Type: integerpage[number]min:1
Page to return, starting at 1.
- Type: integerpage[size]min:1max:100
Records per page. Defaults to 25; anything above 100 is reduced to 100.
- Type: stringfilter[status]default
One or more statuses, comma-separated or repeated:
draft,sent,awaiting_payment,completed,expired. - Type: stringfilter[company
_id] defaultOne or more client company ids, comma-separated or repeated. Returns the documents a recipient represents one of those companies on.
- Type: stringfilter[contact
_id] defaultOne or more contact ids, comma-separated or repeated. Returns the documents one of those contacts is a recipient on.
- Type: stringfilter[project
_id] defaultOne 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.
- Type: stringfilter[deal
_id] defaultOne or more deal ids, comma-separated or repeated. Returns the documents linked to one of those deals.
- Type: stringFormat: datefilter[created
_from] defaultReturn documents created on or after this day, in UTC.
- Type: stringFormat: datefilter[created
_to] defaultReturn documents created on or before this day, in UTC.
- Type: stringFormat: datefilter[expires
_from] defaultReturn documents whose last day to sign is on or after this day, in your account's timezone.
- Type: stringFormat: datefilter[expires
_to] defaultReturn documents whose last day to sign is on or before this day, in your account's timezone.
Responses
- application/json
- application/json
- application/json
- application/json
- application/json
curl 'https://app.hellobonsai.com/public-api/v1/docs?filter%5Bstatus%5D=draft&filter%5Bcompany_id%5D=42&filter%5Bcontact_id%5D=7&filter%5Bproject_id%5D=1203&filter%5Bdeal_id%5D=918&filter%5Bcreated_from%5D=2026-05-01&filter%5Bcreated_to%5D=2026-05-31&filter%5Bexpires_from%5D=2026-05-01&filter%5Bexpires_to%5D=2026-05-31' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"data": [
{
"id": 5120,
"title": "Web Design Proposal - Acme Corp",
"doc_number": "DOC-42",
"deal_id": 918,
"expiration_days": 14,
"expiration_date": "2026-04-28",
"created_at": "2026-04-14T09:12:04.000Z",
"updated_at": "2026-04-14T09:12:04.000Z",
"status": "draft",
"expires_at": "2026-04-28T23:59:59.000-03:00",
"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
}
}
}