Pin or unpin a note

curl --request POST \
  --url https://client-api.salesfinity.co/v2/notes/{id}/pin \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "507f1f77bcf86cd799439044"
}
'

import requests

url = "https://client-api.salesfinity.co/v2/notes/{id}/pin"

payload = { "user_id": "507f1f77bcf86cd799439044" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: '507f1f77bcf86cd799439044'})
};

fetch('https://client-api.salesfinity.co/v2/notes/{id}/pin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client-api.salesfinity.co/v2/notes/{id}/pin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_id' => '507f1f77bcf86cd799439044'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://client-api.salesfinity.co/v2/notes/{id}/pin"

	payload := strings.NewReader("{\n  \"user_id\": \"507f1f77bcf86cd799439044\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://client-api.salesfinity.co/v2/notes/{id}/pin")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"507f1f77bcf86cd799439044\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v2/notes/{id}/pin")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"507f1f77bcf86cd799439044\"\n}"

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

{
  "_id": "6703f1c2a9e4b8d1c2f3a4b5",
  "team": "507f1f77bcf86cd799439012",
  "author": {
    "_id": "507f1f77bcf86cd799439033",
    "first_name": "Maya",
    "last_name": "Chen",
    "email": "[email protected]"
  },
  "content": "Mentioned moving back from Lisbon next quarter.",
  "is_pinned": true,
  "contact": "6703f1c2a9e4b8d1c2f3a4b6",
  "createdAt": "2026-10-03T14:05:11.482Z",
  "updatedAt": "2026-10-03T15:31:02.774Z",
  "pinned_at": "2026-10-03T15:31:02.774Z",
  "pinned_by": "507f1f77bcf86cd799439044"
}

{
  "message": "User is not a member of this team",
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Note not found",
  "error": "Not Found",
  "statusCode": 404,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Rate limit of 300 requests per minute exceeded. Retry in 12s.",
  "error": "Too Many Requests",
  "statusCode": 429,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Internal server error",
  "error": "Internal Server Error",
  "statusCode": 500,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Notes

Pin or unpin a note

Flips a note between pinned and unpinned. Any member of the team can pin or unpin any of the team’s notes, not only the author.

Pinning sets is_pinned to true and records pinned_at and pinned_by (the user_id you send). Unpinning sets is_pinned to false and removes both fields. Pinned notes sort first in List notes, most recently pinned first.

Not idempotent: each call flips the state, so a retried request can undo the first. To reach a specific state, read is_pinned from List notes and call this only when it differs. Succeeds with 201.

POST

notes

{id}

Pin or unpin a note

curl --request POST \
  --url https://client-api.salesfinity.co/v2/notes/{id}/pin \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "507f1f77bcf86cd799439044"
}
'

import requests

url = "https://client-api.salesfinity.co/v2/notes/{id}/pin"

payload = { "user_id": "507f1f77bcf86cd799439044" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: '507f1f77bcf86cd799439044'})
};

fetch('https://client-api.salesfinity.co/v2/notes/{id}/pin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client-api.salesfinity.co/v2/notes/{id}/pin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_id' => '507f1f77bcf86cd799439044'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://client-api.salesfinity.co/v2/notes/{id}/pin"

	payload := strings.NewReader("{\n  \"user_id\": \"507f1f77bcf86cd799439044\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://client-api.salesfinity.co/v2/notes/{id}/pin")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"507f1f77bcf86cd799439044\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v2/notes/{id}/pin")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"507f1f77bcf86cd799439044\"\n}"

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

{
  "_id": "6703f1c2a9e4b8d1c2f3a4b5",
  "team": "507f1f77bcf86cd799439012",
  "author": {
    "_id": "507f1f77bcf86cd799439033",
    "first_name": "Maya",
    "last_name": "Chen",
    "email": "[email protected]"
  },
  "content": "Mentioned moving back from Lisbon next quarter.",
  "is_pinned": true,
  "contact": "6703f1c2a9e4b8d1c2f3a4b6",
  "createdAt": "2026-10-03T14:05:11.482Z",
  "updatedAt": "2026-10-03T15:31:02.774Z",
  "pinned_at": "2026-10-03T15:31:02.774Z",
  "pinned_by": "507f1f77bcf86cd799439044"
}

{
  "message": "User is not a member of this team",
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Note not found",
  "error": "Not Found",
  "statusCode": 404,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Rate limit of 300 requests per minute exceeded. Retry in 12s.",
  "error": "Too Many Requests",
  "statusCode": 429,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Internal server error",
  "error": "Internal Server Error",
  "statusCode": 500,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Flips a note between pinned and unpinned. Pinned notes sort to the top of List notes, the most recently pinned first.

Unlike editing and deleting, any team member may pin or unpin a note, not only its author.

Call on a note that is	Result
Unpinned	`is_pinned` becomes `true`; `pinned_at` and `pinned_by` (the `user_id` you send) are set
Pinned	`is_pinned` becomes `false`; `pinned_at` and `pinned_by` are removed

This call toggles, so it is not idempotent: a retried request undoes the first one. To reach a specific state, read is_pinned from List notes and call this only when it differs.

Path parameters

id (required, string): The note’s _id, a 24-character hex string, from List notes.

Request body

Field	Type	Required	Description
`user_id`	string	Yes	ID of the team member pinning or unpinning. Must be a member of the team that owns the API key.

Example request

{
  "user_id": "507f1f77bcf86cd799439044"
}

Response (201)

Returns the updated note object with its new is_pinned, pinned_at and pinned_by.

Errors

Status	When
400	`user_id` is missing, not an ID or not a member of the team, or the note `id` is not a valid ID (`Invalid ObjectId format for parameter: id`)
404	No note with this `id` exists on your team

Authorizations

x-api-key

string

header

required

Team-scoped API key generated in the Salesfinity dashboard under Settings → Connections → API & Webhooks. A missing or invalid key returns HTTP 403.

Path Parameters

string

required

The note's _id, as returned by List notes or Create a note. A 24-character hex string.

Example:

"6703f1c2a9e4b8d1c2f3a4b5"

Body

application/json

user_id

string

required

ID of the member pinning or unpinning, a 24-character hex string. Any member of the team may; recorded as pinned_by when the note becomes pinned.

Example:

"507f1f77bcf86cd799439044"

Response

The note with its new pin state.

_id

string

Note ID.

Example:

"6703f1c2a9e4b8d1c2f3a4b5"

team

string

Team that owns the note.

Example:

"507f1f77bcf86cd799439012"

author

object

The author, with first_name, last_name, email and image when Salesfinity has them. null if the author's user record no longer exists.

Show child attributes

content

string

Plain text of the note.

is_pinned

boolean

Whether the note is pinned. false for a new note.

pinned_at

string<date-time> | null

When the note was pinned. Absent when the note is not pinned.

pinned_by

string | null

ID of the member who pinned the note. Absent when the note is not pinned.

contact

string | null

ID of the contact the note is attached to. Present on person notes only.

company

string | null

ID of the company the note is attached to. Present on company notes only.

createdAt

string<date-time>

When the note was created.

updatedAt

string<date-time>

When the note was last changed, including pin changes.

Get started

MCP server

MCP reference

MCP use cases

Dialer API

Calls and analytics API

Enrichment API

Sequencer API

Pin or unpin a note

Path parameters

Request body

Example request

Response (201)

Errors

Authorizations

Path Parameters

Body

Response

​Path parameters

​Request body

​Example request

​Response (201)

​Errors

Authorizations

Path Parameters

Body

Response

Path parameters

Request body

Example request

Response (201)

Errors