What's new in the SecurityTrax API

New

• Customer communications: create, update, delete — customer_communications now supports GET (list and by id), POST, PATCH /{id}, and DELETE /{id}. A create links both a customer and a customer_note and needs direction (i or o). type defaults to phone, and user_id is set to the acting user. You get a 422 if the note belongs to a different customer or already has an active communication. To recategorize a contact, PATCH the existing record.

• At-risk cases: create, update, delete — customer_at_risks now supports GET (list and by id), POST, PATCH /{id}, and DELETE /{id}. A create needs the customer relationship and a customer_at_risk_reason_id. Resolving and closing work by setting is_resolved / is_closed: the server fills in resolved_at/resolved_by and closed_at/closed_by, which are read-only. A case with is_resolved set must include a customer_at_risk_resolution_id. List filters include is_closed, is_resolved, assigned_user_id, is_assigned, and follow_up_date ranges.

• At-risk notes: POST /v4/customer_at_risk_notes — Add a follow-up note to an at-risk case. Notes can't be edited or deleted after they're created. communication and note are required. You need Modify on the At Risk permission to create one. Notes are listable, and also come back with GET /v4/customer_at_risks/{id}?include=notes.

• Lead interactions: POST /v4/lead_contacts — Log a rep interaction on a lead. Interactions can't be edited or deleted after they're created. note is required, and the parent must be a lead (type: leads); a customer returns 422. If you omit user_id, current_lead_type_id, and current_rep_id, they're filled from the acting user and the lead's current state. Creating requires lead-modify access.

• GET /v4/object_files — Lists customer and lead file metadata. Filters: customer_id (or object_id), service_type, and created_at / updated_at ranges. Sorts on id, object_id, name, created_at, and updated_at. File bytes are still downloaded through v1.

• 24 more documented, listable resources — Each now has GET /v4/{resource} with filters, sorting, and ?count_only=true, plus a reference page. All are read-only.

  • Customers & leads: message_logs, customer_to_email, consumer_financing_applications, consumer_financing_applicants, customer_equipment_reconcile, customer_billing_to_uses
  • Scheduling: calendar_event_reschedules (reschedule history: old/new start, reason, initiated_by), calendar_events_extended (on-site en-route, arrival and departure status)
  • Billing: customer_accounting_information, invoice_emails, invoice_statements, payment_to_invoice (which payment paid which invoice, and amount_used), accounting_journal_entries, accounting_journal_entry_lines, mmr_to_mmr_items
  • Workflows & e-documents: flows, flow_steps, flow_enrollments, flow_enrollment_steps, electronic_document_envelopes, electronic_document_assignments, electronic_document_assignment_recipients, electronic_document_assignment_events, electronic_document_field_value

  customer_billing_to_uses, calendar_events_extended, and payment_to_invoice have composite keys, so they are list-only with no /{id} route.

Changed

• ⚠ Breaking: an unrecognized filter value now returns 422. These filters used to ignore a value they didn't recognize and return the list unfiltered:

  • users?active=, locations?active=
  • groups?assignable=
  • user_rep_numbers?domain=
  • customer_payments?cleared=
  • customer_contacts?about=
  • calendar_category on calendar_events, calendar_event_types, and calendar_event_detail_types

  They now return 422 with reason unsupported_value and list the accepted values. Likewise, sending an array for page, per_page, sort, or include (for example ?page[]=2) returns 422 instead of being read as the default.

• GET /v4/customers can list leads. Add ?record_type=lead to list leads; record_type=customer is still the default. What you see matches the Leads page in SecurityTrax. New filters, which work for both customers and leads: lead_rep_id, lead_type_id, lead_disposition_id, lead_company_id (source), lead_company_campaign_id, and lead_callback_date_from / _to. New sorts: lead_created and lead_callback_date. Sending a customer-only filter (location_id, sale_date_from / _to, cancelled) with record_type=lead returns 422.

• GET /v4/customers accepts ?rep_id= — Exact sales-rep match within your permitted results. A rep with no customers you can see returns an empty page, not 403.

• New includes.

  • customers?include=files works on a single record and on the list.
  • customer_invoices?include=invoice_line_items returns the invoice with its active lines, on a single record or the list.
  • users/{id}?include=udfs returns a user's custom-field values.

  On list requests, each row's include is capped at 100 records. When any row hits the cap, the response adds meta.includes_truncated and meta.include_item_limit.

• customer_id filter alias — customer_invoices, invoice_recurring, object_tags, object_udfs, and object_files accept customer_id in place of entity_id / object_id. Sending both with different values returns 422.

• object_udfs covers user custom fields. Pass ?object_type=user, with user_id as an alias for object_id, to list user values. POST /v4/object_udfs/set and /clear accept user fields. Reading user values requires the company-wide Users view permission, and setting or clearing them requires Users modify. Customer values work as before.

• customer_notes returns follow_up_date on tickets. The ticket due date could already be written but wasn't returned in responses. It is now readable too.

• Access tokens carry a scope. When you create a token, you choose what it works with. A token without API access now gets 401 unauthenticated on /user/v4/*. Existing tokens are scoped to API access, so current integrations keep working without changes.

Fixed

• GET /v4/calendar_events left out appointments you could read by id. Users who can assign sales appointments to themselves, and users with lead scheduling access, now see the same appointments in the list that they can open individually.
• GET /v4/customer_notes totals and pages didn't match the rows returned. Work orders you could see only through the Work Orders permission were missing from the list. Meanwhile, count_only and meta.pagination.total could count notes you couldn't view, so pages came back shorter than per_page. The list and its totals now apply the notes, work-order, and lead-notes permissions separately.