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.

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.

  • doc
    Type: object
    required
    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,
    "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"
  }
}

The draft was created.