# Kizeo Forms

> Work with Kizeo Forms, the mobile forms app: read forms and their submissions, push pre-filled forms to field staff, manage users and groups, and update external lists. Start a workflow when a form is submitted.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/kizeo-forms

## Actions

### Add user

Add a user to the Kizeo Forms account. Each user may take one of your Kizeo licences.

**Inputs**

- Login (`login`, text, required): The name the user signs in with. It must be unique in the account.
- Password (`password`, text, required): The user's first password; they can change it in Kizeo.
- First name (`first_name`, text, required): The user's first name.
- Last name (`last_name`, text, required): The user's last name.
- Email (`email`, text): The user's email address.
- Phone (`phone`, text): The user's phone number.
- Administrator (`admin`, true/false): Whether the user administers the Kizeo account. Defaults to no. Default: `false`.
- Fills in forms (`form_user`, true/false): Whether the user fills in forms on the app. Defaults to yes. Default: `true`.

**Outputs**

- `user` (object): The user as created
- `user_id` (text): The new user's id

**Example output**

```json
{
  "user": {
    "admin": false,
    "email": "jeanne@example.com",
    "first_name": "Jeanne",
    "form_user": true,
    "id": "1002",
    "last_name": "Dupont",
    "login": "jdupont",
    "phone": ""
  },
  "user_id": "1002"
}
```

### Add user to group

Add a user to a group, as a member or as a group leader.

**Inputs**

- Group (`group_id`, text, required): The group. Pick one, or give its id.
- User (`kizeo_user_id`, text, required): The Kizeo Forms user. Pick one, or give their id.
- As (`role`, text): A member of the group, or one of its group leaders. Defaults to member. One of: `member` (Member (default)), `leader` (Group leader). Default: `member`.

**Outputs**

- `added` (true/false): True once added
- `group_id` (text): The group
- `message` (text): Kizeo's own message, if any
- `role` (text): member or leader
- `user_id` (text): The user

**Example output**

```json
{
  "added": true,
  "group_id": "301",
  "message": "",
  "role": "member",
  "user_id": "1001"
}
```

### Create group

Create a group, at the top level or inside another group.

**Inputs**

- Name (`name`, text, required): The group's name.
- Inside group (`parent_group_id`, text): The group to put it in. Leave empty for the top level.

**Outputs**

- `group` (object): The group as created
- `group_id` (text): The new group's id

**Example output**

```json
{
  "group": {
    "id": "301",
    "name": "North team",
    "parent_group_id": ""
  },
  "group_id": "301"
}
```

### Delete group

Delete a group. Its users stay in the account.

**Inputs**

- Group (`group_id`, text, required): The group. Pick one, or give its id.

**Outputs**

- `deleted` (true/false): True once deleted
- `group_id` (text): The group deleted
- `message` (text): Kizeo's own message, if any

**Example output**

```json
{
  "deleted": true,
  "group_id": "301",
  "message": ""
}
```

### Delete user

Delete a user from the Kizeo Forms account.

**Inputs**

- User (`kizeo_user_id`, text, required): The Kizeo Forms user. Pick one, or give their id.

**Outputs**

- `deleted` (true/false): True once deleted
- `message` (text): Kizeo's own message, if any
- `user_id` (text): The user deleted

**Example output**

```json
{
  "deleted": true,
  "message": "",
  "user_id": "1001"
}
```

### Get external list

Get every item of an external list, such as code:label lines.

**Inputs**

- External list (`list_id`, text, required): The external list. Pick one, or give its id.

**Outputs**

- `item_count` (number): How many items
- `items` (list): Its items
- `list` (object): The external list

**Example output**

```json
{
  "item_count": 2,
  "items": [
    "ACME:Acme",
    "GLOBEX:Globex"
  ],
  "list": {
    "id": "7001",
    "items": [
      "ACME:Acme",
      "GLOBEX:Globex"
    ],
    "name": "Customers",
    "update_time": "2026-09-30 17:00:00"
  }
}
```

### Get form

Get a form's definition, with each field's id, caption and type. Use the field ids to read answers or fill in a pushed form.

**Inputs**

- Form (`form_id`, text, required): The form. Pick one, or give its id from an earlier step.

**Outputs**

- `field_count` (number): How many fields
- `fields` (list): The form's fields
- `form` (object): The form's definition

**Example output**

```json
{
  "field_count": 2,
  "fields": [
    {
      "caption": "Customer",
      "id": "customer",
      "list_id": "",
      "required": true,
      "type": "text"
    },
    {
      "caption": "Photo",
      "id": "photo",
      "list_id": "",
      "required": false,
      "type": "photo"
    }
  ],
  "form": {
    "exports": [],
    "fields": {
      "customer": {
        "caption": "Customer",
        "required": true,
        "type": "text"
      },
      "photo": {
        "caption": "Photo",
        "required": false,
        "type": "photo"
      }
    },
    "id": "512345",
    "name": "Site inspection",
    "options": {}
  }
}
```

### Get group

Get a group with its users, group leaders and child groups.

**Inputs**

- Group (`group_id`, text, required): The group. Pick one, or give its id.

**Outputs**

- `group` (object): The group
- `leaders` (list): The group's leaders
- `users` (list): The group's users

**Example output**

```json
{
  "group": {
    "children": [],
    "id": "301",
    "leaders": [],
    "name": "North team",
    "parent_group_id": "",
    "users": [
      {
        "admin": false,
        "create_time": "2025-01-10 08:00:00",
        "email": "jeanne@example.com",
        "first_name": "Jeanne",
        "form_user": true,
        "id": "1001",
        "is_current_user": false,
        "last_name": "Dupont",
        "leader_group": false,
        "login": "jdupont",
        "phone": "+33600000000"
      }
    ]
  },
  "leaders": [],
  "users": [
    {
      "admin": false,
      "create_time": "2025-01-10 08:00:00",
      "email": "jeanne@example.com",
      "first_name": "Jeanne",
      "form_user": true,
      "id": "1001",
      "is_current_user": false,
      "last_name": "Dupont",
      "leader_group": false,
      "login": "jdupont",
      "phone": "+33600000000"
    }
  ]
}
```

### Get submission

Get one submission in full: who sent it, when, and every answer.

**Inputs**

- Form (`form_id`, text, required): The form. Pick one, or give its id from an earlier step.
- Submission ID (`data_id`, text, required): The submission's id (_id), from 'Search submissions' or a trigger.

**Outputs**

- `submission` (object): The submission
- `values` (object): Each answer's value, by field id

**Example output**

```json
{
  "submission": {
    "answer_time": "2026-10-20 14:01:58",
    "create_time": "2026-10-20 14:02:11",
    "fields": {
      "customer": {
        "type": "text",
        "value": "Acme"
      }
    },
    "form_id": "512345",
    "id": "98765432",
    "update_time": "2026-10-20 14:02:11",
    "user_id": "1001"
  },
  "values": {
    "customer": "Acme"
  }
}
```

### List external lists

List the external lists (the choices offered in forms' list fields) the connected user can see.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `lists` (list): The external lists

**Example output**

```json
{
  "count": 1,
  "lists": [
    {
      "id": "7001",
      "name": "Customers",
      "update_time": "2026-09-30 17:00:00"
    }
  ]
}
```

### List forms

List every form the connected user can see, with its id and name.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `forms` (list): The forms

**Example output**

```json
{
  "count": 1,
  "forms": [
    {
      "id": "512345",
      "name": "Site inspection",
      "update_time": "2026-10-01 09:00:00"
    }
  ]
}
```

### List groups

List every group in the Kizeo Forms account.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `groups` (list): The groups

**Example output**

```json
{
  "count": 1,
  "groups": [
    {
      "id": "301",
      "name": "North team",
      "parent_group_id": ""
    }
  ]
}
```

### List unread submissions

List a form's submissions not yet marked as read under a read marker, in full. Mark them read afterwards with 'Mark submissions as read'.

**Inputs**

- Form (`form_id`, text, required): The form. Pick one, or give its id from an earlier step.
- Read marker (`marker`, text, required): A name for what this workflow does with the submissions, such as lodol_invoices. Kizeo remembers which submissions are read separately for each name, so other tools reading the same form aren't affected.
- At most (`limit`, number): How many to return, 1 to 500. Defaults to 50. From 1 to 500.
- Include edited (`include_updated`, true/false): Also return read submissions that were changed since. Default: `false`.

**Outputs**

- `count` (number): How many
- `data_ids` (list): Their ids, to mark as read
- `submissions` (list): The unread submissions

**Example output**

```json
{
  "count": 1,
  "data_ids": [
    "98765432"
  ],
  "submissions": [
    {
      "_answer_time": "2026-10-20 14:01:58",
      "_create_time": "2026-10-20 14:02:11",
      "_form_id": "512345",
      "_id": "98765432",
      "_record_number": "42",
      "_update_time": "2026-10-20 14:02:11",
      "_user_id": "1001",
      "_user_name": "Jeanne Dupont"
    }
  ]
}
```

### List users

List every user in the Kizeo Forms account, with their login, name, email and rights.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `users` (list): The users

**Example output**

```json
{
  "count": 1,
  "users": [
    {
      "admin": false,
      "create_time": "2025-01-10 08:00:00",
      "email": "jeanne@example.com",
      "first_name": "Jeanne",
      "form_user": true,
      "id": "1001",
      "is_current_user": false,
      "last_name": "Dupont",
      "leader_group": false,
      "login": "jdupont",
      "phone": "+33600000000"
    }
  ]
}
```

### Mark submissions as read

Mark submissions as read under a read marker, so 'List unread submissions' with that marker no longer returns them.

**Inputs**

- Form (`form_id`, text, required): The form. Pick one, or give its id from an earlier step.
- Read marker (`marker`, text, required): A name for what this workflow does with the submissions, such as lodol_invoices. Kizeo remembers which submissions are read separately for each name, so other tools reading the same form aren't affected.
- Submission IDs (`data_ids`, list, required): The submissions' ids, such as data_ids from 'List unread submissions'.

**Outputs**

- `count` (number): How many
- `data_ids` (list): The submissions marked
- `marked` (true/false): True once marked
- `message` (text): Kizeo's own message, if any

**Example output**

```json
{
  "count": 1,
  "data_ids": [
    "98765432"
  ],
  "marked": true,
  "message": ""
}
```

### Push form to a user

Send a form, with some answers already filled in, to a user's Kizeo app for them to complete, optionally planned for a time slot.

**Inputs**

- Form (`form_id`, text, required): The form. Pick one, or give its id from an earlier step.
- Send to (`recipient_user_id`, text, required): The user whose app receives the form.
- Answers (`values`, object): Field ids and their answers, such as {"customer": "Acme"}. See 'Get form' for the field ids.
- Planned start (`planning_start`, date and time): When the job starts, for Kizeo's planning. Give the end too.
- Planned end (`planning_end`, date and time): When the job ends, for Kizeo's planning.

**Outputs**

- `data_id` (text): The pushed submission's id, empty if Kizeo gave none
- `form_id` (text): The form sent
- `message` (text): Kizeo's own message, if any
- `pushed` (true/false): True once sent
- `recipient_user_id` (text): Who received it

**Example output**

```json
{
  "data_id": "98765433",
  "form_id": "512345",
  "message": "",
  "pushed": true,
  "recipient_user_id": "1001"
}
```

### Remove user from group

Take a user out of a group, as a member or as a group leader. The user stays in the account.

**Inputs**

- Group (`group_id`, text, required): The group. Pick one, or give its id.
- User (`kizeo_user_id`, text, required): The Kizeo Forms user. Pick one, or give their id.
- As (`role`, text): A member of the group, or one of its group leaders. Defaults to member. One of: `member` (Member (default)), `leader` (Group leader). Default: `member`.

**Outputs**

- `group_id` (text): The group
- `message` (text): Kizeo's own message, if any
- `removed` (true/false): True once removed
- `role` (text): member or leader
- `user_id` (text): The user

**Example output**

```json
{
  "group_id": "301",
  "message": "",
  "removed": true,
  "role": "member",
  "user_id": "1001"
}
```

### Replace external list items

Replace every item of an external list with the items given. Items not given are removed, so pass the whole list.

**Inputs**

- External list (`list_id`, text, required): The external list. Pick one, or give its id.
- Items (`items`, list, required): Every item the list should hold, one per entry, as Kizeo writes them (such as ACME:Acme for a code and label).

**Outputs**

- `item_count` (number): How many items it now has
- `list_id` (text): The list changed
- `message` (text): Kizeo's own message, if any
- `updated` (true/false): True once replaced

**Example output**

```json
{
  "item_count": 2,
  "list_id": "7001",
  "message": "Updated",
  "updated": true
}
```

### Search submissions

Find a form's submissions by date answered, who sent them, text they contain or the value of a field, newest first.

**Inputs**

- Form (`form_id`, text, required): The form. Pick one, or give its id from an earlier step.
- Answered on or after (`from_date`, date): Only submissions answered on or after this date.
- Answered on or before (`until_date`, date): Only submissions answered on or before this date.
- Answered by (`kizeo_user_id`, text): Only submissions sent by this user.
- Containing (`search_text`, text): Only submissions with this text anywhere in them.
- Where fields equal (`field_filters`, object): Field ids and the exact value each must have, such as {"city": "Lyon"}. See 'Get form' for the field ids.
- Order (`order`, text): By when they were answered. Defaults to newest first. One of: `desc` (Newest first (default)), `asc` (Oldest first). Default: `desc`.
- At most (`limit`, number): How many to return, 1 to 1000. Defaults to 100. From 1 to 1000.

**Outputs**

- `count` (number): How many
- `submissions` (list): The submissions, with Kizeo's _ fields and one key per form field
- `total` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "submissions": [
    {
      "_answer_time": "2026-10-20 14:01:58",
      "_create_time": "2026-10-20 14:02:11",
      "_form_id": "512345",
      "_id": "98765432",
      "_record_number": "42",
      "_update_time": "2026-10-20 14:02:11",
      "_user_id": "1001",
      "_user_name": "Jeanne Dupont"
    }
  ],
  "total": 1
}
```

### Update user

Change a user's login, password, name, contact details or rights. Only the fields given change.

**Inputs**

- User (`kizeo_user_id`, text, required): The Kizeo Forms user. Pick one, or give their id.
- Login (`login`, text): A new login. Leave empty to keep it.
- Password (`password`, text): A new password. Leave empty to keep it.
- First name (`first_name`, text): A new first name. Leave empty to keep it.
- Last name (`last_name`, text): A new last name. Leave empty to keep it.
- Email (`email`, text): The user's email address.
- Phone (`phone`, text): The user's phone number.
- Administrator (`admin`, text): Make the user an administrator, or not. Leave empty to keep it. One of: `yes`, `no`.
- Fills in forms (`form_user`, text): Let the user fill in forms, or not. Leave empty to keep it. One of: `yes`, `no`.

**Outputs**

- `changed` (list): The details sent
- `message` (text): Kizeo's own message, if any
- `updated` (true/false): True once updated
- `user_id` (text): The user updated

**Example output**

```json
{
  "changed": [
    "first_name",
    "login"
  ],
  "message": "Updated",
  "updated": true,
  "user_id": "1001"
}
```
