# Knack

> Create, find, update and delete records in a Knack app, submit its forms and upload files, with the app's API key.

App · Databases · 18 actions. Web page: https://docs.lodol.com/docs/integrations/knack

## Actions

### Count records

Count an object's records, all of them or those matching a rule. Uses one API call.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Filter field (`field_key`, text): The field to filter on.
- Operator (`operator`, text): How to compare. Blank checks, 'is any' and the 'today' / 'current time' operators need no value. One of: `is`, `is not`, `contains`, `does not contain`, `starts with`, `ends with`, `is blank`, `is not blank`, `is any`, `higher than`, and 15 more. Default: `is`.
- Value (`value`, text): The value to compare with. To match a connected record, use the connection field with 'is' and the connected record's id. Dates use the field's own format, such as 09/24/2026.
- Range amount (`range_amount`, number): For 'is during the previous/next', 'is before the previous' and 'is after the next': how many units, such as 3. At least 1.
- Range unit (`range_unit`, text): For the 'is during ...' operators: the unit, such as days, weeks, months or years.
- Advanced filters (JSON) (`filters`, object): Optional extra rules in Knack's filter format, such as {"match": "or", "rules": [{"field": "field_1", "operator": "contains", "value": "Ltd"}]}. Combined with the rule above.
- Match (`match`, text): Whether records must match all rules or any rule. One of: `and` (All rules), `or` (Any rule). Default: `and`.

**Outputs**

- `object_key` (text)
- `total_records` (number)

**Example output**

```json
{
  "object_key": "object_1",
  "total_records": 12
}
```

### Create a record

Create a record in an object. Fields left out get their default value. Form record rules do not run.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Fields (`fields`, object, required): The new record's values. Fill in the fields to set and leave the rest blank. Name, Address, Email and Link values take JSON such as {"first": "Ada", "last": "Lovelace"}; a connection takes a list of record ids; a file or image field takes the id from 'Upload a file'; Yes/No takes true, false or kn-blank to clear it.

**Outputs**: A Knack record. Besides id it carries one key per field, such as field_1 (and field_1_raw when the format is 'both').

- `id` (text): The record id.

**Example output**

```json
{
  "field_1": "Acme Ltd",
  "field_2": "Customer",
  "field_3": 42,
  "id": "575482d691e16d4235adcdb6"
}
```

### Delete a record

Delete a record permanently.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Record ID (`record_id`, text, required): The record to delete. A Builder URL containing the id also works.

**Outputs**

- `deleted` (true/false)
- `id` (text)

**Example output**

```json
{
  "deleted": true,
  "id": "575482d691e16d4235adcdb6"
}
```

### Delete a record through a view

Delete a record through a table, list, search, calendar or details view that has a delete link.

**Inputs**

- Page (`scene_key`, text, required): The page (scene) the view is on, such as scene_1.
- View (`view_key`, text, required): A view with a delete link.
- Record ID (`record_id`, text, required): The record to delete. A Builder URL containing the id also works.

**Outputs**

- `deleted` (true/false)
- `id` (text)

**Example output**

```json
{
  "deleted": true,
  "id": "575482d691e16d4235adcdb6"
}
```

### Find or create a record

Return the first record whose field equals a value, or create one with that value (plus any other fields) if none exists.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Match field (`match_field`, text, required): The field to look the record up by, such as an email.
- Match value (`match_value`, text, required): The value that field must equal.
- Fields if created (`fields`, object): Other values to set only when a new record is created. The match field is set for you. Fill in the fields to set and leave the rest blank. Name, Address, Email and Link values take JSON such as {"first": "Ada", "last": "Lovelace"}; a connection takes a list of record ids; a file or image field takes the id from 'Upload a file'; Yes/No takes true, false or kn-blank to clear it.

**Outputs**

- `created` (true/false)
- `record` (object): A Knack record. Besides id it carries one key per field, such as field_1 (and field_1_raw when the format is 'both').

**Example output**

```json
{
  "created": false,
  "record": {
    "field_1": "Acme Ltd",
    "field_2": "Customer",
    "field_3": 42,
    "id": "575482d691e16d4235adcdb6"
  }
}
```

### Get a record

Fetch one record by its id.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Record ID (`record_id`, text, required): The record's id. A Builder URL containing the id also works.

**Outputs**: A Knack record. Besides id it carries one key per field, such as field_1 (and field_1_raw when the format is 'both').

- `id` (text): The record id.

**Example output**

```json
{
  "field_1": "Acme Ltd",
  "field_2": "Customer",
  "field_3": 42,
  "id": "575482d691e16d4235adcdb6"
}
```

### Get a record from a view

Fetch one record as a view shows it.

**Inputs**

- Page (`scene_key`, text, required): The page (scene) the view is on, such as scene_1.
- View (`view_key`, text, required): A table, list, search, calendar, details or edit form view.
- Record ID (`record_id`, text, required): The record's id. A Builder URL containing the id also works.

**Outputs**: A Knack record. Besides id it carries one key per field, such as field_1 (and field_1_raw when the format is 'both').

- `id` (text): The record id.

**Example output**

```json
{
  "field_1": "Acme Ltd",
  "field_2": "Customer",
  "field_3": 42,
  "id": "575482d691e16d4235adcdb6"
}
```

### List fields

List an object's fields with the field_N key each one uses in records, its type and, for choices, its options.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.

**Outputs**

- `fields` (list)
- `object_key` (text)
- `object_name` (text)
- `total` (number)

**Example output**

```json
{
  "fields": [
    {
      "key": "field_1",
      "name": "Name",
      "read_only": false,
      "required": true,
      "type": "short_text",
      "unique": false
    }
  ],
  "object_key": "object_1",
  "object_name": "Companies",
  "total": 1
}
```

### List objects

List the app's objects (tables) with their keys and record counts, read from the app's published schema.

**Inputs**: None.

**Outputs**

- `application_id` (text)
- `application_name` (text)
- `objects` (list)
- `total` (number)

**Example output**

```json
{
  "application_id": "5d79512148c4af00106d1507",
  "application_name": "Customer Portal",
  "objects": [
    {
      "display_field": "field_1",
      "field_count": 3,
      "is_user_object": false,
      "key": "object_1",
      "name": "Companies",
      "record_count": 12
    }
  ],
  "total": 1
}
```

### List records

Return one page of an object's records.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Records per page (`rows_per_page`, number): How many records to return, 1-1000. From 1 to 1000. Default: `25`.
- Page number (`page`, number): Which page of results to return, starting at 1. At least 1. Default: `1`.
- Sort by field (`sort_field`, text): The field to sort by. Leave blank for Knack's default order.
- Sort order (`sort_order`, text): Ascending or descending, when a sort field is chosen. One of: `asc` (Ascending), `desc` (Descending). Default: `asc`.
- Value format (`format`, text): Raw gives structured values (best for later steps), HTML the formatted text Knack displays, Both gives field_N as HTML and field_N_raw as raw. One of: `raw`, `both`, `html`. Default: `raw`.

**Outputs**

- `current_page` (number)
- `records` (list)
- `total_pages` (number)
- `total_records` (number)

**Example output**

```json
{
  "current_page": 1,
  "records": [
    {
      "field_1": "Acme Ltd",
      "field_2": "Customer",
      "field_3": 42,
      "id": "575482d691e16d4235adcdb6"
    }
  ],
  "total_pages": 1,
  "total_records": 1
}
```

### List records in a view

Return one page of records exactly as a table, list, search or calendar view shows them, with only the view's fields.

**Inputs**

- Page (`scene_key`, text, required): The page (scene) the view is on, such as scene_1.
- View (`view_key`, text, required): A table, list, search or calendar view.
- Records per page (`rows_per_page`, number): How many records to return, 1-1000. From 1 to 1000. Default: `25`.
- Page number (`page`, number): Which page of results to return, starting at 1. At least 1. Default: `1`.
- Sort by field (`sort_field`, text): The field to sort by. Leave blank for Knack's default order.
- Sort order (`sort_order`, text): Ascending or descending, when a sort field is chosen. One of: `asc` (Ascending), `desc` (Descending). Default: `asc`.
- Value format (`format`, text): Raw gives structured values (best for later steps), HTML the formatted text Knack displays, Both gives field_N as HTML and field_N_raw as raw. One of: `raw`, `both`, `html`. Default: `raw`.
- Parent page slug (`parent_page_slug`, text): For a view on a child page only: the page slug from its URL, such as company-details.
- Parent record ID (`parent_record_id`, text): For a child page only: the record the page is for.

**Outputs**

- `current_page` (number)
- `records` (list)
- `total_pages` (number)
- `total_records` (number)

**Example output**

```json
{
  "current_page": 1,
  "records": [
    {
      "field_1": "Acme Ltd",
      "field_2": "Customer",
      "field_3": 42,
      "id": "575482d691e16d4235adcdb6"
    }
  ],
  "total_pages": 1,
  "total_records": 1
}
```

### List views

List the app's pages and the views on them, with each view's type, object and whether its page needs a login.

**Inputs**

- Page (`scene_key`, text): Only this page's views. Leave blank for all pages.

**Outputs**

- `total` (number)
- `views` (list)

**Example output**

```json
{
  "total": 1,
  "views": [
    {
      "object_key": "object_1",
      "parent_scene_slug": null,
      "requires_login": false,
      "scene_key": "scene_1",
      "scene_name": "Companies",
      "scene_slug": "companies",
      "view_key": "view_1",
      "view_name": "Companies table",
      "view_type": "table"
    }
  ]
}
```

### Log in an app user

Check an app user's email and password and return their record id and user roles. Leave both blank to check the app user saved on the connection.

**Inputs**

- Email (`email`, text): The app user's email address.
- Password (`password`, text): The app user's password.

**Outputs**

- `approval_status` (text)
- `email` (text)
- `id` (text)
- `logged_in` (true/false)
- `profile_keys` (list)
- `profile_objects` (list)
- `values` (object)

**Example output**

```json
{
  "approval_status": "approved",
  "email": "ada@example.com",
  "id": "5d65e8b2a1c3f40011223344",
  "logged_in": true,
  "profile_keys": [
    "profile_1"
  ],
  "profile_objects": [
    {
      "entry_id": "5d65e8b2a1c3f40011223344",
      "object": "object_2"
    }
  ],
  "values": {}
}
```

### Search records

Find an object's records matching a field rule, optionally combined with more rules in Knack's filter format.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Filter field (`field_key`, text): The field to filter on.
- Operator (`operator`, text): How to compare. Blank checks, 'is any' and the 'today' / 'current time' operators need no value. One of: `is`, `is not`, `contains`, `does not contain`, `starts with`, `ends with`, `is blank`, `is not blank`, `is any`, `higher than`, and 15 more. Default: `is`.
- Value (`value`, text): The value to compare with. To match a connected record, use the connection field with 'is' and the connected record's id. Dates use the field's own format, such as 09/24/2026.
- Range amount (`range_amount`, number): For 'is during the previous/next', 'is before the previous' and 'is after the next': how many units, such as 3. At least 1.
- Range unit (`range_unit`, text): For the 'is during ...' operators: the unit, such as days, weeks, months or years.
- Advanced filters (JSON) (`filters`, object): Optional extra rules in Knack's filter format, such as {"match": "or", "rules": [{"field": "field_1", "operator": "contains", "value": "Ltd"}]}. Combined with the rule above.
- Match (`match`, text): Whether records must match all rules or any rule. One of: `and` (All rules), `or` (Any rule). Default: `and`.
- Records per page (`rows_per_page`, number): How many records to return, 1-1000. From 1 to 1000. Default: `25`.
- Page number (`page`, number): Which page of results to return, starting at 1. At least 1. Default: `1`.
- Sort by field (`sort_field`, text): The field to sort by. Leave blank for Knack's default order.
- Sort order (`sort_order`, text): Ascending or descending, when a sort field is chosen. One of: `asc` (Ascending), `desc` (Descending). Default: `asc`.
- Value format (`format`, text): Raw gives structured values (best for later steps), HTML the formatted text Knack displays, Both gives field_N as HTML and field_N_raw as raw. One of: `raw`, `both`, `html`. Default: `raw`.

**Outputs**

- `current_page` (number)
- `records` (list)
- `total_pages` (number)
- `total_records` (number)

**Example output**

```json
{
  "current_page": 1,
  "records": [
    {
      "field_1": "Acme Ltd",
      "field_2": "Customer",
      "field_3": 42,
      "id": "575482d691e16d4235adcdb6"
    }
  ],
  "total_pages": 1,
  "total_records": 1
}
```

### Submit a form

Create a record through a Form view, running the form's record rules (emails, connected updates). Only the form's own fields are saved.

**Inputs**

- Page (`scene_key`, text, required): The page (scene) the view is on, such as scene_1.
- View (`view_key`, text, required): A Form view that adds records.
- Fields (`fields`, object, required): The form's values. Fill in the fields to set and leave the rest blank. Name, Address, Email and Link values take JSON such as {"first": "Ada", "last": "Lovelace"}; a connection takes a list of record ids; a file or image field takes the id from 'Upload a file'; Yes/No takes true, false or kn-blank to clear it.

**Outputs**

- `record` (object): A Knack record. Besides id it carries one key per field, such as field_1 (and field_1_raw when the format is 'both').
- `submit_key` (text)

**Example output**

```json
{
  "record": {
    "field_1": "Acme Ltd",
    "field_2": "Customer",
    "field_3": 42,
    "id": "575482d691e16d4235adcdb6"
  },
  "submit_key": "submit_1"
}
```

### Update a record

Change some of a record's fields. Blank fields are not touched.

**Inputs**

- Object (`object_key`, text, required): The Knack object (table), such as object_1.
- Record ID (`record_id`, text, required): The record to change. A Builder URL containing the id also works.
- Fields (`fields`, object, required): The values to change. Fill in the fields to set and leave the rest blank. Name, Address, Email and Link values take JSON such as {"first": "Ada", "last": "Lovelace"}; a connection takes a list of record ids; a file or image field takes the id from 'Upload a file'; Yes/No takes true, false or kn-blank to clear it.

**Outputs**: A Knack record. Besides id it carries one key per field, such as field_1 (and field_1_raw when the format is 'both').

- `id` (text): The record id.

**Example output**

```json
{
  "field_1": "Acme Ltd",
  "field_2": "Customer",
  "field_3": 42,
  "id": "575482d691e16d4235adcdb6"
}
```

### Update a record through a view

Update a record through an edit form, or a table or search view with inline editing on. Fields not in the view are not changed.

**Inputs**

- Page (`scene_key`, text, required): The page (scene) the view is on, such as scene_1.
- View (`view_key`, text, required): An edit form, or a table or search with inline editing on.
- Record ID (`record_id`, text, required): The record to change. A Builder URL containing the id also works.
- Fields (`fields`, object, required): The values to change. Fill in the fields to set and leave the rest blank. Name, Address, Email and Link values take JSON such as {"first": "Ada", "last": "Lovelace"}; a connection takes a list of record ids; a file or image field takes the id from 'Upload a file'; Yes/No takes true, false or kn-blank to clear it.

**Outputs**

- `record` (object): A Knack record. Besides id it carries one key per field, such as field_1 (and field_1_raw when the format is 'both').
- `submit_key` (text)

**Example output**

```json
{
  "record": {
    "field_1": "Acme Ltd",
    "field_2": "Customer",
    "field_3": 42,
    "id": "575482d691e16d4235adcdb6"
  },
  "submit_key": "submit_1"
}
```

### Upload a file

Upload a file or image to the app. Put the returned id in a file or image field with Create or Update a record. Knack needs a separate upload for each field it is attached to.

**Inputs**

- Upload as (`asset_type`, text, required): File for a file field, Image for an image field. One of: `file`, `image`. Default: `file`.
- File (`file`, text): Upload a file or pick one from an earlier step. Leave blank to upload the text below as a file instead.
- Text content (`text_content`, text): Text to upload as a file, such as a CSV built in an earlier step. Used only when no file is given.
- File name (`filename`, text): The name Knack shows, such as report.csv. Defaults to the uploaded file's own name.

**Outputs**

- `filename` (text)
- `id` (text)
- `public_url` (text)
- `size` (number)
- `thumb_url` (text)
- `type` (text)

**Example output**

```json
{
  "filename": "report.csv",
  "id": "5e2f1c9a8b7d6e5f4a3b2c1d",
  "public_url": "https://s3.amazonaws.com/assets/report.csv",
  "size": 1024,
  "thumb_url": "",
  "type": "file"
}
```