Customer Notes
Reference for the customer_notes resource. Requests follow the conventions in
Requests and Responses; fields you
receive and may write are filtered by your user's permissions, so responses can
contain a subset of the fields below.
Operations
| Operation | Request |
|---|---|
| List | GET /{profile}/user/v4/customer_notes |
| Fetch | GET /{profile}/user/v4/customer_notes/{id} |
| Create | POST /{profile}/user/v4/customer_notes |
| Update | PATCH /{profile}/user/v4/customer_notes/{id} |
| Delete | DELETE /{profile}/user/v4/customer_notes/{id} |
Required on create: link customer under data.relationships — a create that omits it is rejected with 422 naming the relationship.
How it works
customer_notes is one resource spanning three record types on a single table.
The type is decided by two fields and resolved to a typed shape automatically:
| Record type | When | Extra fields it carries |
|---|---|---|
| Note | ticket_type_id = 0 and is_work_order = 0 |
none beyond the base fields |
| Ticket | ticket_type_id > 0 and is_work_order = 0 |
ticket columns (follow-up, assignment, close) |
| Work order | is_work_order = 1 |
ticket columns plus work-order columns |
Every record is type: "customer_notes" regardless — the record type only
changes which fields you get back.
Creating
POST creates a record whose record type is decided by the fields you send —
a plain note by default, a ticket if you set ticket_type_id, or a work order if
you set is_work_order to 1. Each type is gated by its own permission (work
orders need the customer work-orders permission) and validated by its own rules (a
work order also requires adt_work_order_type_id). subject and note_type_id
are required for every type. Put the fields under data.attributes and link the
parent customer under data.relationships.customer:
# a plain note
curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_notes" \
-H "Authorization: Bearer stx_acme_..." \
-H "Content-Type: application/json" \
-d '{"data":{"attributes":{"subject":"Panel swap requested","note":"Customer called to schedule.","note_type_id":1},"relationships":{"customer":{"data":{"type":"customers","id":1}}}}}'
The parent customer link is required: creation is authorized at that customer's
location, so a request without a customer is rejected (403), and a link to a
customer that doesn't exist returns 422 naming the customer relationship.
Listing and record types
The list endpoint returns all three record types mixed (newest first),
location-scoped to the customers you can see. Narrow to one type with
?record_type=note|ticket|work_order; an unrecognized value returns 422.
Tickets and work orders are also reachable — already type-filtered — as customer
relationships: GET /customers/{id}?include=tickets and ?include=work_orders
(and ?include=notes for plain notes). Prefer those when you want one customer's
records of a single type.
Permissions differ by record type
Notes and tickets are gated by the customer/lead notes permission; work
orders are gated by the customer work-orders permission. So the same user can
read a customer's notes and tickets yet get 404 on a work order fetched by id —
or an empty work_orders include — because access is decided per record, per
type.
Deleting
DELETE soft-deletes the record; afterward every read of it returns 404.
Validation worth knowing before you integrate:
subjectis required (1–255 characters) andnote_type_idis required.noteis optional — omit it or send an empty body; if present it may be up to the column limit (65535 characters).priorityis capped at3.- On a work order (
is_work_order = 1),adt_work_order_type_idis required and must be a real type (> 0) — omitting it or sending0returns422. subjectandnoteare rejected if they look like a credit-card number (a PCI guard), returned as422.
Fields
Fields are grouped by the permission that gates them. A group you may not view
is absent from responses; a group you may not write is rejected with 422 when
sent in a write.
Work Order
View: customers — Customer Work Orders at the record's location; leads — Lead Notes. Create: customers — Customer Work Orders at the record's location; leads — Lead Notes. Update: customers — Customer Work Orders at the record's location; leads — Lead Notes.
| Field | Type | Writable | Validation |
|---|---|---|---|
is_work_order |
integer | Create, update | — |
adt_work_order_type_id |
integer (nullable) | Create, update | Required on create; min 1 |
adt_work_order_number |
string (nullable) | Read-only | max length 255 |
ticket_type_id |
integer | Create, update | min 0 |
follow_up_date |
date (nullable) | Create, update | — |
needs_tech_schedule |
boolean (nullable) | Read-only | — |
tech_schedule_id |
integer (nullable) | Read-only | min 0 |
closed_by |
integer (nullable) | Read-only | min 0 |
closed_at |
datetime (nullable) | Read-only | — |
customer_id |
integer | Create, update | min 0 |
note_type_id |
integer | Create, update | Required on create; min 0 |
user_id |
integer | Create, update | min 0 |
subject |
string (nullable) | Create, update | Required on create; max length 255; min length 1 |
note |
string (nullable) | Create, update | max length 65535 |
priority |
integer (nullable) | Create, update | max 3; min 0 |
created_at |
datetime | Read-only | — |
created_by |
integer | Read-only | — |
updated_at |
datetime | Read-only | — |
updated_by |
integer | Read-only | — |
Ticket
View: customers — Customer Notes at the record's location; leads — Lead Notes. Create: customers — Customer Notes at the record's location; leads — Lead Notes. Update: customers — Customer Notes at the record's location; leads — Lead Notes.
| Field | Type | Writable | Validation |
|---|---|---|---|
ticket_type_id |
integer | Create, update | min 0 |
follow_up_date |
date (nullable) | Create, update | — |
needs_tech_schedule |
boolean (nullable) | Read-only | — |
tech_schedule_id |
integer (nullable) | Read-only | min 0 |
closed_by |
integer (nullable) | Read-only | min 0 |
closed_at |
datetime (nullable) | Read-only | — |
customer_id |
integer | Create, update | min 0 |
note_type_id |
integer | Create, update | Required on create; min 0 |
user_id |
integer | Create, update | min 0 |
subject |
string (nullable) | Create, update | Required on create; max length 255; min length 1 |
note |
string (nullable) | Create, update | max length 65535 |
priority |
integer (nullable) | Create, update | max 3; min 0 |
created_at |
datetime | Read-only | — |
created_by |
integer | Read-only | — |
updated_at |
datetime | Read-only | — |
updated_by |
integer | Read-only | — |
Note
View: customers — Customer Notes at the record's location; leads — Lead Notes. Create: customers — Customer Notes at the record's location; leads — Lead Notes. Update: customers — Customer Notes at the record's location; leads — Lead Notes.
| Field | Type | Writable | Validation |
|---|---|---|---|
customer_id |
integer | Create, update | min 0 |
note_type_id |
integer | Create, update | Required on create; min 0 |
user_id |
integer | Create, update | min 0 |
subject |
string (nullable) | Create, update | Required on create; max length 255; min length 1 |
note |
string (nullable) | Create, update | max length 65535 |
priority |
integer (nullable) | Create, update | max 3; min 0 |
created_at |
datetime | Read-only | — |
created_by |
integer | Read-only | — |
updated_at |
datetime | Read-only | — |
updated_by |
integer | Read-only | — |
Pagination
The list endpoint uses client-controlled offset pagination: ?page= (1-based) and
?per_page= (default 25, max 100). The response mirrors
meta.pagination (page, per_page, total, last_page) and sends an RFC5988
Link header; follow rel="next" to walk pages. See
Pagination.
Filters
The list endpoint accepts these query-param filters: record_type, status, customer_id, note_type_id, user_id, ticket_type_id, created_at_from, created_at_to, updated_at_from, updated_at_to, follow_up_date_from, follow_up_date_to.
An unsupported filter parameter returns 422. See
Filtering collections
for matching semantics.
Sorting
GET .../customer_notes?sort= orders the list by: id, created_at, updated_at, priority, subject, follow_up_date, customer_id.
Prefix a field with - for descending; comma-separate for tie-breakers. An
unsupported field returns 422. See
Sorting collections.
Related
- Requests and Responses — envelope, errors, pagination, and rate limits.
- Authentication — tokens and the
Authorizationheader.