Customer Contacts

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

Required on create: link customer under data.relationships — a create that omits it is rejected with 422 naming the relationship.

How it works

customer_contacts are the emergency / additional contacts on a customer or lead — the people (and alarm passcodes) a monitoring station or a rep may need. Each row belongs to one customer (customer_id) and carries a name, a phone, a contact type (about), and an optional alarm passcode. Full CRUD: POST to add a contact, PATCH to edit, DELETE to remove.

Gated by Customer Emergency Contacts at the customer's location (leads: Lead Emergency Contacts).

Creating a contact

POST /customer_contacts with the owning customer and the contact fields:

curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_contacts" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"customer_id":100,"name":"John Doe","phone1":"8015551234","about":"Mobile","email":"john@example.com"}}}'

* A Pin-type contact may omit phone1.

What you can and can't set

The writable fields match the SecurityTrax contact form exactly. In particular:

• sort is modify-only — new contacts are appended; you reorder an existing contact by PATCHing its sort.
• central_station_id and interactive_services_id are read-only — they are populated by the monitoring / interactive-services integrations, not by users, so the API will not let you set them.

Editing / removing

PATCH /customer_contacts/{id} updates the contact; DELETE /customer_contacts/{id} removes it (soft delete). Both re-check Customer/Lead Emergency Contacts at the customer's location.

Reading a customer's contacts

The simplest read is on the parent: GET /customers/{id}?include=contacts. You can also list directly: GET /customer_contacts?customer_id={customerId} (filters: customer_id, about, created_at/updated_at ranges; sort: id, customer_id, sort, created_at, updated_at; ?count_only=true for the total). The alarm passcode requires the emergency-contact view permission and is never exposed to AI/MCP surfaces.

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.

Contact

View: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts. Create: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts. Update: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts.

Ordering

View: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts. Update: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts.

Passcode

View: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts. Create: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts. Update: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts.

External Connections

View: customers — Customer Emergency Contacts at the record's location; leads — Lead Emergency Contacts.

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, about, created_at_from, created_at_to, updated_at_from, updated_at_to. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../customer_contacts?sort= orders the list by: id, customer_id, sort, created_at, updated_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 — tokens and the Authorization header.