Notes

The Notes API allows you to create, read, update, and delete notes on people, companies, and deals. Notes support @mentions to link related people and companies.

Notes are nested under their parent entity:

/api/people/{personId}/notes — Notes on a person
/api/companies/{companyId}/notes — Notes on a company
/api/pipelines/{type}/deals/{dealId}/notes — Notes on a deal

All note endpoints share the same request/response format.

List Notes

GET /api/people/{personId}/notes
GET /api/companies/{companyId}/notes
GET /api/pipelines/{type}/deals/{dealId}/notes

Retrieves a paginated list of notes for the parent entity.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of notes to return (1-100, default: 50)
`offset`	integer	No	Number of notes to skip (default: 0)

Response

Success Response (200)

{
  "success": true,
  "data": {
    "notes": [
      {
        "id": "note-uuid",
        "content": "Had a great call with [@John Doe](person:person-uuid). Discussed partnership with [@Acme Inc](company:company-uuid).",
        "entityType": "USER",
        "entityId": "person-uuid",
        "dealId": null,
        "createdByUserId": "user-uuid",
        "organizationId": "org-uuid",
        "notePeople": [
          {
            "id": "person-uuid",
            "firstName": "John",
            "lastName": "Doe"
          }
        ],
        "noteCompanies": [
          {
            "id": "company-uuid",
            "name": "Acme Inc"
          }
        ],
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "total": 5,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Create Note

POST /api/people/{personId}/notes
POST /api/companies/{companyId}/notes
POST /api/pipelines/{type}/deals/{dealId}/notes

Creates a new note on the parent entity.

Request Body

{
  "content": "Had a great call with [@John Doe](person:person-uuid). Discussed partnership with [@Acme Inc](company:company-uuid)."
}

Parameters

Parameter	Type	Required	Description
`content`	string	Yes	Note content (min 1 character). Supports @mentions.

@Mention Syntax

Link people and companies in note content using this format:

People: [@Display Name](person:uuid)
Companies: [@Display Name](company:uuid)

Mentioned entities are automatically parsed and stored as associations, making them searchable and navigable in the UI.

Response

Success Response (201)

{
  "success": true,
  "data": {
    "id": "note-uuid",
    "content": "Had a great call with [@John Doe](person:person-uuid).",
    "entityType": "USER",
    "entityId": "person-uuid",
    "createdByUserId": "user-uuid",
    "organizationId": "org-uuid",
    "notePeople": [
      {
        "id": "person-uuid",
        "firstName": "John",
        "lastName": "Doe"
      }
    ],
    "noteCompanies": [],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "message": "Note created successfully"
}

Get Note

GET /api/people/{personId}/notes/{noteId}
GET /api/companies/{companyId}/notes/{noteId}
GET /api/pipelines/{type}/deals/{dealId}/notes/{noteId}

Retrieves a specific note. The note must belong to the specified parent entity.

Path Parameters

Parameter	Type	Required	Description
`noteId`	string	Yes	Note UUID

Response

Success Response (200)

{
  "success": true,
  "data": {
    "id": "note-uuid",
    "content": "Follow up on proposal.",
    "entityType": "USER",
    "entityId": "person-uuid",
    "createdByUserId": "user-uuid",
    "organizationId": "org-uuid",
    "notePeople": [],
    "noteCompanies": [],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Update Note

PATCH /api/people/{personId}/notes/{noteId}
PATCH /api/companies/{companyId}/notes/{noteId}
PATCH /api/pipelines/{type}/deals/{dealId}/notes/{noteId}

Updates a note's content. @mention associations are re-parsed from the new content.

Request Body

{
  "content": "Updated: Follow up on proposal next Tuesday."
}

Response

Success Response (200)

{
  "success": true,
  "data": {
    "id": "note-uuid",
    "content": "Updated: Follow up on proposal next Tuesday.",
    "notePeople": [],
    "noteCompanies": [],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T11:00:00.000Z"
  },
  "message": "Note updated successfully"
}

Delete Note

DELETE /api/people/{personId}/notes/{noteId}
DELETE /api/companies/{companyId}/notes/{noteId}
DELETE /api/pipelines/{type}/deals/{dealId}/notes/{noteId}

Deletes a note from the parent entity.

Response

Success Response (200)

{
  "success": true,
  "data": {
    "deleted": true
  },
  "message": "Note deleted successfully"
}

Example Usage

# List notes on a person
curl -X GET "https://beta-api.introzy.com/api/people/person-uuid/notes" \
  -H "Authorization: Bearer introzy_your_api_key"

# Create a note on a company with @mentions
curl -X POST "https://beta-api.introzy.com/api/companies/company-uuid/notes" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Discussed renewal with [@Jane Smith](person:person-uuid). Looking good."
  }'

# Create a note on a deal
curl -X POST "https://beta-api.introzy.com/api/pipelines/sales/deals/deal-uuid/notes" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Demo scheduled for next week."
  }'

# Update a note
curl -X PATCH "https://beta-api.introzy.com/api/people/person-uuid/notes/note-uuid" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated note content."}'

# Delete a note
curl -X DELETE "https://beta-api.introzy.com/api/people/person-uuid/notes/note-uuid" \
  -H "Authorization: Bearer introzy_your_api_key"

Entity Types

Notes are scoped to their parent entity type:

Parent	Entity Type	Path Prefix
Person	`USER`	`/api/people/{personId}/notes`
Company	`COMPANY`	`/api/companies/{companyId}/notes`
Deal	varies	`/api/pipelines/{type}/deals/{dealId}/notes`

For deal notes, {type} is the pipeline type: sales, advocacy, integration, referral, or partner.

Referral Opportunities

Custom Fields