Trouble ticket notes

A trouble ticket note is a text record attached to a trouble ticket that captures information, updates, or correspondence related to the ticket. Notes provide an audit trail of activity and communications as a trouble ticket is investigated and resolved.

The fundamental fields of a trouble ticket note are:

  • subject – A short summary or title for the note.
  • body – The full text of the note. The GET collection response returns a bodySummary field containing a truncated version.
  • language – The language in which the note is written.
  • author – The user who created the note. Populated automatically by BillingCenter at creation time.
  • relatedTo – The entity type the note relates to (for example, troubleTickets).
  • topic – The subject category of the note (for example, general).
  • securityType – Controls visibility of the note (for example, unrestricted).
  • confidential – Boolean indicating whether the note is marked confidential.

These fields are shared with account and policy notes. For information about account and policy notes, see Creating account and policy notes.

Trouble ticket notes are a sub-resource of trouble tickets. Each note is also accessible via the common notes endpoints at /common/v1/notes/{noteId}, which supports GET, PATCH, and DELETE operations on individual notes.

The following endpoints are available for trouble ticket notes:

  • GET /billing/v1/trouble-tickets/{troubleTicketId}/notes
  • POST /billing/v1/trouble-tickets/{troubleTicketId}/notes

Querying for trouble ticket notes

Use the following endpoint to retrieve the notes associated with a specific trouble ticket:

  • GET /billing/v1/trouble-tickets/{troubleTicketId}/notes

The response contains a paginated collection of notes. By default, each note does not include the body field, instead including a the truncated bodySummary. This is because of the potentially large size of the body field. The body can be retrieved using the ?fields=body query parameter, or by retrieving the individual note using the GET /common/v1/notes/{noteId} endpoint.

Example of querying trouble ticket notes

The following example retrieves the notes for a trouble ticket.

Command 
GET /billing/v1/trouble-tickets/bc:SEyIzYv_UUbqo57yO12dV/notes

Response

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "author": {
                    "displayName": "Super User",
                    "id": "default_data:1",
                    "type": "User",
                    "uri": "/admin/v1/users/default_data:1"
                },
                "bodySummary": "Policyholder contests that the invoice amount is not correct. Need to send communication...",
                "confidential": false,
                "createdDate": "2026-05-20T21:24:03.500Z",
                "id": "bc:SD6mbcc5StqKaJXsZ2xTq",
                "language": {
                    "code": "en_US",
                    "name": "English (US)"
                },
                "securityType": {
                    "code": "unrestricted",
                    "name": "Unrestricted"
                },
                "subject": "Invoice amount complaint",
                "topic": {
                    "code": "general",
                    "name": "General"
                },
                "updateTime": "2026-05-20T21:26:20.875Z"
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/common/v1/notes/bc:SD6mbcc5StqKaJXsZ2xTq",
                    "methods": [
                        "delete",
                        "get",
                        "patch"
                    ]
                }
            }
        },
        {
            "attributes": {
                "author": {
                    "displayName": "Super User",
                    "id": "default_data:1",
                    "type": "User",
                    "uri": "/admin/v1/users/default_data:1"
                },
                "bodySummary": "Sent email to policyholder asking about disputed invoice item amount. Will follow up if...",
                "confidential": false,
                "createdDate": "2026-05-20T21:18:24.722Z",
                "id": "bc:SdGw-g25BZo0y4TFDP3ZF",
                "language": {
                    "code": "en_US",
                    "name": "English (US)"
                },
                "securityType": {
                    "code": "confidential",
                    "name": "Confidential"
                },
                "subject": "Asked policyholder for clarification",
                "topic": {
                    "code": "general",
                    "name": "General"
                },
                "updateTime": "2026-05-20T21:18:34.479Z"
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/common/v1/notes/bc:SdGw-g25BZo0y4TFDP3ZF",
                    "methods": [
                        "delete",
                        "get",
                        "patch"
                    ]
                }
            }
        }
    ],
    "links": {
        "first": {
            "href": "/billing/v1/trouble-tickets/bc:So9-TxqqnmEXW22G3IgbH/notes",
            "methods": [
                "get"
            ]
        },
        "self": {
            "href": "/billing/v1/trouble-tickets/bc:So9-TxqqnmEXW22G3IgbH/notes",
            "methods": [
                "get"
            ]
        }
    }
}

Creating trouble ticket notes

To add a note to a trouble ticket, use the following endpoint:

  • POST /billing/v1/trouble-tickets/{troubleTicketId}/notes

A successful request returns HTTP 201 with the created note's fields.

Minimum creation criteria

The following fields are required to create a trouble ticket note:

Field Description Note
body The full text of the note.
language The language of the note. Specify as a typekey reference to the LanguageType typelist. Example code: en_us.
subject A short summary or title for the note.

The following optional fields can also be set at creation:

  • confidential – Boolean indicating whether the note is confidential. Defaults to false.
  • relatedTo – The entity type the note relates to. Specify as a typekey reference (for example, {"code": "troubleTickets"}). Nullable.
  • securityType – Controls note visibility. Specify as a typekey reference (for example, {"code": "unrestricted"}).
  • topic – The subject category of the note. Specify as a typekey reference (for example, {"code": "general"}).

The author field is populated automatically by BillingCenter based on the authenticated user making the request.

Example: creating a note with the minimum required fields

The following payload is the minimum required to create a trouble ticket note.

Command 
POST /billing/v1/trouble-tickets/bc:SEyIzYv_UUbqo57yO12dV/notes

Request body

{
  "data": {
    "attributes": {
      "body": "Reviewed the billing discrepancy with the account team. Awaiting confirmation of payment records.",
      "language": {
        "code": "en_us"
      },
      "subject": "Initial investigation update"
    }
  }
}

Response

{
    "data": {
        "attributes": {
            "author": {
                "displayName": "Super User",
                "id": "default_data:1",
                "type": "User",
                "uri": "/admin/v1/users/default_data:1"
            },
            "body": "Reviewed the billing discrepancy with the account team. Awaiting confirmation of payment records.",
            "confidential": false,
            "createdDate": "2026-05-20T22:33:18.159Z",
            "id": "bc:SP1mSKYQmeCwY7G9hXKhl",
            "language": {
                "code": "en_US",
                "name": "English (US)"
            },
            "securityType": {
                "code": "unrestricted",
                "name": "Unrestricted"
            },
            "subject": "Initial investigation update",
            "topic": {
                "code": "general",
                "name": "General"
            },
            "updateTime": "2026-05-20T22:33:18.174Z"
        },
        "checksum": "0",
        "links": {
            "self": {
                "href": "/common/v1/notes/bc:SP1mSKYQmeCwY7G9hXKhl",
                "methods": [
                    "delete",
                    "get",
                    "patch"
                ]
            }
        }
    }
}

Example: creating a note with all fields

The following example creates a trouble ticket note with all available fields specified.

Command 
POST /billing/v1/trouble-tickets/bc:SEyIzYv_UUbqo57yO12dV/notes

Request body

{
  "data": {
    "attributes": {
      "body": "Escalated to finance team for review of payment records.",
      "confidential": false,
      "language": {
        "code": "en_us"
      },
      "relatedTo": {
        "code": "troubleTickets"
      },
      "securityType": {
        "code": "unrestricted"
      },
      "subject": "Escalation note",
      "topic": {
        "code": "general"
      }
    }
  }
}