User Rep Numbers

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

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

How it works

user_rep_numbers are a user's sales-rep registration numbers — the license/registration number a rep uses, scoped by domain:

`domain`	`identifier` means	Example
`location_id`	A location id, or `All` for every location	`"identifier": "1"`
`state`	A two-letter state, or `All` for every state	`"identifier": "UT"`

Full CRUD: create, read, edit (PATCH), delete. The target user is linked on create through the user relationship. Reading requires access to view the user and no rep-numbers-information restriction on your account; writing additionally requires access to modify the user.

Adding a rep number

curl -X POST "https://portal.securitytrax.com/acme/user/v4/user_rep_numbers" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"domain":"state","identifier":"UT","number":"REG-88421"},"relationships":{"user":{"data":{"type":"users","id":42}}}}}'

Field	Required	Notes
`user` (relationship)	Yes	The user the rep number belongs to.
`domain`	Yes	`location_id` or `state`.
`identifier`	Yes	Must match the domain: a real location id / two-letter state, or `All`. A mismatch returns `422`.
`number`	Yes	The registration number, ≤ 100 chars.

Editing / deleting

PATCH /user_rep_numbers/{id} edits a rep number; DELETE /user_rep_numbers/{id} soft-deletes it.

Reading rep numbers

GET /user_rep_numbers?user_id={userId} lists a user's rep numbers (filters: user_id, domain; sort: id, user_id, domain, created_at; ?count_only=true for the total). Reads are company-wide — if you hold the User view permission anywhere (and aren't restricted from rep-number information), you can read any user's rep numbers, matching the web app.

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.

Rep Number

View: the standard canViewUserRepNumbers rules. Create: the standard canManageUserRepNumbers rules. Update: the standard canManageUserRepNumbers rules.

Field	Type	Writable	Validation
`user_id`	integer	Create, update	min 0
`domain`	string (nullable)	Create, update	Required on create; one of: `location_id`, `state`
`identifier`	string (nullable)	Create, update	Required on create; max length 100
`number`	string (nullable)	Create, update	Required on create; max length 100
`status`	string (nullable)	Read-only	one of: `active`, `deleted`
`created_at`	string (nullable)	Read-only	—
`created_by`	integer (nullable)	Read-only	—
`updated_at`	string (nullable)	Read-only	—
`updated_by`	integer (nullable)	Read-only	—

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

Sorting

GET .../user_rep_numbers?sort= orders the list by: id, user_id, domain, created_at. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Requests and Responses — envelope, errors, pagination, and rate limits.
Authentication — tokens and the Authorization header.