Documentation

Customers

Reference for the customers 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/customers
Fetch GET /{profile}/user/v4/customers/{id}
Create POST /{profile}/user/v4/customers
Update PATCH /{profile}/user/v4/customers/{id}
Delete DELETE /{profile}/user/v4/customers/{id}

Partner provisioning actions for Alarm.com, Guardian Protection Services, ADT are documented on their own pages under Integration Actions.

How it works

A customers record is either a customer or a lead — one resource, one id space, distinguished by sale information:

  • Create a lead by POSTing without a sale_date. Leads require a lead_company_id (the record's source) or the request fails with 422. A lead has no location — do not send location_id (a non-zero location_id is rejected with 422).
  • Create a customer by POSTing with a sale_date. A customer requires a valid location_id (a real location). account_type defaults to Residential when omitted.
  • The list endpoint returns customers only; leads don't appear in it. A lead is still readable and updatable by id.
# Create a lead (no sale_date)
curl -X POST "https://portal.securitytrax.com/acme/user/v4/customers" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"fname":"Jane","lname":"Doe","city":"Lehi","state":"UT","phone1":"8015550100","lead_company_id":1}}}'

# Create a customer (sale_date present)
curl -X POST "https://portal.securitytrax.com/acme/user/v4/customers" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"fname":"John","lname":"Doe","city":"Lehi","state":"UT","phone1":"8015550100","location_id":1,"sale_date":"2026-07-10","account_type":"Residential"}}}'

Location (location_id)

location_id is where a customer physically lives, and it splits cleanly on the customer-vs-lead distinction. The column is never null — the "no location" value is the integer 0.

Record Valid location_id On create
Customer (sale_date present) a real location, > 0 required — must be a location you can create customers at
Lead (no sale_date) 0 only (a lead has no location) omit it, or send 0 explicitly — both work; the stored value is 0

The rules that follow from that:

  • A lead may send location_id: 0 explicitly (or omit it entirely) — both produce a lead stored with location_id = 0. Sending a non-zero location_id on a lead is rejected with 422 ("a lead has no location").
  • A customer must send a real, non-zero location_id. Omitting it, or sending 0, is rejected:
    • On create, this surfaces as 403 ("cannot create customers") — the permission gate is evaluated against location 0, which no one holds a create grant at, so it fails before field validation runs. The fix is the same either way: send a location you can create customers at.
    • On update, it surfaces as 422 ("location_id is required and must be a valid location for a customer").
  • location_id is effectively create-time for a customer — an update that doesn't include it leaves the stored location untouched.

Deleting a customer soft-deletes the record: DELETE /customers/{id} marks it deleted, after which every read of it returns 404. Treat this as permanent — there is no API or in-app way to undo it. The record is soft-deleted rather than physically erased, so SecurityTrax support can restore it on request, but there is no self-service recovery. It requires the customer delete permission at the record's location — leads use the lead delete permission — and returns 403 without it. When you want to end a customer's lifecycle without losing the record, use cancellation (customer_is_cancelled, customer_cancel_date, customer_cancel_reason_id) or archiving instead.

Filtering by date

Date filters take an inclusive range as <field>_from / <field>_to (each optional; a date-only value like 2026-07-01 spans the whole day, and an unparseable value returns 422). A customer carries five distinct dates — pick the one that matches what you're actually asking:

Filter Column What it marks
sale_date_from / _to sale_date The sale date (business).
created_from / _to created When the record became a customer (a sale). Empty while it is still a lead.
lead_created_from / _to lead_created When the record was first created as a lead. Empty if it was created directly as a customer.
created_at_from / _to created_at When the database row was inserted — an audit stamp, always set. Use this for "everything created since X".
updated_at_from / _to updated_at When the row was last modified (audit stamp). Use this for incremental sync — "everything that changed since my last poll".

For incremental sync, updated_at_from is almost always the one you want.

Validation worth knowing before you integrate:

  • phone1 is required and must be a valid phone number. phone2, phone3 and phone4 are optional, but each is validated the same way when provided. Formatting (spaces, dashes, parentheses) is stripped automatically before the number is checked and stored.
  • zip must be a valid ZIP/postal code for the record's state — changing either field re-validates the pair.
  • birthdate must place the person between 15 and 120 years old.
  • monitoring_company_id and interactive_services_provider_id cannot be changed once the record is linked to a central station / interactive services account (409-style state rules returned as 422 with detail).

Reviewed member includes

?include=<name> embeds a related collection under data.relationships.<name>. Every embedded record is permission-filtered field by field, exactly as if you fetched it directly — a field you can't view is omitted, and a relationship you can't view at all returns 403 on a single record (or an empty array per row on the collection). These member includes are reviewed and documented:

Include Returns Permission to view Notes
notes customer_notes (plain notes) Customer Notes (leads: Lead Notes) The note/ticket/work-order split; plain notes only.
tickets customer_notes (tickets) Customer Notes (leads: Lead Notes) Rows with a ticket type.
work_orders customer_notes (work orders) Customer Work Orders Gated separately from notes — you can see notes without seeing work orders.
equipment customer_equipment Customer Equipment (leads: view-lead) Cost fields (equipment_cost, equipment_value, equipment_par, equipment_tech_bonus, …) ride the equipment permission and are never exposed to AI. central_station_id / interactive_services_id need the equipment, monitoring, or interactive-services permission.
invoices customer_invoices Customer Invoices (leads: Lead Invoices) Invoice header fields only (dates, terms, notes, mailing info). Line-item amounts and totals live on the invoice's own line items, not here.

On the collection endpoint (GET .../customers?include=) only notes, tickets, and work_orders are supported; the others are single-record only.

Partner provisioning actions

Provisioning the customer at integration partners (Alarm.com, Guardian Protection Services, ADT) happens through per-record actions documented on their own pages under Integration Actions — see the links beneath the operations table above. They all call the same integration engine as the SecurityTrax connection tabs, and the customer's identity data always comes from the customer record, so keep it accurate before provisioning.

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.

Profile

View: customers — the standard canViewCustomer rules; leads — the standard canViewLead rules. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
location_id integer (nullable) Create, update Required on create; min 0
parent_entity_id integer (nullable) Create, update min 0
account_type string (nullable) Create, update max length 255; one of: Residential, Commercial
account_class_id integer (nullable) Create, update min 0
business_name string (nullable) Create, update max length 255
business_contact string (nullable) Create, update max length 255
lead_home_ownership string (nullable) Create, update one of: own, rent, lease, other, model

Lifecycle

View: customers — the standard canViewCustomer rules; leads — the standard canViewLead rules.

Field Type Writable Validation
created datetime (nullable) Read-only —
lead_created datetime (nullable) Read-only —
created_at datetime (nullable) Read-only —
created_by integer (nullable) Read-only —
updated_at datetime (nullable) Read-only —
updated_by integer (nullable) Read-only —

Address Verification

View: customers — the standard canViewCustomer rules; leads — the standard canViewLead rules.

Field Type Writable Validation
address_verified_at datetime (nullable) Read-only —
address_verified_via string (nullable) Read-only max length 16
property_ownership_verification_status string (nullable) Read-only max length 50

Contact

View: customers — the standard canViewCustomer rules; leads — the standard canViewLead rules. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer Contact Info at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
fname string (nullable) Create, update Required on create; max length 255
lname string (nullable) Create, update Required on create; max length 255
lang string (nullable) Create, update max length 2
address1 string (nullable) Create, update max length 255
address2 string (nullable) Create, update max length 255
city string (nullable) Create, update Required on create; max length 255
state string (nullable) Create, update Required on create; max length 2
zip string (nullable) Create, update max length 50
county string (nullable) Create, update max length 100
cross_street string (nullable) Create, update max length 100
phone1 string (nullable) Create, update Required on create; max length 15
phone2 string (nullable) Create, update max length 15
phone3 string (nullable) Create, update max length 15
phone4 string (nullable) Create, update max length 15
email string (nullable) Create, update max length 255; email format
contact_time string (nullable) Create, update max length 50
spouse string (nullable) Create, update max length 255
credit_tracking string (nullable) Create, update max length 100

Credit

View: customers — the standard canViewCustomer rules; leads — the standard canViewLead rules. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer Contact Info at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
beacon_score integer (nullable) Create, update max 1000; min 100

Birthdate

View: customers — Cust Conf Birthday at the record's location; leads — Lead Conf Birthday. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer Contact Info at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
birthdate string (nullable) Create, update —

SSN

View: customers — Cust Conf SSN at the record's location; leads — Lead Conf SSN. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer Contact Info at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
ssn string (nullable) Create, update —

Sale

View: customers — Customer Sale Info at the record's location; leads — the standard canViewLead rules. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer Sale Info at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
sale_date string (nullable) Create, update —
rep_id integer (nullable) Create, update min 0
train_id integer (nullable) Create, update —
lead_rep_id integer (nullable) Create, update min 0
lead_callcenter_rep string (nullable) Create, update max length 255
mmr_id integer (nullable) Create, update min 0
mmr_a_la_carte boolean (nullable) Create, update —
monitoring_plan_id integer (nullable) Create, update —
activation_fee_id integer (nullable) Create, update min 0
payment_received boolean (nullable) Create, update —
lead_company_id integer (nullable) Create, update min 0
lead_company_campaign_id integer (nullable) Create, update min 0
discount_affiliate_id integer (nullable) Create, update min 0
discount_affiliate_member_number string (nullable) Create, update max length 45
term_id integer (nullable) Create, update min 0
customer_warranty_id integer (nullable) Create, update min 0
dealer_number_id integer (nullable) Create, update min 0
collections_date string (nullable) Create, update date format Y-m-d

Cancel

View: Customer Sale Info at the record's location. Update: Customer Cancel (view) at the record's location.

Field Type Writable Validation
customer_is_cancelled boolean (nullable) Update only —
customer_cancel_date string (nullable) Update only —
customer_cancel_reason_id integer (nullable) Update only —

Connection Providers

View: customers — the standard canViewCustomer rules; leads — the standard canViewLead rules. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
monitoring_company_id integer (nullable) Create, update min 0
interactive_services_provider_id integer (nullable) Create, update min 0

Monitoring Connection

View: any of: Customer ADT at the record's location; Customer Monitronics at the record's location; Customer CMS at the record's location; Customer Affiliated Monitoring at the record's location; Customer Rapid Response at the record's location; Customer Avant Guard at the record's location; Customer United Central Control at the record's location; Customer Safe at the record's location; Customer All American Monitoring at the record's location; Customer API at the record's location. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
account_num string (nullable) Create, update max length 255
secondary_account_num string (nullable) Create, update max length 255
adt_customer_number string (nullable) Create, update max length 255
adt_serial_man string (nullable) Create, update min length 0
adt_monitoring_system_type_id integer (nullable) Create, update min 0

Interactive Services Connection

View: any of: Customer Alarm Dot Com at the record's location; Customer Secure Net at the record's location; the standard canViewCustomer rules. Update: any of: Customer Alarm Dot Com at the record's location; Customer Secure Net at the record's location; Customer at the record's location.

Field Type Writable Validation
interactive_services_id string (nullable) Read-only max length 255
adc_lead_id string (nullable) Update only min length 0

Legacy Funding

View: Customer Funding at the record's location. Update: Customer Funding at the record's location.

Field Type Writable Validation
funder_id integer (nullable) Update only —
funding_status_id integer (nullable) Update only —
funder_reason_id integer (nullable) Update only min 0
fund_submitted_date string (nullable) Update only —
fund_funded_date string (nullable) Update only —
fund_chargeback_date string (nullable) Update only —
fund_reinstate_date string (nullable) Update only —
fund_noc_date string (nullable) Update only —
fund_reversal_date string (nullable) Update only —
fund_deferred_date string (nullable) Update only —
fund_grade_info string (nullable) Update only max length 255
fund_amount string (nullable) Update only —
fund_amount_hold string (nullable) Update only —
fund_amount_bonus string (nullable) Update only —
fund_amount_received string (nullable) Update only —
fund_chargeback_amount string (nullable) Update only —
fund_reversal_amount string (nullable) Update only —
fund_deferred_amount string (nullable) Update only —

Install

View: customers — Customer Install Info at the record's location; leads — the standard canViewLead rules. Create: customers — Customer at the record's location; leads — Lead. Update: customers — Customer Install Info at the record's location; leads — the standard canModifyLead rules.

Field Type Writable Validation
install_appointment_id integer (nullable) Create, update min 0
is_installed boolean (nullable) Create, update —
service_two_way_voice boolean (nullable) Create, update —
service_aarp boolean (nullable) Create, update —
service_cellular_backup boolean (nullable) Create, update —
service_guard_response boolean (nullable) Create, update —
service_invoicing boolean (nullable) Create, update —
service_maintenance boolean (nullable) Create, update —
service_pulse boolean (nullable) Create, update —
service_tellular boolean (nullable) Create, update —

Confirmation Number

View: customers — Cust Conf Confirm Num at the record's location; leads — Cust Conf Confirm Num. Create: customers — Customer at the record's location; leads — Lead. Update: Customer Install Info at the record's location.

Field Type Writable Validation
confirmation_num string (nullable) Create, update max length 100

Receiver Number

View: customers — Cust Conf Receiver Num at the record's location; leads — Cust Conf Receiver Num. Create: customers — Customer at the record's location; leads — Lead. Update: Customer Install Info at the record's location.

Field Type Writable Validation
receiver_num string (nullable) Create, update max length 100

Abort Code

View: customers — Cust Conf Abort Code at the record's location; leads — Cust Conf Abort Code. Create: customers — Customer at the record's location; leads — Lead. Update: Customer Install Info at the record's location.

Field Type Writable Validation
abort_code string (nullable) Create, update —

Lead

View: the standard canViewLead rules. Create: customers — Customer at the record's location; leads — Lead. Update: the standard canModifyLead rules.

Field Type Writable Validation
lead_callback_date string (nullable) Create, update —
lead_disposition_id integer (nullable) Create, update min 0
lead_callcenter_notes string (nullable) Create, update —
lead_type_id integer (nullable) Create, update min 0
lead_comments string (nullable) Create, update —

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: fname, lname, business_name, business_contact, email, phone, city, state, zip, account_num, account_class_id, cancelled, sale_date_from, sale_date_to, created_from, created_to, lead_created_from, lead_created_to, 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 .../customers?sort= orders the list by: id, fname, lname, business_name, city, state, sale_date, created. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Includable relationships

On a single record, GET .../customers/{id}?include= accepts: notes, work_orders, tickets, equipment, billing, contacts, payments, credit_checks, invoices, invoice_recurring, funding, payables, workflows, lead_interactions, tags, udfs.

On the collection, GET .../customers?include= accepts: notes, work_orders, tickets. See Expanding related records for response shape and errors.

Related

Ask about the docs
Ask about the docs
Answers from the SecurityTrax documentation

Ask about a feature, setting, or workflow.

Answers come from the documentation. Double-check anything important. AI features are subject to the AI Terms.