Object Udfs

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

object_udfs are custom field values — the value a customer (or other object) holds for a user-defined field (UDF) definition. This resource covers customer custom fields; gated by the customer's own view/modify access (setting a customer's UDF value is modifying that customer). UDF definitions (the fields themselves) are managed in the admin UI and are not part of this resource.

object_udfs has a composite primary key (udf_id, object_id) and no row id. A value is identified by the pair (which field, which customer), not by a surrogate id — so there is no GET/PATCH/DELETE /object_udfs/{id}. You read values (list + customers?include=udfs) and set/clear them through the two collection actions below.

Setting a value

POST /object_udfs/set upserts a customer's value for a field: it updates the existing value if the customer already has one for that field, otherwise it creates it.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/object_udfs/set" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"object_id":100,"udf_id":12,"value":"Gold"}}}'

Returns the resulting object_udfs row (201). Requires the same access as modifying the customer; an invalid value for the field's type, or a udf_id that isn't a customer field, returns 422; a missing customer returns 422.

Clearing a value

POST /object_udfs/clear blanks the customer's value for a field (the value goes empty; the row stays active, matching how SecurityTrax removes a UDF value). Clearing a field the customer has no value for returns 404.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/object_udfs/clear" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"object_id":100,"udf_id":12}}}'

Reading values

GET /object_udfs?object_id={customerId} lists a customer's custom-field values (filters: object_id, udf_id; sort: udf_id, object_id, value, created_at; ?count_only=true for the total). A customer's values are also reachable via GET /customers/{id}?include=udfs.

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.

Customer Udf

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

Customer Equipment Udf

View: Customer Equipment at the record's location. Create: Customer Equipment at the record's location. Update: Customer Equipment at the record's location.

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: object_id, udf_id. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../object_udfs?sort= orders the list by: udf_id, object_id, value, 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 — tokens and the Authorization header.