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

required
application/json

Document attributes, wrapped in a doc key.

  • Properties: 6

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/public-api/v1/docs
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"
  }
}