---
title: "Create a note"
method: POST
path: "/v1/notes"
tags: ["Notes"]
---

# Create a note

`POST /v1/notes`

Creates a new note associated with a specific entity (required scope notes:write)

## Headers

- `Customer-Id` integer, required

## Request body

- CreateNoteModel — Create note model
  - `entityType` 'contact' | 'job' | 'stockItem' | 'resource' | 'vehicle' | 'salesOpportunity' | 'contract', required — The type of entity that the note is associated to<p>Possible values:</p><ul><li><b>contact</b>: Associated with a contact entity</li><li><b>job</b>: Associated with a job entity</li><li><b>stockItem</b>: Associated with a stock item entity</li><li><b>resource</b>: Associated with a resource entity</li><li><b>vehicle</b>: Associated with a vehicle entity</li><li><b>salesOpportunity</b>: Associated with a sales opportunity entity</li><li><b>contract</b>: Associated with a contract entity</li></ul>
  - `entityId` integer, required — The unique identifier of the associated entity that owns the note, relative to the `entityType`
  - `typeId` integer, required — The unique identifier of the note type definition associated to this note
  - `subject` string, required — The subject of the note
  - `ownedByUserId` integer, nullable — The unique id of the user who owns the note. Must have an active licence. If not provided, this will be set to the default user in the note type or the user ID of the API request
  - `parentId` integer, nullable — The unique identifier of the parent note of this note
  - `dueAt` string, date-time, nullable — The UTC timestamp of when this note is due for completion
  - `reference` string, nullable — The internal reference of the note - should usually be unique. If not provided, this will be auto-generated
  - `status` 'open' | 'completed' | 'cancelled' — The status of the note<p>Possible values:</p><ul><li><b>open</b>: Open</li><li><b>completed</b>: Completed</li><li><b>cancelled</b>: Cancelled</li></ul>
  - `completionText` string, nullable — The completion text for the note
  - `description` string, nullable — The detailed textual content about the note
  - `customFields` CustomFieldWriteModel[], nullable — Custom fields associated with the note
    - `definitionId` integer, required — The unique identifier of the associated custom field definition
    - `value` string, nullable — The value of this custom field. If set to null, any existing value will be unset

## Response `201`

Created

- PostResponseInt64 — Represents a response for a POST request, containing the ID of the newly created record
  - `id` integer — Identifier of the newly created record

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `422` — Unprocessable Content
- `500` — Internal Server Error

---

[API](https://skmtc.net/bigchange/apis/bigchange-dx.md) · [All operations](https://skmtc.net/bigchange/apis/bigchange-dx/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bigchange/bigchange-dx/revisions/916e669fc527/schema)