Create a document from a template
Creates a draft document from one of your templates. Nothing is sent:
the draft waits in Bonsai for you to review and send it. template_id is
the only required field — there is no blank document.
You are always the sender. Pass contact_id to fill the template's first
receiver role with that contact. Without one, a project_id or deal_id
fills it from that project's or deal's client, the way the app does, and
company_id alone fills it with the company's primary contact. The
response lists the roles still waiting for somebody in unassigned_roles,
so you can tell the user what is left to fill in Bonsai, and returns the
pricing table the draft took from the template in pricing_table.
company_id, contact_id, project_id and deal_id must all point at
the same client company. The document's client comes from company_id,
else the project's client, else the deal's. Every other field that names a
different company gets its own invalid_value error, and its message says
which field set the client.
Variables fill in the way they do in the app: the document's own (such as its creation date) straight away, the receiver's once a contact fills the role.
The ids this endpoint takes come from other endpoints:
GET /public-api/v1/templates?filter[type]=Doc for template_id,
GET /public-api/v1/companies for company_id,
GET /public-api/v1/contacts for contact_id,
GET /public-api/v1/projects for project_id, and
GET /public-api/v1/deals for deal_id.
Body
Document attributes, wrapped in a doc key.
- Properties: 6Type: objectdocrequired
Responses
- application/json
- application/json
- application/json
- application/json
- application/json
- application/json
curl https://app.hellobonsai.com/public-api/v1/docs \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"doc": {
"template_id": "3f2a91c4-6b0e-4d5a-9c88-2e7f13ab4d60",
"title": "Web Design Proposal - Acme Corp",
"contact_id": 7,
"company_id": 42,
"project_id": 1203,
"deal_id": 918
}
}'
{
"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",
"pricing_table": {
"currency": "USD",
"package_selection": "multiple",
"packages": [
{
"id": "V1StGXR8Z5jdHi6BmyTq2",
"title": "Website",
"description": "Design and build",
"optional": false,
"includes_tax": false,
"unit": "flat",
"total": "7800.0",
"rows": [
{
"id": "Uakgb4Jk0sQ3dTz9mPw7x",
"name": "Development",
"description": "Frontend and CMS",
"rate": "120.0",
"quantity": "40.0",
"unit": "per_hour",
"optional": false,
"tax_rate_ids": [],
"total": "4800.0",
"tax_total": "0.0"
}
]
}
],
"subtotal": "7800.0",
"tax_total": "0.0",
"total": "7800.0"
}
},
"meta": {
"request_id": "b1f0d2c4-7a9e-4c3b-8d5f-1e2a3b4c5d6e"
}
}