> Calendly developer docs. For page Markdown, append .md to any URL.
> Index: https://developer.calendly.com/llms.txt
> API catalog: https://developer.calendly.com/.well-known/api-catalog
> OpenAPI: https://developer.calendly.com/openapi/calendly-api.yaml
> OAuth authorization server: https://calendly.com/.well-known/oauth-authorization-server
> MCP protected resource: https://mcp.calendly.com/.well-known/oauth-protected-resource
> Scheduling MCP endpoint: https://mcp.calendly.com
> Docs search MCP: https://developer.calendly.com/_mcp/server

# Create Note

POST https://api.calendly.com/notes
Content-Type: application/json

Creates a note about one contact. The authenticated user owns the note. Send a `title`, a `body`, or both. First, leading and trailing whitespace is removed from `title` and `body`. After that, at least one of them must contain a character, and the length limits apply. The maximum length of `title` is 255 characters. Some emoji and other symbols count as 2. The maximum length of `body` is 10,000 characters.

To add a reminder, send `remind_at` as an RFC 3339 date-time with seconds, an uppercase `T`, and `Z` or a `±hh:mm` offset, such as `2026-11-01T13:00:00Z`. The year must be from 1970 to 9999. The reminder is saved at that exact time. If reminders are not available on the account, the request returns 403 and no note is created.

Creating a note is not idempotent: each call creates a new note. A request that fails or times out can still create the note. Before you retry, use List Notes with the contact to check.

**Note:** Requires the Contacts API on your plan.

> `contacts:write`

Reference: https://developer.calendly.com/api-docs/calendly-api/contacts/create-note

## Authentication

- `Authorization` header (bearer token, required) — OAuth 2.0
- `Authorization` header (bearer token, required) — Personal Access Token

## Request

### Body (application/json)

This endpoint expects a CreateNoteRequest.

- `contact` (string, required) — The URI of the contact that the note is about.
- `title` (string, optional, nullable) — The title of the note. Leading and trailing whitespace is removed. After that, the maximum length is 255 characters. Some emoji and other symbols count as 2. Omit it, send `null`, or send an empty string for no title.
- `body` (string, optional, nullable) — The plain-text content of the note. Leading and trailing whitespace is removed. After that, the maximum length is 10,000 characters. Omit it, send `null`, or send an empty string for no body.
- `remind_at` (string, optional, nullable) — When the reminder is due, as an RFC 3339 date-time with seconds, an uppercase `T`, and `Z` or a `±hh:mm` offset, in the years 1970 to 9999. Omit it or send `null` for no reminder.

## Response

### 201

Created

- `resource` (Note, required) — A note that a user wrote about a contact. Only the user who owns a note can see it.

## Errors

### 400 Bad Request Error

Request is not valid

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

### 401 Unauthorized Error

Cannot authenticate caller

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

### 403 Forbidden Error

Permission Denied or insufficient scope

- `Create-noteRequestForbiddenError`
  - CreateNoteError: CreateNoteError
  - InsufficientScopeError: InsufficientScopeError

### 429 Too Many Requests Error

Too Many Requests

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

### 500 Internal Server Error

An error has occurred on the server

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

## Types

### Note

A note that a user wrote about a contact. Only the user who owns a note can see it.

- `uri` (string, required) — Canonical reference (unique identifier) for the note.
- `title` (string, required, nullable) — The title of the note. `null` if the note has no title. Maximum 255 characters. Some emoji and other symbols count as 2.
- `body` (string, required, nullable) — The plain-text content of the note. `null` if the note has no body. Maximum 10,000 characters.
- `contact` (string, required, nullable) — The URI of the contact that the note is about. Never `null` when you filter by `contact`. `null` only for a note that has no contact.
- `remind_at` (string, required, nullable) — When the reminder is due. `null` if the note has no reminder.
- `completed_at` (string, required, nullable) — When the reminder was completed. `null` if the reminder is not complete or the note has no reminder.
- `created_at` (string, required) — When the note was created.
- `updated_at` (string, required) — When the note or its reminder was last changed.

### ErrorResponseDetailsItem

- `message` (string, required)
- `parameter` (string, optional)
- `code` (string, optional)

### CreateNoteError

Permission Denied

- `title` (enum, required)
  - Allowed values: `Permission Denied`
- `message` (enum, required)
  - Allowed values: `Please upgrade to a paid Calendly account.`, `You do not have permission to access this resource.`, `The contact does not exist, or you cannot access it. It may have been merged or deleted. Search for the contact again, then retry.`, `Reminders aren't available on your Calendly account yet. Send the note without remind_at.`

### InsufficientScopeError

Caller does not have required oauth scopes

- `title` (enum, required)
  - Allowed values: `Insufficient scope`
- `message` (enum, required)
  - Allowed values: `This operation requires the scopes listed in the 'required_scopes' array.`
- `required_scopes` (list of string, required)

## Examples

### Created note

**Response**

```json
{
  "resource": {
    "uri": "https://api.calendly.com/notes/NNNNNNNNNNNNNNNN",
    "title": "Follow up",
    "body": "Send the revised proposal after Thursday's call.",
    "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
    "remind_at": "2026-10-02T16:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-09-28T16:31:00.000Z",
    "updated_at": "2026-09-28T16:31:00.000Z"
  }
}
```

**SDK Code**

```python Created note
import requests

url = "https://api.calendly.com/notes"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Created note
const url = 'https://api.calendly.com/notes';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Created note
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.calendly.com/notes"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Created note
require 'uri'
require 'net/http'

url = URI("https://api.calendly.com/notes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Created note
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.calendly.com/notes")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Created note
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.calendly.com/notes', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Created note
using RestSharp;

var client = new RestClient("https://api.calendly.com/notes");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Created note
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/notes")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Title and body

**Request**

```json
{
  "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
  "title": "Follow up",
  "body": "Send the revised proposal after Thursday's call."
}
```

**Response**

```json
{
  "resource": {
    "uri": "https://api.calendly.com/notes/NNNNNNNNNNNNNNNN",
    "title": "Follow up",
    "body": "Send the revised proposal after Thursday's call.",
    "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
    "remind_at": "2026-10-02T16:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-09-28T16:31:00.000Z",
    "updated_at": "2026-09-28T16:31:00.000Z"
  }
}
```

**SDK Code**

```python Title and body
import requests

url = "https://api.calendly.com/notes"

payload = {
    "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
    "title": "Follow up",
    "body": "Send the revised proposal after Thursday's call."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Title and body
const url = 'https://api.calendly.com/notes';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"contact":"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA","title":"Follow up","body":"Send the revised proposal after Thursday\'s call."}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Title and body
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.calendly.com/notes"

	payload := strings.NewReader("{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"body\": \"Send the revised proposal after Thursday's call.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Title and body
require 'uri'
require 'net/http'

url = URI("https://api.calendly.com/notes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"body\": \"Send the revised proposal after Thursday's call.\"\n}"

response = http.request(request)
puts response.read_body
```

```java Title and body
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.calendly.com/notes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"body\": \"Send the revised proposal after Thursday's call.\"\n}")
  .asString();
```

```php Title and body
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.calendly.com/notes', [
  'body' => '{
  "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
  "title": "Follow up",
  "body": "Send the revised proposal after Thursday\'s call."
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Title and body
using RestSharp;

var client = new RestClient("https://api.calendly.com/notes");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"body\": \"Send the revised proposal after Thursday's call.\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Title and body
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
  "title": "Follow up",
  "body": "Send the revised proposal after Thursday's call."
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/notes")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### With a reminder

**Request**

```json
{
  "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
  "title": "Follow up",
  "remind_at": "2026-10-02T16:00:00Z"
}
```

**Response**

```json
{
  "resource": {
    "uri": "https://api.calendly.com/notes/NNNNNNNNNNNNNNNN",
    "title": "Follow up",
    "body": "Send the revised proposal after Thursday's call.",
    "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
    "remind_at": "2026-10-02T16:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-09-28T16:31:00.000Z",
    "updated_at": "2026-09-28T16:31:00.000Z"
  }
}
```

**SDK Code**

```python With a reminder
import requests

url = "https://api.calendly.com/notes"

payload = {
    "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
    "title": "Follow up",
    "remind_at": "2026-10-02T16:00:00Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript With a reminder
const url = 'https://api.calendly.com/notes';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"contact":"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA","title":"Follow up","remind_at":"2026-10-02T16:00:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go With a reminder
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.calendly.com/notes"

	payload := strings.NewReader("{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"remind_at\": \"2026-10-02T16:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby With a reminder
require 'uri'
require 'net/http'

url = URI("https://api.calendly.com/notes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"remind_at\": \"2026-10-02T16:00:00Z\"\n}"

response = http.request(request)
puts response.read_body
```

```java With a reminder
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.calendly.com/notes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"remind_at\": \"2026-10-02T16:00:00Z\"\n}")
  .asString();
```

```php With a reminder
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.calendly.com/notes', [
  'body' => '{
  "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
  "title": "Follow up",
  "remind_at": "2026-10-02T16:00:00Z"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp With a reminder
using RestSharp;

var client = new RestClient("https://api.calendly.com/notes");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"contact\": \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n  \"title\": \"Follow up\",\n  \"remind_at\": \"2026-10-02T16:00:00Z\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift With a reminder
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "contact": "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
  "title": "Follow up",
  "remind_at": "2026-10-02T16:00:00Z"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/notes")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```