Saved Views API

Saved views let users persist custom column configurations and filter sets for entity lists (contacts, organisations, households, and tasks). Each user can save up to five views per entity type. One view can be marked as a favorite and is used as the default for that entity.

All endpoints are under the /api/v1/views base path and require a standard authenticated session with one of the roles: TENANT_STAFF, TENANT_ADMIN, SYSTEM_ADMIN, SYSTEM_STAFF, PARTNER_ADMIN, or PARTNER_STAFF.

User view preferences

User preferences are stored per authenticated user and control display behaviour across all entity views.

The preference response contains a single flag:

{
  "suppressUnsavedChangesModal": false
}

To update preferences, send the same structure with the desired value. The suppressUnsavedChangesModal field is required.

curl "https://api.altafid.dev.altafid.net/api/v1/views/preferences" \
  -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-type: TENANT_STAFF" \
  --data '{
    "suppressUnsavedChangesModal": true
  }'

List views for an entity

GET/api/v1/views/{entityType}

Returns all saved views for the authenticated user and the given entity type. entityType must be one of CONTACT, ORGANISATION, HOUSEHOLD, or TASK. For this integration guide, the primary entity types are CONTACT, ORGANISATION, and HOUSEHOLD.

curl "https://api.altafid.dev.altafid.net/api/v1/views/CONTACT" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-type: TENANT_STAFF"

{
  "views": [
    {
      "viewUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Active Prospects",
      "isFavorite": true,
      "columns": [
        { "field": "firstName", "visible": true, "order": 0 },
        { "field": "paternalLastName", "visible": true, "order": 1 },
        { "field": "stage", "visible": true, "order": 2 }
      ],
      "filters": [
        { "field": "contactType", "operator": "equals", "value": "ACTIVE" }
      ],
      "createdAt": "2026-01-15T10:30:00",
      "updatedAt": "2026-03-20T14:45:00",
      "version": 3
    }
  ],
  "favoriteViewUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "entityType": "CONTACT",
  "maxViewsAllowed": 5
}

To fetch a single view by its UUID:

GET/api/v1/views/view/{viewUuid}

Returns a single SavedViewResponse with the same structure as one entry in the list above.

Create a view

POST/api/v1/views/{entityType}

Creates a new view for the given entity type. The request body is optional; if omitted or if name is blank, a name is auto-generated as "View N" where N is the next available number. Returns 201 Created with the full view object.

curl "https://api.altafid.dev.altafid.net/api/v1/views/CONTACT" \
  -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-type: TENANT_STAFF" \
  --data '{ "name": "High Value Clients" }'

A newly created view starts with default columns and no filters. Use the update endpoint to configure columns and filters.

Update and rename a view

PUT/api/v1/views/view/{viewUuid} replaces the column and filter configuration of an existing view. The version field is required for optimistic locking — submit the version you received from the last read and the server will reject the update with 409 if another update has occurred since then.

{
  "columns": [
    { "field": "firstName", "visible": true, "order": 0 },
    { "field": "paternalLastName", "visible": true, "order": 1 },
    { "field": "preferredEmail", "visible": true, "order": 2 },
    { "field": "stage", "visible": false, "order": 3 }
  ],
  "filters": [
    { "field": "segment", "operator": "equals", "value": "Retail" }
  ],
  "version": 3
}

To rename a view without touching its columns or filters, use the lighter-weight patch endpoint:

PATCH/api/v1/views/view/{viewUuid}/rename

{
  "name": "Premium Retail Clients"
}

The name field is required and must not be blank. Maximum 100 characters.

Duplicate a view

POST/api/v1/views/view/{viewUuid}/duplicate

Creates a copy of the specified view. If the request body is omitted or name is blank, the duplicate is named "Source Name Copy" (or "Source Name Copy N" if that name already exists). Returns 201 Created.

{
  "name": "Active Prospects — Copy"
}

Set a view as favorite

PATCH/api/v1/views/view/{viewUuid}/favorite

Marks the given view as the user's favorite for its entity type. Any previously set favorite is automatically unset. No request body is required. Returns the updated view with isFavorite: true.

curl "https://api.altafid.dev.altafid.net/api/v1/views/view/a1b2c3d4-e5f6-7890-abcd-ef1234567890/favorite" \
  -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-type: TENANT_STAFF"

Delete a view

DELETE/api/v1/views/view/{viewUuid}

Deletes the view and returns a response that identifies which view should become the new active view and which should become the new favorite (the service automatically promotes the next suitable view).

{
  "deletedViewUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "newActiveViewUuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "newFavoriteViewUuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

If no views remain for that entity type after the deletion, newActiveViewUuid and newFavoriteViewUuid will be null.