> 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

# List Notes

GET https://api.calendly.com/notes

Returns a list of notes for one or more contacts. Notes are private. A user can see only the notes that they wrote. Notes that other users wrote about the same contacts are not returned.

The `contact` parameter is required. A query parameter other than `contact`, `count`, or `page_token` returns 400. The response is one list for all the contacts. Each note shows its contact in the `contact` field.

Notes are sorted by `updated_at`, most recently updated first. Notes with the same `updated_at` are sorted by note ID, so the order is stable. A note that changes while you page moves to the first page, so later pages do not include it. To show reminders by due date, get all the pages, then sort them by `remind_at`.

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

> `contacts:read`

Reference: https://developer.calendly.com/api-docs/calendly-api/contacts/list-notes

## Authentication

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

## Request

### Query parameters

- `contact` (list of string, required) — Returns only notes about these contacts. Use 1 to 10 contact URIs, separated by commas. If the user cannot access one of the contacts, the request returns 403 and no notes.
- `count` (integer, optional, default: 20) — The number of rows to return
- `page_token` (string, optional) — The token to pass to get the next or previous portion of the collection

## Response

### 200

OK

- `collection` (list of Note, required)
- `pagination` (Pagination, required)

## 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

- `List-notesRequestForbiddenError`
  - ListNotesError: ListNotesError
  - 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.

### Pagination

- `count` (integer, required) — The number of rows to return
- `next_page` (string, required, nullable) — URI to return the next page of an ordered list ("null" indicates no additional results are available)
- `previous_page` (string, required, nullable) — URI to return the previous page of an ordered list ("null" indicates no additional results are available)
- `next_page_token` (string, required, nullable) — Token to return the next page of an ordered list ("null" indicates no additional results are available)
- `previous_page_token` (string, required, nullable) — Token to return the previous page of an ordered list ("null" indicates no additional results are available)

### ErrorResponseDetailsItem

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

### ListNotesError

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.`, `One or more contacts do not exist, or you cannot access them. A contact may have been merged or deleted. Search for the contacts again, then retry.`

### 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

**Response**

```json
{
  "collection": [
    {
      "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-25T18:00:00.000Z",
      "updated_at": "2026-09-28T16:32:00.000Z"
    }
  ],
  "pagination": {
    "count": 1,
    "next_page": null,
    "previous_page": null,
    "next_page_token": null,
    "previous_page_token": null
  }
}
```

**SDK Code**

```python Notes for a contact
import requests

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

querystring = {"contact":"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA"}

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

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Notes for a contact
const url = 'https://api.calendly.com/notes?contact=https%3A%2F%2Fapi.calendly.com%2Fcontacts%2FAAAAAAAAAAAAAAAA';
const options = {method: 'GET', 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 Notes for a contact
package main

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

func main() {

	url := "https://api.calendly.com/notes?contact=https%3A%2F%2Fapi.calendly.com%2Fcontacts%2FAAAAAAAAAAAAAAAA"

	req, _ := http.NewRequest("GET", 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 Notes for a contact
require 'uri'
require 'net/http'

url = URI("https://api.calendly.com/notes?contact=https%3A%2F%2Fapi.calendly.com%2Fcontacts%2FAAAAAAAAAAAAAAAA")

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

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

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

```java Notes for a contact
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.calendly.com/notes?contact=https%3A%2F%2Fapi.calendly.com%2Fcontacts%2FAAAAAAAAAAAAAAAA")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Notes for a contact
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.calendly.com/notes?contact=https%3A%2F%2Fapi.calendly.com%2Fcontacts%2FAAAAAAAAAAAAAAAA', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp Notes for a contact
using RestSharp;

var client = new RestClient("https://api.calendly.com/notes?contact=https%3A%2F%2Fapi.calendly.com%2Fcontacts%2FAAAAAAAAAAAAAAAA");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Notes for a contact
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/notes?contact=https%3A%2F%2Fapi.calendly.com%2Fcontacts%2FAAAAAAAAAAAAAAAA")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
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()
```