Guide
Objects & records
One set of record endpoints works for every object in a workspace. Object types and their fields are discovered at runtime, so the same integration works with each workspace's own data model, including custom objects and custom fields, without code changes.
GET /v1/objects lists the object types the key's user can read. Use each entry's object_type in record URLs: /v1/objects/{object_type}/records.
| Kind | Examples | Notes |
|---|---|---|
| CRM | companies, contacts, deals | Customer relationship records and their associations. |
| Work items | work-items | Programs, projects, deliverables, tasks, and workspace-defined types share one object. The work_item_type_id field selects the type. |
| Built-in catalogs | Varies by workspace | Other built-in business objects the workspace has enabled. |
| Custom objects | Workspace-specific ids | Objects created in Object Manager (kind: "default"). They appear automatically. |
curl https://api.dev.preshos.com/v1/objects \
-H "Authorization: Bearer $PRESHOS_API_KEY"{
"data": [
{
"object_type": "companies",
"name": "Companies",
"singular_name": "Company",
"kind": "built_in",
"category": "crm",
"display_field": "name",
"capabilities": { "search": true, "create": true, "update": true, "delete": false },
"permissions": {
"create": { "allowed": true, "scopes": ["owned_by_user"] },
"read": { "allowed": true, "scopes": ["org_wide"] },
"update": { "allowed": true, "scopes": ["owned_by_team"] },
"delete": { "allowed": false, "scopes": [] }
}
}
]
}capabilitiessays what the object supports through the API, for everyone. Ifcapabilities.deleteis false, no key can delete its records.permissionsis advisory and specific to the key's user.scopestells you which records an action covers:owned_by_user(your records),owned_by_team(your teams' records), ororg_wide(every record). Every request is still authorized individually.- Pass
include_unreadable=trueto also list objects the user cannot read.
GET /v1/objects/{object_type} returns everything needed to read and write one object type: its fields, relationships, status workflow, and, for work items, the active work-item types. Fields the user cannot read are not listed.
curl https://api.dev.preshos.com/v1/objects/companies \
-H "Authorization: Bearer $PRESHOS_API_KEY"| Field property | Meaning |
|---|---|
key | The key used in fields for reads, writes, filters, and sorting. |
name | Display label in PRESHos. |
type | Data type, such as text, number, date, select, boolean, or reference. |
required | Must be provided when creating a record. |
editable | Can be written through the API. Read-only fields reject the whole write. |
storage | physical fields are columns: filterable and sortable. jsonb fields are custom fields stored under fields.custom_fields. |
options | Allowed values for select fields (value, label). |
constraints | Extra validation such as lengths or ranges, when defined. |
For work items, add ?work_item_type_id=deliverable (or any type id) to include the fields configured for that type.
Every record has the same envelope, whatever its object type:
{
"object_type": "companies",
"id": "48213",
"display": "Acme Corporation",
"status": "customer",
"owner_user_id": 17,
"created_at": "2026-09-02T14:11:08.000Z",
"updated_at": "2026-09-30T09:45:51.000Z",
"version": "9a1b2c3d4e5f60718293a4b5c6d7e8f9",
"fields": {
"name": "Acme Corporation",
"domain": "acme.com",
"industry": "Manufacturing"
}
}| Property | Meaning |
|---|---|
id | Canonical record id (a string). Use it in every record URL. |
display | The value of the object's display field, such as a name or title. |
status | Current status value or workflow status id. |
owner_user_id | Owning user id, when the object has an owner. Use GET /v1/users to resolve it. |
version | Opaque concurrency token. Send it as If-Match when updating. |
fields | Business fields keyed by field key. Unreadable fields are omitted. |
public_id, work_item_type_id | Work items only. See below. |
Retrieving one record (GET /v1/objects/{object_type}/records/{record_id}) returns every readable field. List and search endpoints return identity fields only unless you ask for specific fields with fields; see Querying.
Timestamps are ISO-8601 in UTC. Unknown properties may be added to responses at any time; ignore what you do not use.
Programs, projects, deliverables, tasks, and any workspace-defined types are all records of the single work-items object. The work_item_type_id field holds the type: program, project, deliverable, task, or a custom type id listed in the object definition's work_item_types.
- Creating a work item requires
fields.work_item_type_id. - Parent/child structure uses the
parent_work_item_idfield. A child created without a company inherits the nearest ancestor's company. - Each type has its own status workflow:
work_item_types[].workflowin the object definition. - Work items also return
public_id, the number PRESHos shows in app links. Always useidwith the API.
Reads are scoped in the database to what the user may read, so pagination and totals only ever include visible records:
| Read scope on the user's role | Records returned |
|---|---|
Own records (owned_by_user) | Records the user owns. |
Team records (owned_by_team) | Records owned by the user or by members of the user's teams. |
Workspace (org_wide) | Every record of the object type. |
Check permissions on GET /v1/objects to decide which actions to offer in your integration, and handle 403 and 404 on every call anyway. Teams come from GET /v1/teams.