Contact Notes

Create and manage notes attached to contacts. Notes are authored by users and have ownership-based authorization for updates and deletes.

All endpoints require authentication via the X-API-Key header. See Authentication.

List notes

GET /contact-notes/:contactId

List notes for a contact. Uses cursor-based pagination.

Path parameters

Parameter	Type	Description
`contactId`	string	Contact ID. Must exist in your org.

Query parameters

Parameter	Type	Default	Notes
`cursor`	string	null	Cursor from a previous response for the next page.
`limit`	number	20	1–100.
`userId`	string	—	Optional. Filter notes by author user ID.

Example request

curl "https://<host>/api/contact-notes/664a...?limit=10" \
  -H "X-API-Key: your-api-key"

Response

{
  "error": false,
  "success": true,
  "message": "Contact notes fetched successfully",
  "code": 200,
  "data": {
    "notes": [
      {
        "_id": "667a...",
        "orgId": "...",
        "userId": "...",
        "contactId": "664a...",
        "content": "Spoke with contact about upcoming event.",
        "createdAt": 1716000000000
      }
    ],
    "cursorPagination": {
      "nextCursor": "abc123...",
      "hasMore": true
    }
  }
}

Uses cursor-based pagination. Pass the nextCursor value as the cursor query parameter to fetch the next page.

Errors

Status	Message	Cause
404	`Contact not found`	Contact ID does not exist in your org.

Create a note

POST /contact-notes/:contactId

Returns 201.

Path parameters

Parameter	Type	Description
`contactId`	string	Contact ID. Must exist in your org.

Request body

Field	Type	Required	Notes
`content`	string	Yes	Note text. Minimum 1 character.

Example request

curl -X POST https://<host>/api/contact-notes/664a... \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Follow up about scholarship application." }'

Response (`201 Created`)

{
  "error": false,
  "success": true,
  "message": "Contact note created successfully",
  "code": 200,
  "data": {
    "_id": "667b...",
    "orgId": "...",
    "userId": "...",
    "contactId": "664a...",
    "content": "Follow up about scholarship application.",
    "createdAt": 1716000000000
  }
}

Note: The HTTP status is 201, but the envelope code field is 200.

Errors

Status	Message	Cause
400	`Content is required`	Missing or empty `content` field.
404	`Contact not found`	Contact ID does not exist in your org.

Update a note

PUT /contact-notes/:id

Only the note author can update.

Path parameters

Parameter	Type	Description
`id`	string	Note ID.

Request body

Field	Type	Required	Notes
`content`	string	Yes	Updated note text. Minimum 1 character.

Example request

curl -X PUT https://<host>/api/contact-notes/667b... \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Updated: confirmed scholarship interest." }'

Response

{
  "error": false,
  "success": true,
  "message": "Contact note updated successfully",
  "code": 200,
  "data": {
    "_id": "667b...",
    "content": "Updated: confirmed scholarship interest."
  }
}

Errors

Status	Message	Cause
403	`You are not authorized to update this contact note`	You are not the note author.
404	`Note not found`	No note with that ID in your org.

Delete a note

DELETE /contact-notes/:id

The note author or an admin can delete.

Path parameters

Parameter	Type	Description
`id`	string	Note ID.

Example request

curl -X DELETE https://<host>/api/contact-notes/667b... \
  -H "X-API-Key: your-api-key"

Response

{
  "error": false,
  "success": true,
  "message": "Contact note deleted successfully",
  "code": 200,
  "data": null
}

Errors

Status	Message	Cause
403	`You need to be the owner or an admin to delete this note`	You are not the author and do not have admin role.
404	`Note not found`	No note with that ID in your org.

Authorization model

Contact notes use ownership-based authorization:

Update: Only the note author can update their own notes.
Delete: The note author or an org admin can delete a note.

Unauthorized actions return 403 Forbidden.

Response envelope

All endpoints use the standard envelope:

{
  "error": false,
  "success": true,
  "message": "...",
  "code": 200,
  "data": "..."
}

Note that create (POST) returns HTTP status 201, while the envelope code remains 200.

On this page