Object Files

Reference for the object_files 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
Fetch	`GET /{profile}/user/v4/object_files/{id}`
Create	`POST /{profile}/user/v4/object_files`

Not available as a standard REST operation for this resource: listing, update, delete — such requests return 402 feature_not_enabled or 403 permission_denied.

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

How it works

object_files are the file attachments on a customer or lead — signed agreements, site photos, scanned paperwork — the same files that appear on the customer's Files tab. Each row stores the display name, the original filename (file, which drives the content type on download), and the owning record (object_type + object_id, managed by the server).

This resource is create + read: POST to attach a file, GET to read a file's metadata. Renaming and deleting remain on the v1 customer_files endpoints for now, as does downloading the stored bytes (GET /{profile}/user/v1/customer_files/{id}/download).

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

Attaching a file

POST /object_files with the owning customer in data.relationships.customer and the file bytes base64-encoded in the file_data attribute:

curl -X POST "https://portal.securitytrax.com/acme/user/v4/object_files" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "object_files",
      "relationships": {"customer": {"data": {"type": "customers", "id": 100}}},
      "attributes": {
        "name": "Signed agreement",
        "file": "agreement.pdf",
        "file_data": "JVBERi0xLjQg..."
      }
    }
  }'

Field	Required	Notes
`customer` (relationship)	Yes	The customer/lead the file attaches to — the record's permission context. Always type `customers`, for leads too.
`name`	Yes	Display name, 1–255 chars.
`file`	Yes	Original filename incl. extension, ≤ 255 chars — determines the download content type.
`file_data`	Yes	The file bytes, base64-encoded. Decoded size ≤ 20 MB. Write-only: never returned on any read.

The response is the created record's metadata — file_data is never echoed back, and the stored bytes are not readable through v4.

What you can and can't set

object_type / object_id are server-managed: the customer relationship sets the owner, and v4 creates are customer/lead files only (user, source, and template files stay on their v1 endpoints).
service_type / service_id are integration bookkeeping (e-sign providers etc.) — read-only.
status is managed by the platform (active on create).

Reading a customer's files

GET /object_files/{id} returns one file's metadata. For the list, read the parent with the files relationship where available, or use the v1 list endpoints; file_data and the stored bytes are never part of a v4 projection.

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.

File

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

Field	Type	Writable	Validation
`name`	string (nullable)	Create only	Required on create; max length 255
`file`	string (nullable)	Create only	Required on create; max length 255
`file_data`	string (nullable)	Create only	Required on create

Managed

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

Field	Type	Writable	Validation
`object_id`	integer (nullable)	Read-only	min 0
`service_type`	string (nullable)	Read-only	max length 45
`service_id`	integer (nullable)	Read-only	max 255
`status`	string (nullable)	Read-only	one of: `active`, `deleted`
`created_at`	string (nullable)	Read-only	—
`created_by`	integer	Read-only	—
`updated_at`	string (nullable)	Read-only	—
`updated_by`	integer	Read-only	—

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