Skip to main content
POST
/
v1
/
notes
Create a note
curl --request POST \
  --url https://api.folk.app/v1/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "entity": {
    "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
  },
  "visibility": "public",
  "content": "This is a note about **John Doe**",
  "parentNote": {
    "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c"
  }
}'
{
  "data": {
    "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc",
    "entity": {
      "id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
      "entityType": "person",
      "fullName": "John Doe"
    },
    "visibility": "public",
    "content": "This is a note about John Doe",
    "author": {
      "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
      "fullName": "John Doe",
      "email": "john.doe@example.com"
    },
    "createdAt": "2021-01-01T00:00:00.000Z",
    "parentNote": {
      "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
      "entity": {
        "id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
        "entityType": "person",
        "fullName": "John Doe"
      },
      "content": "This is a parent note about John Doe",
      "visibility": "public",
      "author": {
        "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
        "fullName": "John Doe",
        "email": "john.doe@example.com"
      },
      "createdAt": "2021-01-01T00:00:00.000Z",
      "deleted": false
    }
  }
}
Create a note linked to a person, company or deal.

​
Visibility

The visibility of the note can be set to public or private.
  • public: The note is visible to all users in the workspace.
  • private: The note is visible only to the current user.

​
Content

The content of the note can be in plain text or in markdown format. We support the full CommonMark basic syntax, including:
  • Headings
  • Bold
  • Italic
  • Lists
  • Links
  • Images
  • Blockquotes
  • Horizontal rules
  • Code

​
Mentions

We also support mentioning workspace members using a simple markdown link to the GET /v1/users/{userId} endpoint. 
[<user_name>](https://api.folk.app/v1/users/<user_id>)
For example, to mention user John Doe with ID usr_6526333c-1502-46e3-aa01-8f6130f69814: 
This is a note mentioning [John Doe](https://api.folk.app/v1/users/usr_6526333c-1502-46e3-aa01-8f6130f69814)
To retrieve the user ID, you can use the GET /v1/users endpoint.
You can use any value as the user name. Our system will always replace it with the real user name of the workspace member mentioned.Providing an invalid link, a wrong user id, or a user id that does not exist will not trigger any error. Always respect the syntax and use ids retrieved from the API to make sure the mention is valid and the workspace member is notified.

​
Attachments

We currently do not support direct attachment upload. However, you can use any bucket storage service to upload files and reference them in the note content using a link, as long as the file is publicly accessible. Example: 
[PDF link](https://my-bucket.s3.eu-west-1.amazonaws.com/my-file.pdf)

Authorizations

​
Authorization
string
header
required

API key for authentication

Body

application/json
​
entity
object
required

The entity connected to the note. You can link people, companies and deals.

Example:
{
  "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
}
​
visibility
enum<string>
required

The visibility of the note.

  • public: The note is visible to all users in the workspace.
  • private: The note is visible only to the current user.
Available options:
public,
private
​
content
string
required

The content of the note. Can be in plain text or in markdown format.

Required string length: 1 - 100000
Example:

"This is a note about **John Doe**"

​
parentNote
object

The parent note, if this note is a reply to another note.

Example:
{
  "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c"
}

Response

The note created in the workspace.

​
data
object
required

A note linked to an entity.

Example:
{
  "id": "nte_91118b73-5a75-480b-b8e3-a33671c35cdc",
  "entity": {
    "id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
    "entityType": "person",
    "fullName": "John Doe"
  },
  "visibility": "public",
  "content": "This is a note about John Doe",
  "author": {
    "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
    "fullName": "John Doe",
    "email": "john.doe@example.com"
  },
  "createdAt": "2021-01-01T00:00:00.000Z",
  "parentNote": {
    "id": "nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
    "entity": {
      "id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
      "entityType": "person",
      "fullName": "John Doe"
    },
    "content": "This is a parent note about John Doe",
    "visibility": "public",
    "author": {
      "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
      "fullName": "John Doe",
      "email": "john.doe@example.com"
    },
    "createdAt": "2021-01-01T00:00:00.000Z",
    "deleted": false
  }
}
​
deprecations
string[]
Example:
["This field is deprecated"]