Calendar Events

Reference for the calendar_events 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

Not available as a standard REST operation for this resource: create, update, delete — such requests return 402 feature_not_enabled or 403 permission_denied (see the actions above for this resource's write path).

How it works

calendar_events are appointments — one table holding both tech appointments (calendar_category: tech_schedule: installs, service visits, removals) and sales appointments (calendar_category: sale_schedule). The table has a composite key (id, calendar_category), so records are not addressed at /{id}; instead, appointments of both kinds are managed through collection actions. schedule, reschedule, and cancel take the appointment id (or, for schedule, the calendar_category) in the body. available_users and available_slots are read-only lookups (HTTP 200) for who can take a job and, when the company uses time-slot scheduling, which configured slots are open. Resolve calendar_event_type_id from calendar event types before scheduling. Record a confirmation through calendar event confirmations.

Permissions follow the SecurityTrax scheduler:

• Tech appointments need the Scheduler permission at the customer's location (create / modify / delete for schedule / reschedule / cancel). Your own appointments are always visible.
• Sales appointments need the Sale Scheduler permission, or Assign Sale Schedule To Self — in which case you may only schedule appointments assigned to yourself.

Scheduling a tech appointment

curl -X POST "https://portal.securitytrax.com/acme/user/v4/calendar_events/schedule" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"customer_id":1001,"user_id":42,"calendar_event_type_id":1,"customer_note_id":5005,"start_time":1767290400,"duration":7200,"notes":"Bring the replacement panel"}}}'

calendar_category defaults to tech_schedule.

Scheduling a sales appointment

Pass calendar_category: sale_schedule:

curl -X POST "https://portal.securitytrax.com/acme/user/v4/calendar_events/schedule" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"calendar_category":"sale_schedule","customer_id":1001,"user_id":42,"calendar_event_type_id":1,"start_time":1767290400,"duration":3600}}}'

Sales appointments cannot link a work order (customer_note_id is rejected).

Scheduling through the API runs the same platform side effects as scheduling in SecurityTrax (appointment notifications, remote system sync where configured).

Note. schedule and reschedule perform no double-booking check — like the other integration surfaces, they will happily schedule someone into an occupied window. Use available_users with a time window (or GET /calendar_events?user_id=42&start_from=...&start_to=...) if overlap matters to your flow.

Rescheduling

curl -X POST "https://portal.securitytrax.com/acme/user/v4/calendar_events/reschedule" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"id":314,"start_time":1767376800,"initiated_by":"c","reschedule_reason_id":2}}}'

Works for both tech and sales appointments (the id resolves the kind). start_time is required (unix timestamp or date-time string); pass duration only to change the length. initiated_by (c = customer, d = dealer/company) is optional — when provided and the company tracks reschedules, a reschedule audit record (old time, new time, reason, who initiated) is written alongside the move, exactly as the SecurityTrax scheduler does.

Canceling

curl -X POST "https://portal.securitytrax.com/acme/user/v4/calendar_events/cancel" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"id":314}}}'

Deletes the appointment from the schedule. A linked work order is not closed or unlinked — it simply no longer has this appointment.

Listing appointments

Filters: customer_id, user_id (the assigned tech/rep), calendar_category (tech_schedule / sale_schedule), calendar_event_type_id, customer_note_id (work order), and a start-time window via start_from / start_to (unix timestamps). Sort by id, customer_id, user_id, start_time, duration, or created_at (default start_time, newest first); ?count_only=true for the total.

# A tech's appointments for one day
curl "https://portal.securitytrax.com/acme/user/v4/calendar_events?user_id=42&start_from=1767250800&start_to=1767337199" \
  -H "Authorization: Bearer stx_acme_..."

Who can take the job

POST /calendar_events/available_users returns the techs or sales reps who can be assigned for this customer (the same lists the SecurityTrax scheduler uses), as a slim { user_id, name, fname, lname, eligible } row — not a full users resource. name is Last, First (the same as a user's display name in SecurityTrax). This is a query, not a create: HTTP 200, and the payload is in data (same envelope as a fetch, not meta.data).

# Eligible techs at the customer's office location
curl -X POST "https://portal.securitytrax.com/acme/user/v4/calendar_events/available_users" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"customer_id":1001}}}'

{
  "ok": true,
  "data": {
    "users": [
      {"user_id": 42, "name": "Doe, Jane", "fname": "Jane", "lname": "Doe", "eligible": true}
    ],
    "list_mode": "location"
  },
  "summary": null,
  "breadcrumbs": [],
  "meta": {"surface": "api", "action": "available_users"},
  "errors": []
}

# Specific users, with occupancy for a day
curl -X POST "https://portal.securitytrax.com/acme/user/v4/calendar_events/available_users" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"customer_id":1001,"user_ids":[42,87],"list_mode":"in_coverage_area","start_from":1767250800,"start_to":1767337199}}}'

When a window is sent, each user also has busy, includes_time_off, and conflicts (id, category, start, duration, type — no customer_id). Occupancy looks at the assignee's whole calendar, including time off. No window → those keys are omitted. The response echoes the resolved list_mode (tech only) and the window when one was sent. Timestamps out are unix ints.

Permissions match scheduling: Scheduler create at the customer for tech; Sale Scheduler or Assign Sale Schedule To Self for sales. With only self-assign, omitted user_ids returns you alone; a foreign id is 422.

Open time slots (time-slot scheduling only)

POST /calendar_events/available_slots lists the company's configured tech windows that are open for this customer — the same capacity math as one page of the slot picker. A start_from + start_to window is required and may not be longer than the company's days-to-show-per-page setting (hard-capped at 31). Companies that do not use time-slot scheduling get 422 slot_scheduler_not_enabled (this does not invent 30-minute slots). Sales appointments do not use slots.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/calendar_events/available_slots" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"customer_id":1001,"start_from":1767250800,"start_to":1767855600}}}'

Response data is { slots: [{ start_time, end_time, available }] } (HTTP 200, same query envelope as available_users). Same-day-disabled windows and days past the booking horizon are omitted entirely. Needs Scheduler create at the customer.

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.

Tech Appointment

View: customers — the standard canViewTechSchedule rules; leads — Lead Scheduler. Create: customers — Scheduler at the record's location. Update: customers — Scheduler at the record's location.

Sales Appointment

View: any of: Sale Scheduler; Assign Sale Schedule To Self. Create: any of: Sale Scheduler; Assign Sale Schedule To Self. Update: the standard canModifySaleSchedulerAppointment rules.

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: customer_id, user_id, calendar_category, calendar_event_type_id, customer_note_id, start_from, start_to. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../calendar_events?sort= orders the list by: id, customer_id, user_id, start_time, duration, created_at. 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 — API access tokens and the Authorization header.