---
title: "Save a view"
description: "filters uses the same field / op / value grammar the list endpoints take as ?<field>[<op>]=<value>, and is validated against THAT list's own field and operator allow-list — a view cannot be…"
canonical_url: "https://twominutebilling.com/help/developers/api-reference/list-views/save-a-view"
---
# Save a view

> filters uses the same field / op / value grammar the list endpoints take as ?<field>[<op>]=<value>, and is validated against THAT list's own field and operator allow-list — a view cannot be…

<api-operation method="POST" path="/v1/list_views">
<template v-slot:docs="">

`filters` uses the same `field` / `op` / `value` grammar the list endpoints take as `?<field>[<op>]=<value>`, and is validated against THAT list's own field and operator allow-list — a view cannot be saved holding a filter the list would later reject. A view must carry at least one of filters / search / sort / hidden_columns; an empty one would sit in the dropdown claiming to narrow something.

## Headers

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Idempotency-Key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Safely retry writes — repeats return the original response. If a write FAILED after it had already taken effect, that failure is what repeats: the key is spent, and a new attempt needs a new key.
    </td>
  </tr>
</tbody>
</table>

## Body

The request body is **required**.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        entity
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The kind of list the view is for.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        business
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Omit for an org-level list
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The list view's name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        visibility
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      <code>
        private
      </code>
      
       is scoped to the caller; only the owner may ever edit or delete either kind. One of <code>
        private
      </code>
      
      , <code>
        everyone
      </code>
      
      . Defaults to <code>
        "private"
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filters
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The filters saved with the view.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filters.field
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The field to filter on.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filters.op
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The filter operator.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filters.value
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Comma-separated for <code>
        in
      </code>
      
      /<code>
        not_in
      </code>
      
      /<code>
        between
      </code>
      
      ; a day count for <code>
        in_last
      </code>
      
      /<code>
        in_next
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The free-text search saved with the view.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_field
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The field the view sorts by.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_desc
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      True to sort in descending order.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hidden_columns
      </code>
    </td>
    
    <td>
      <code>
        array of string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Column ids the view hides. null means the list's own defaults.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        is_default
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The view YOU land on for this list. Per owner — at most one.
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        list_view
      </code>
      
      . One of <code>
        list_view
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      lv_…
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        entity
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Which list the view belongs to (subscriptions, invoices, …).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The list view's name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        owner
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Who saved it. null for a view that belongs to the business itself.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        is_mine
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether the CALLER owns it — only the owner may rename, re-share, default or delete. Computed per request, never stored.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        visibility
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Who can see this list view. One of <code>
        private
      </code>
      
      , <code>
        business
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filters
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The saved filter set, in the list's own filter vocabulary.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The free-text search saved with the view.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_field
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The field the view sorts by.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_desc
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the view sorts in descending order.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hidden_columns
      </code>
    </td>
    
    <td>
      <code>
        array of string
      </code>
    </td>
    
    <td>
      Column ids the view hides. null means the list's own defaults.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        is_default
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The view its owner lands on for this list. At most one per owner.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        created_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the list view was created (ISO-8601 UTC).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        updated_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the list view was last changed (ISO-8601 UTC).
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        201
      </code>
    </td>
    
    <td>
      Created
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Invalid filter field/operator/value, or an empty view
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      No such business
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        409
      </code>
    </td>
    
    <td>
      You already have a view by that name on this list
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl -X POST "$TMBILLING_URL/v1/list_views" \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customer",
    "name": "Active subscriptions"
  }'
```

</template>

<template v-slot:response="">
<code-group>

```json [201 Created]
{
  "object": "list_view",
  "id": "view_XXXXXXXXXXXX01",
  "entity": "customer",
  "name": "Active subscriptions",
  "owner": "usr_XXXXXXXXXXXX01",
  "is_mine": false,
  "visibility": "private",
  "filters": [],
  "search": "ada",
  "sort_field": "created_at",
  "sort_desc": false,
  "hidden_columns": [
    "Hidden column"
  ],
  "is_default": false,
  "created_at": "2026-03-14T09:30:00Z",
  "updated_at": "2026-03-14T09:30:00Z"
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid filter field/operator/value, or an empty view"
  }
}
```

```json [404 Not Found]
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such business"
  }
}
```

```json [409 Conflict]
{
  "error": {
    "type": "conflict_error",
    "message": "You already have a view by that name on this list"
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.