Introduction

Welcome to the Lumiform Public API documentation! You can use our API to get your organization's Inspections, Questions and Issues. Lists of Inspections and Issues are paginated. Paginated responses also have a meta and a links property useful for navigation - or even for helping you build a navigation UI if you desire!

You can view cURL request examples in the dark area to the right, as well as examples of the responses you should expect to get.

Authentication

To obtain your API Bearer token, use this code:

curl GET 'https://public-api.lumiformapp.com/api/v1/oauth2/token' \
  -H 'Authorization: Basic yourbase64token'

Make sure to replace yourbase64token with the token you have obtained by base 64 encoding your API key and API secret concatenated with a colon.

If all went well you should receive a response like the following:

{
  "access_token": "yourtoken",
  "expires_in": 3600,
  "token_type": "Bearer"
}

To authorize requests, use this code:

# With shell, you can just pass the correct header with each request
curl "[api_endpoint_here]" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer yourtoken"

Make sure to replace yourtoken with the token you got from the previous response.

Lumiform uses API keys to allow access to the API. Your organization can obtain an API key and secret by visiting the API management page. Once you have obtained them, you can get your API key by following these steps:

Concatenate your API key and API secret with a colon like so: apikey:apisecret
Generate a base64 encoded token from your key and secret concatenated string. You can use this website for example.
Make a request to our OAuth 2.0 Token endpoint using Basic Authorization, and your base64 token as the key, as shown in the code example.
You should now receive your bearer token in the access_token field which you can use for authorization!

Lumiform expects your access_token bearer token to be included in the header of all API requests you make:

Authorization: Bearer [your token here]

You must replace [your token here] with your organization's access token.

Filters

Get All Users (v1)

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/filters/users' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "name": "Obi-Wan Kenobi",
      "email": "obi.wan@jediknights.com"
    },
    {
      "id": 2,
      "name": "Yoda",
      "email": "yoda@jediknights.com"
    },
    {
      "id": 3,
      "name": "Mace Windu",
      "email": "mace.windu@jediknights.com"
    },
    {
      "id": 4,
      "name": "Jocasta Nu",
      "email": "jocasta.nu@jediknights.com"
    },
    {
      "id": 5,
      "name": "Ki-Adi-Mundi",
      "email": "ki.adi.mundi@jediknights.com"
    }
  ]
}

This endpoint retrieves all users of your organization.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/filters/users

Get All Sites (v1)

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/filters/sites' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Temple of Coruscant"
    },
    {
      "id": 2,
      "title": "Temple of Ahch-To"
    }
  ]
}

This endpoint retrieves all sites of your organization.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/filters/sites

Get All Form Templates

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/filters/form-templates' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Safety form template",
      "status": "active"
    },
    {
      "id": 2,
      "title": "Materials form template",
      "status": "active"
    },
    {
      "id": 3,
      "title": "Kaminoan cloning tank form template",
      "status": "inactive"
    }
  ]
}

This endpoint retrieves all form templates of your organization.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/filters/form-templates

Get All Checklists

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/filters/checklists' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Safety checklist",
      "status": "active"
    },
    {
      "id": 2,
      "title": "Materials checklist",
      "status": "active"
    },
    {
      "id": 3,
      "title": "Kaminoan cloning tank checklist",
      "status": "inactive"
    }
  ]
}

This endpoint retrieves all checklists of your organization.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/filters/checklists

Roles

Get All Roles

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/roles' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1018907909,
      "name": "Administrator",
      "site_restricted": 0,
      "permissions": [],
      "users": [
        {
          "id": 87913847,
          "name": "Yoda",
          "email": "yoda@jediknights.com",
          "admin": 1
        }
      ],
      "created_at": null,
      "updated_at": null
    },
    {
      "id": 868746486,
      "name": "Sith",
      "site_restricted": false,
      "permissions": [
        "manage-users",
        "manage-sites"        
      ],
      "users": [
        {
          "id": 87913858,
          "name": "Darth Vader",
          "email": "darth.vader@sith.com",
          "admin": 0
        }
      ],
      "created_at": 1588753848,
      "updated_at": 1659609697
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v1/roles?page=1",
    "last": "https://public-api.lumiformapp.com/api/v1/roles?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v1/roles?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/roles?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/roles?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/roles?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v1/roles",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your roles.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/roles

Query Parameters

Parameter	Required	Type	Example	Description
site_restricted	No	Boolean	false	A boolean to try and find in the roles that have site restricted.
users	No	Array	1,2,3	A list of user IDs, or a single ID, to search for roles they are assigned to.
permissions	No	Array	role-1,role-2	A list of permissions, or single permission, to search for roles that contain them.
updated_from	No	Unix time	1585589759	The date from which to search for the update date of your roles.
updated_to	No	Unix time	1630185200	The date to which to search for the update date of your roles.
created_from	No	Unix time	1585589759	The date from which to search for the creation date of your roles.
created_to	No	Unix time	1630185200	The date to which to search for the creation date of your roles.

Get a Specific Role

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/roles/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 868746486,
    "name": "Sith",
    "site_restricted": false,
    "permissions": [
      "manage-users",
      "manage-sites"
    ],
    "users": [
      {
        "id": 87913858,
        "name": "Darth Vader",
        "email": "darth.vader@sith.com",
        "admin": 0
      }
    ],
    "created_at": 1588753848,
    "updated_at": 1659609697
  }
}

This endpoint retrieves a specific role.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/roles/<RoleId>

URL Parameters

Parameter	Required	Type	Example	Description
RoleId	Yes	Number	1	The ID of the role to retrieve.

Forms

Get All Forms

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/forms' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Safety checklist",
      "inspection_title": "Safety checklist",
      "assignees": [
        {
          "id": 1,
          "name": "Obi-Wan Kenobi",
          "email": "obi.wan@jediknights.com"
        },
        {
          "id": 2,
          "name": "Yoda",
          "email": "yoda@jediknights.com"
        }
      ],
      "conducted_by": {
        "id": 1,
        "name": "Obi-Wan Kenobi",
        "email": "obi.wan@jediknights.com"
      },
      "site": {
        "id": 1,
        "title": "Temple of Coruscant"
      },
      "conducted_at": 1585553421,
      "status": "closed",
      "due_at": 1625050211,
      "overdue": false,
      "issues": [],
      "checklist": {
        "id": 1,
        "title": "Safety checklist",
        "status": "active"
      },
      "approval": {
        "id": 30,
        "status": "approved",
        "comment": "my comment",
        "approver": {
          "id": 4,
          "name": "Jeff Hanneman",
          "email": "jeff.hanneman@slayer.net",
          "admin": 1
        },
        "updated_at": 1748878859
      }
    },
    {
      "id": 2,
      "title": "Lightsaber practice room materials checklist",
      "inspection_title": "Safety checklist",
      "assignees": [
        {
          "id": 2,
          "name": "Yoda",
          "email": "yoda@jediknights.com"
        }
      ],
      "conducted_by": {
        "id": 2,
        "name": "Yoda",
        "email": "yoda@jediknights.com"
      },
      "site": {
        "id": 1,
        "title": "Temple of Coruscant"
      },
      "conducted_at": 1585589759,
      "status": "closed",
      "due_at": 1595599783,
      "overdue": false,
      "issues": [
        {
          "id": 1,
          "title": "Missing blinding helmets",
          "updated_at": 1593378800,
          "site": {
            "id": 1,
            "title": "Temple of Coruscant"
          },
          "resolved_at": null,
          "resolved_by": null,
          "created_at": 1585589759,
          "assignees": [
            {
              "id": 3,
              "name": "Mace Windu",
              "email": "mace.windu@jediknights.com"
            }
          ],
          "status": "in_progress",
          "due_at": 1630185200,
          "overdue": false,
          "priority": "high",
          "created_by": {
            "id": 2,
            "name": "Yoda",
            "email": "yoda@jediknights.com"
          }
        }
      ],
      "checklist": {
        "id": 2,
        "title": "Materials checklist",
        "status": "active"
      },
      "approval": {
        "id": 31,
        "status": "approved",
        "comment": null,
        "approver": {
          "id": 4,
          "name": "Jeff Hanneman",
          "email": "jeff.hanneman@slayer.net",
          "admin": 1
        },
        "updated_at": 1748878859
      }
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/forms?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/forms?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/forms?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/forms?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/forms?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/forms?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/forms",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your forms.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/forms

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
conducted_from	No	Unix time	1585589759	The date from which to search for conducted forms.
conducted_to	No	Unix time	1630185200	The date to which to search for conducted forms.
due_from	No	Unix time	1585589759	The date from which to search for the due date of your forms.
due_to	No	Unix time	1630185200	The date to which to search for the due date of your forms.
users	No	Array	1,2,3	A list of user IDs, or a single ID, to search for forms they conducted.
sites	No	Array	1,2,3	A list of site IDs, or a single ID, to search for forms where they were conducted.
statuses	No	Array	open,taken	A list of statuses, or a single status, to search forms in. Allowed values: open, taken, closed, cant_do.
overdue	No	Boolean	true	Toggle filtering for overdue or not overdue forms.
title	No	Text	warehouse	A string of text to try and find in the forms titles.
checklist	No	Number	1	The ID of a checklist to search its conducted forms.
order_by	No	Text	id	The field to order the results by. Allowed values: id, conducted_at.
order_way	No	Text	ASC	The field to order the results by. Allowed values: ASC, DESC.

Get a Specific Form

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/forms/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "title": "Safety checklist",
    "inspection_title": "Safety checklist",
    "assignees": [
      {
        "id": 1,
        "name": "Obi-Wan Kenobi",
        "email": "obi.wan@jediknights.com"
      },
      {
        "id": 2,
        "name": "Yoda",
        "email": "yoda@jediknights.com"
      }
    ],
    "conducted_by": {
      "id": 1,
      "name": "Obi-Wan Kenobi",
      "email": "obi.wan@jediknights.com"
    },
    "site": {
      "id": 1,
      "title": "Temple of Coruscant"
    },
    "conducted_at": 1585553421,
    "status": "closed",
    "due_at": 1625050211,
    "overdue": false,
    "issues": [],
    "checklist": {
      "id": 1,
      "title": "Safety checklist",
      "status": "active"
    },
    "photos": [
      {
        "id": "d0ada570-c2db-4cc7-bb29-c18b6d1fef8e.jpeg",
        "url": "https://assets.lumiformapp.com/image-public/d0ada570-c2db-4cc7-bb29-c18b6d1fef8e.jpeg?token=[your token here]",
        "width": null,
        "height": null
      }
    ],
    "approval": {
      "id": 29,
      "status": "approved",
      "comment": "my comment",
      "approver": {
        "id": 4,
        "name": "Jeff Hanneman",
        "email": "jeff.hanneman@slayer.net",
        "admin": 1
      },
      "updated_at": 1748878859
    }
  }
}

This endpoint retrieves a specific form.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/forms/<FormId>

URL Parameters

Parameter	Required	Type	Example	Description
FormId	Yes	Number	1	The ID of the form to retrieve.

Get Questions of a Form

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/forms/1/questions' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Are the archives complete?",
      "type": "list",
      "response": "No",
      "max_score": 1,
      "score": 0,
      "percentage": 0,
      "is_negative": true,
      "notes": "Planet Kamino is missing from the archives.",
      "photos": [
        {
          "id": "d0ada570-c2db-4cc7-bb29-c18b6d1fef8e.jpeg",
          "url": "https://assets.lumiformapp.com/image-public/d0ada570-c2db-4cc7-bb29-c18b6d1fef8e.jpeg?token=[your token here]",
          "width": 800,
          "height": 802
        }
      ],
      "issues": [
        {
          "id": 2,
          "title": "Add Kamino to the archives",
          "updated_at": 1593378800,
          "site": {
            "id": 1,
            "title": "Temple of Coruscant"
          },
          "resolved_at": 1624914800,
          "resolved_by": null,
          "created_at": 1598649200,
          "assignees": [
            {
              "id": 4,
              "name": "Jocasta Nu",
              "email": "jocasta.nu@jediknights.com"
            }
          ],
          "status": "in_progress",
          "due_at": 1630185200,
          "overdue": false,
          "priority": "high",
          "created_by": {
            "id": 1,
            "name": "Obi-Wan Kenobi",
            "email": "obi.wan@jediknights.com"
          }
        }
      ]
    },
    {
      "id": 2,
      "title": "Did the younglings go to bed early?",
      "response": "Yes",
      "max_score": 1,
      "score": 1,
      "percentage": 100,
      "is_negative": false,
      "notes": null,
      "photos": [],
      "issues": []
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/forms/1/questions?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/forms/1/questions?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/forms/1/questions?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/forms/1/questions?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/forms/1/questions?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/forms/1/questions?page=2",
        "label": "Next »",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/forms/1/questions",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves questions of a specific form.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/forms/<FormId>/questions

URL Parameters

Parameter	Required	Type	Example	Description
FormId	Yes	Number	1	The ID of the form to retrieve questions from.

Query Parameters

Parameter	Required	Type	Example	Description
conducted_from	No	Unix time	1585589759	The date from which to search for answered questions.
conducted_to	No	Unix time	1630185200	The date to which to search for answered questions.
title	No	Text	archives	A string of text to try and find in the question titles.
response	No	Text	No	A string of text to try and find in the question response.
negative	No	Boolean	true	Toggle filtering for negatively answered questions.

Export a Specific Form to desired format

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/forms/1/export?format=pdf&timezone=Europe/Berlin' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": "<base64-encoded-string>",
  "format": "pdf"
}

This endpoint retrieves a report, encoded in base64 string, for specific form.

CSV Export caveats

CSV export contains direct links to photos however they are unauthorized for download. To download photos, you need to append query parameter with your token. The final URL should look like: https://assets.lumiformapp.com/image-public/d0ada570-c2db-4cc7-bb29-c18b6d1fef8e.jpeg?token=[your token here]

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/forms/<FormId>/export

URL Parameters

Parameter	Required	Type	Example	Description
FormId	Yes	Number	1	The ID of the form to retrieve.

Query Parameters

Parameter	Required	Type	Example	Description
format	yes	Text	pdf	Format for export. Supported formats: pdf
timezone	yes	Timezone	Europe/Berlin	Timezone to be used for exporting dates.

Actions

Get All Actions

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/actions' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Check the droid attack on the Wookies",      
      "status": "in_progress",
      "due_at": 1630185200      
    },
    {
      "id": 2,
      "title": "Add Kamino to the archives",
      "status": "in_progress",
      "due_at": 1630185200
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/actions?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/actions?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/actions?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/actions?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/actions?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/actions?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/actions",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your actions.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/actions

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
resolved_by	No	Number	1	The user ID to find actions they have resolved.
title	No	Text	Check	A string of text to try and find in the actions titles.
updated_from	No	Unix time	1585589759	The date from which to search for the update date of your action.
updated_to	No	Unix time	1630185200	The date to which to search for the update date of your actions.
created_from	No	Unix time	1585589759	The date from which to search for the creation date of your actions.
created_to	No	Unix time	1630185200	The date to which to search for the creation date of your actions.
sites	No	Array	1,2,3	A list of site IDs, or a single ID, to search for actions related to them.
resolved_from	No	Unix time	1585589759	The date from which to search for the resolution date of your actions.
resolved_to	No	Unix time	1630185200	The date to which to search for the resolution date of your actions.
assignees	No	Array	1,2,3	A list of user IDs, or a single ID, to search for actions they are assigned to.
statuses	No	Array	open,in_progress	A list of statuses, or a single status, to search actions in. Allowed values: open, solved, in_progress, cant_do.
due_from	No	Unix time	1585589759	The date from which to search for the due date of your actions.
due_to	No	Unix time	1630185200	The date to which to search for the due date of your actions.
overdue	No	Boolean	true	Toggle filtering for overdue or not overdue actions.
priorities	No	Array	normal	A list of priorities, or a single priority, to search actions with. Allowed values: normal, high.
created_by	No	Number	1	The user ID to find actions they have created.

Get a Specific Action

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/actions/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "title": "Check the droid attack on the Wookies",
    "description": "action description",
    "updated_at": 1593378800,
    "site": {
      "id": 1,
      "title": "Temple of Coruscant",
      "description": "Site description"
    },
    "resolved_at": 1624914800,
    "resolved_by": null,
    "created_at": 1598649200,
    "assignees": [
      {
        "id": 2,
        "name": "Yoda",
        "email": "yoda@jediknights.com"
      }
    ],
    "status": "in_progress",
    "due_at": 1630185200,
    "overdue": false,
    "priority": "normal",
    "created_by": {
      "id": 5,
      "name": "Ki-Adi-Mundi",
      "email": "ki.adi.mundi@jediknights.com"
    },
    "photos": [
      {
        "id": "d0ada570-c2db-4cc7-bb29-c18b6d1fef8e.jpeg",
        "url": "https://assets.lumiformapp.com/image-public/d0ada570-c2db-4cc7-bb29-c18b6d1fef8e.jpeg?token=[your token here]",
        "width": 800,
        "height": 802
      }
    ]
  }
}

This endpoint retrieves a specific action.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/actions/<ActionId>

URL Parameters

Parameter	Required	Type	Example	Description
ActionId	Yes	Number	1	The ID of the action to retrieve.

Create an Action

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/actions' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"title": "action title", "description": "action description", "site": 576577251, "status": "open", "assignees":[1,2], "due_at": 1585639822, "priority": "high"}'

Mandatory fields: title

status values: open, solved, in_progress or cant_do

priority values: normal or high

The above command returns JSON structured like this:

{
  "id": 123
}

This endpoint creates a site.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/actions

Update an Action

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/actions/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"title": "action title", "description": "action description", "site": 576577251, "status": "open", "assignees":[1,2], "due_at": 1585639822, "priority": "high"}'

Mandatory fields: title

The above command does not return any data

This endpoint updates a specific action.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/actions/<ActionId>

URL Parameters

Parameter	Required	Type	Example	Description
ActionId	Yes	Number	1	The ID of the action to update.

Delete an Action

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/actions/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific action.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/actions/<ActionId>

URL Parameters

Parameter	Required	Type	Example	Description
ActionId	Yes	Number	1	The ID of the action to delete.

Errors

The Lumiform Public API uses the following error codes:

Error Code	Meaning
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't JSON.
422	Unprocessable Entity -- Your filters or your request body are incorrectly specified. See Validation Errors below.
429	Too Many Requests -- You're requesting too many resources! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Validation Errors

A 422 response is structured like this:

{
  "message": "{\"type\":\"validation.code\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.code",
      "parameters": [],
      "field": "fieldName"
    }
  ],
  "code": 422
}

A 422 response carries an errors array of error objects. Each object has type, parameters and field. errors is always a numeric array — never an object keyed by field name.

Match on errors[].type, not on message. The message string encodes the first error and may change presentation; the type codes will not.

Seat limit codes

Your organization's parent can enable seat management for entity folders. When it is enabled, a top-level entity folder can carry a seat limit, set from the Lumiform web app. While a limit is in force, writes that change who can reach that folder are checked against the capacity of the resulting state.

Code	Field	Meaning
`validation.entityFolderSeatManagement.exceedsChildAllocation`	`seatLimit`	The seat limit is higher than the parent's remaining allocation allows. Lower the limit, or free capacity elsewhere.
`validation.entityFolderSeatManagement.belowChargedUsers`	`seatLimit`	The seat limit is below the number of users already charged to the folder. Raise the limit, or free seats first.
`validation.entityFolderSeatManagement.noFreeSeats`	`users`, or `role` on user writes	The resulting assignments cannot all be charged against the folder's remaining seats. Assign fewer users, or free a seat by removing someone else, or raise the limit in the web app.
`validation.entityFolderSeatManagement.limitedFolderCannotBeNested`	`children`	A folder that carries a seat limit cannot become a child of another folder. Remove the limit in the web app first, then nest it.

exceedsChildAllocation:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.exceedsChildAllocation\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.exceedsChildAllocation",
      "parameters": [],
      "field": "seatLimit"
    }
  ],
  "code": 422
}

belowChargedUsers:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.belowChargedUsers\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.belowChargedUsers",
      "parameters": [],
      "field": "seatLimit"
    }
  ],
  "code": 422
}

noFreeSeats:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.noFreeSeats\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.noFreeSeats",
      "parameters": [],
      "field": "users"
    }
  ],
  "code": 422
}

limitedFolderCannotBeNested:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.limitedFolderCannotBeNested\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.limitedFolderCannotBeNested",
      "parameters": [],
      "field": "children"
    }
  ],
  "code": 422
}

These codes can be returned by write requests on entity folders, entity items, entity types and users. They are business errors: correct the request before retrying, and do not retry it unchanged.

Inspections

Get All Inspections

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/inspections' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Safety checklist",
      "assignees": [
        {
          "id": 1,
          "name": "Obi-Wan Kenobi",
          "email": "obi.wan@jediknights.com"
        },
        {
          "id": 2,
          "name": "Yoda",
          "email": "yoda@jediknights.com"
        }
      ],
      "conducted_by": {
        "id": 1,
        "name": "Obi-Wan Kenobi",
        "email": "obi.wan@jediknights.com"
      },
      "site": {
        "id": 1,
        "title": "Temple of Coruscant"
      },
      "conducted_at": 1585553421,
      "status": "closed",
      "due_at": 1625050211,
      "overdue": false,
      "issues": [],
      "checklist": {
        "id": 1,
        "title": "Safety checklist",
        "status": "active"
      }
    },
    {
      "id": 2,
      "title": "Lightsaber practice room materials checklist",
      "assignees": [
        {
          "id": 2,
          "name": "Yoda",
          "email": "yoda@jediknights.com"
        }
      ],
      "conducted_by": {
        "id": 2,
        "name": "Yoda",
        "email": "yoda@jediknights.com"
      },
      "site": {
        "id": 1,
        "title": "Temple of Coruscant"
      },
      "conducted_at": 1585589759,
      "status": "closed",
      "due_at": 1595599783,
      "overdue": false,
      "issues": [
        {
          "id": 1,
          "title": "Missing blinding helmets",
          "updated_at": 1593378800,
          "site": {
            "id": 1,
            "title": "Temple of Coruscant"
          },
          "resolved_at": null,
          "resolved_by": null,
          "created_at": 1585589759,
          "assignees": [
            {
              "id": 3,
              "name": "Mace Windu",
              "email": "mace.windu@jediknights.com"
            }
          ],
          "status": "in_progress",
          "due_at": 1630185200,
          "overdue": false,
          "priority": "high",
          "created_by": {
            "id": 2,
            "name": "Yoda",
            "email": "yoda@jediknights.com"
          }
        }
      ],
      "checklist": {
        "id": 2,
        "title": "Materials checklist",
        "status": "active"
      }
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v1/inspections?page=1",
    "last": "https://public-api.lumiformapp.com/api/v1/inspections?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v1/inspections?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/inspections?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/inspections?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/inspections?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v1/inspections",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your inspections.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/inspections

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
conducted_from	No	Unix time	1585589759	The date from which to search for conducted inspections.
conducted_to	No	Unix time	1630185200	The date to which to search for conducted inspections.
due_from	No	Unix time	1585589759	The date from which to search for the due date of your inspections.
due_to	No	Unix time	1630185200	The date to which to search for the due date of your inspections.
users	No	Array	1,2,3	A list of user IDs, or a single ID, to search for inspections they conducted.
sites	No	Array	1,2,3	A list of site IDs, or a single ID, to search for inspections where they were conducted.
statuses	No	Array	open,taken	A list of statuses, or a single status, to search inspections in. Allowed values: open, taken, closed, cant_do.
overdue	No	Boolean	true	Toggle filtering for overdue or not overdue inspections.
title	No	Text	warehouse	A string of text to try and find in the inspections titles.
checklist	No	Number	1	The ID of a checklist to search its conducted inspections.

Get a Specific Inspection

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/inspections/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "title": "Safety checklist",
    "assignees": [
      {
        "id": 1,
        "name": "Obi-Wan Kenobi",
        "email": "obi.wan@jediknights.com"
      },
      {
        "id": 2,
        "name": "Yoda",
        "email": "yoda@jediknights.com"
      }
    ],
    "conducted_by": {
      "id": 1,
      "name": "Obi-Wan Kenobi",
      "email": "obi.wan@jediknights.com"
    },
    "site": {
      "id": 1,
      "title": "Temple of Coruscant"
    },
    "conducted_at": 1585553421,
    "status": "closed",
    "due_at": 1625050211,
    "overdue": false,
    "issues": [],
    "checklist": {
      "id": 1,
      "title": "Safety checklist",
      "status": "active"
    }
  }
}

This endpoint retrieves a specific inspection.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/inspections/<InspectionId>

URL Parameters

Parameter	Required	Type	Example	Description
InspectionId	Yes	Number	1	The ID of the inspection to retrieve.

Get Questions of an Inspection

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/inspections/1/questions' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Are the archives complete?",
      "response": "No",
      "max_score": 1,
      "score": 0,
      "percentage": 0,
      "is_negative": true,
      "notes": "Planet Kamino is missing from the archives.",
      "issues": [
        {
          "id": 2,
          "title": "Add Kamino to the archives",
          "updated_at": 1593378800,
          "site": {
            "id": 1,
            "title": "Temple of Coruscant"
          },
          "resolved_at": 1624914800,
          "resolved_by": null,
          "created_at": 1598649200,
          "assignees": [
            {
              "id": 4,
              "name": "Jocasta Nu",
              "email": "jocasta.nu@jediknights.com"
            }
          ],
          "status": "in_progress",
          "due_at": 1630185200,
          "overdue": false,
          "priority": "high",
          "created_by": {
            "id": 1,
            "name": "Obi-Wan Kenobi",
            "email": "obi.wan@jediknights.com"
          }
        }
      ]
    },
    {
      "id": 2,
      "title": "Did the younglings go to bed early?",
      "response": "Yes",
      "max_score": 1,
      "score": 1,
      "percentage": 100,
      "is_negative": false,
      "notes": null,
      "issues": []
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v1/inspections/1/questions?page=1",
    "last": "https://public-api.lumiformapp.com/api/v1/inspections/1/questions?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v1/inspections/1/questions?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/inspections/1/questions?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/inspections/1/questions?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/inspections/1/questions?page=2",
        "label": "Next »",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v1/inspections/1/questions",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves questions of a specific inspection.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/inspections/<InspectionId>/questions

URL Parameters

Parameter	Required	Type	Example	Description
InspectionId	Yes	Number	1	The ID of the inspection to retrieve questions from.

Query Parameters

Parameter	Required	Type	Example	Description
conducted_from	No	Unix time	1585589759	The date from which to search for answered questions.
conducted_to	No	Unix time	1630185200	The date to which to search for answered questions.
title	No	Text	archives	A string of text to try and find in the question titles.
response	No	Text	No	A string of text to try and find in the question response.
negative	No	Boolean	true	Toggle filtering for negatively answered questions.

Export a Specific Inspection to desired format

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/inspections/1/export?format=pdf&timezone=Europe/Berlin' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": "<base64-encoded-string>",
  "format": "pdf"
}

This endpoint retrieves a report, encoded in base64 string, for specific inspection.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/inspections/<InspectionId>/export

URL Parameters

Parameter	Required	Type	Example	Description
InspectionId	Yes	Number	1	The ID of the inspection to retrieve.

Query Parameters

Parameter	Required	Type	Example	Description
format	yes	Text	pdf	Format for export. Supported formats: pdf
timezone	yes	Timezone	Europe/Berlin	Timezone to be used for exporting dates.

Issues

Get All Issues

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/issues' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Check the droid attack on the Wookies",
      "updated_at": 1593378800,
      "site": {
        "id": 1,
        "title": "Temple of Coruscant"
      },
      "resolved_at": 1624914800,
      "resolved_by": null,
      "created_at": 1598649200,
      "assignees": [
        {
          "id": 2,
          "name": "Yoda",
          "email": "yoda@jediknights.com"
        }
      ],
      "status": "in_progress",
      "due_at": 1630185200,
      "overdue": false,
      "priority": "normal",
      "created_by": {
        "id": 5,
        "name": "Ki-Adi-Mundi",
        "email": "ki.adi.mundi@jediknights.com"
      }
    },
    {
      "id": 2,
      "title": "Add Kamino to the archives",
      "updated_at": 1593378800,
      "site": {
        "id": 1,
        "title": "Temple of Coruscant"
      },
      "resolved_at": 1624914800,
      "resolved_by": null,
      "created_at": 1598649200,
      "assignees": [
        {
          "id": 4,
          "name": "Jocasta Nu",
          "email": "jocasta.nu@jediknights.com"
        }
      ],
      "status": "in_progress",
      "due_at": 1630185200,
      "overdue": false,
      "priority": "high",
      "created_by": {
        "id": 1,
        "name": "Obi-Wan Kenobi",
        "email": "obi.wan@jediknights.com"
      }
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v1/issues?page=1",
    "last": "https://public-api.lumiformapp.com/api/v1/issues?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v1/issues?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/issues?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/issues?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v1/issues?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v1/issues",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your issues.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/issues

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
resolved_by	No	Number	1	The user ID to find issues they have resolved.
title	No	Text	Check	A string of text to try and find in the issues titles.
updated_from	No	Unix time	1585589759	The date from which to search for the update date of your issue.
updated_to	No	Unix time	1630185200	The date to which to search for the update date of your issues.
created_from	No	Unix time	1585589759	The date from which to search for the creation date of your issues.
created_to	No	Unix time	1630185200	The date to which to search for the creation date of your issues.
sites	No	Array	1,2,3	A list of site IDs, or a single ID, to search for issues related to them.
resolved_from	No	Unix time	1585589759	The date from which to search for the resolution date of your issues.
resolved_to	No	Unix time	1630185200	The date to which to search for the resolution date of your issues.
assignees	No	Array	1,2,3	A list of user IDs, or a single ID, to search for issues they are assigned to.
statuses	No	Array	open,in_progress	A list of statuses, or a single status, to search issues in. Allowed values: open, solved, in_progress, cant_do.
due_from	No	Unix time	1585589759	The date from which to search for the due date of your issues.
due_to	No	Unix time	1630185200	The date to which to search for the due date of your issues.
overdue	No	Boolean	true	Toggle filtering for overdue or not overdue issues.
priorities	No	Array	normal	A list of priorities, or a single priority, to search issues with. Allowed values: normal, high.
created_by	No	Number	1	The user ID to find issues they have created.

Get a Specific Issue

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v1/issues/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "title": "Check the droid attack on the Wookies",
    "updated_at": 1593378800,
    "site": {
      "id": 1,
      "title": "Temple of Coruscant"
    },
    "resolved_at": 1624914800,
    "resolved_by": null,
    "created_at": 1598649200,
    "assignees": [
      {
        "id": 2,
        "name": "Yoda",
        "email": "yoda@jediknights.com"
      }
    ],
    "status": "in_progress",
    "due_at": 1630185200,
    "overdue": false,
    "priority": "normal",
    "created_by": {
      "id": 5,
      "name": "Ki-Adi-Mundi",
      "email": "ki.adi.mundi@jediknights.com"
    }
  }
}

This endpoint retrieves a specific issue.

HTTP Request

GET https://public-api.lumiformapp.com/api/v1/issues/<IssueId>

URL Parameters

Parameter	Required	Type	Example	Description
IssueId	Yes	Number	1	The ID of the issue to retrieve.

Groups

Get All Groups

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/groups' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 868746486,
      "name": "Jedi Order",
      "users": [
        {
          "id": 87913847,
          "name": "Yoda",
          "email": "yoda@jediknights.com"
        }
      ]
    },
    {
      "id": 868746478,
      "name": "Order of the Sith Lords",
      "users": [
        {
          "id": 87913858,
          "name": "Darth Vader",
          "email": "darth.vader@sith.com"
        }
      ]
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/groups?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/groups?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/groups?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/groups?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/groups?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/groups?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/groups",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your groups.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/groups

Query Parameters

Parameter	Required	Type	Example	Description
name	No	Text	yoda	A string of text to try and find in the groups names.
users	No	Array	1,2,3	A list of user IDs, or a single ID, to search for groups they are assigned to.

Get a Specific Group

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/groups/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "name": "Jedi Order",
    "users": [
      {
        "id": 2,
        "name": "Yoda",
        "email": "yoda@jediknights.com"
      }
    ]
  }
}

This endpoint retrieves a specific group.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/groups/<GroupId>

URL Parameters

Parameter	Required	Type	Example	Description
GroupId	Yes	Number	1	The ID of the group to retrieve.

Create a Group

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/groups' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"name":"Group name","users":"[1,2]"}'

The above command returns JSON structured like this:

{
  "id": 123
}

This endpoint creates a group.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/groups

Update a Group

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/groups/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"name":"New group name","users":"[2,3,4]"}'

The above command does not return any data

This endpoint updates a specific group.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/groups/<GroupId>

URL Parameters

Parameter	Required	Type	Example	Description
GroupId	Yes	Number	1	The ID of the group to update.

Delete a Group

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/groups/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific group.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/groups/<GroupId>

URL Parameters

Parameter	Required	Type	Example	Description
GroupId	Yes	Number	1	The ID of the group to delete.

Sites

Get All Sites

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/sites' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 868746486,
      "name": "Tatooine",
      "description": "It is the home planet of Luke SKywalker",
      "users": [
        {
          "id": 87913847,
          "name": "luke",
          "email": "luke@jediknights.com"
        }
      ],
      "primary_ssid": null,
      "primary_password": null,
      "secondary_ssid": null,
      "secondary_password": null
    },
    {
      "id": 868746478,
      "name": "Alderaan",
      "description": "It is the home planet of Princess Leia Organa",
      "users": [
        {
          "id": 87913858,
          "name": "Leia Organa",
          "email": "leia.organa@sw.com"
        }
      ]
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/sites?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/sites?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/sites?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/sites?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/sites?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/sites?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/sites",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your sites.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/sites

Query Parameters

Parameter	Required	Type	Example	Description
title	No	Text	luke	A string of text to try and find in the sites names.
users	No	Array	1,2,3	A list of user IDs, or a single ID, to search for sites they are assigned to.

Get a Specific Site

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/sites/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 868746486,
    "name": "Tatooine",
    "description": "It is the home planet of Luke SKywalker",
    "users": [
      {
        "id": 87913847,
        "name": "luke",
        "email": "luke@jediknights.com"
      }
    ],
    "primary_ssid": null,
    "primary_password": null,
    "secondary_ssid": null,
    "secondary_password": null
  }
}

This endpoint retrieves a specific site.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/sites/<SiteId>

URL Parameters

Parameter	Required	Type	Example	Description
SiteId	Yes	Number	1	The ID of the site to retrieve.

Create a Site

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/sites' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"title": "Site name", "description": "site description", "users":"[1,2]"}'

Mandatory fields: title

The above command returns JSON structured like this:

{
  "id": 123
}

This endpoint creates a site.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/sites

Update a Site

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/sites/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"title": "Site name", "description": "site description", "users":[1,2], "primary_ssid": "123", "primary_password": "123", "secondary_ssid": "123", "secondary_password": "123"}'

Mandatory fields: title

The above command does not return any data

This endpoint updates a specific site.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/sites/<SiteId>

URL Parameters

Parameter	Required	Type	Example	Description
SiteId	Yes	Number	1	The ID of the site to update.

Delete a Site

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/sites/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific site.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/sites/<SiteId>

URL Parameters

Parameter	Required	Type	Example	Description
SiteId	Yes	Number	1	The ID of the site to delete.

Entity Folders

Get All Entity Folders

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-folders' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Safety folder",
      "parents": [
        {
          "id": 2,
          "title": "Parent folder"
        }
      ],
      "children": [
        {
          "id": 3,
          "title": "Child folder"
        }
      ],
      "users": [
        {
          "id": 1,
          "name": "Obi-Wan Kenobi",
          "email": "obi.wan@jediknights.com",
          "admin": 0
        }
      ],
      "entity_items": [
        {
          "id": 1,
          "title": "Entity item",
          "description": null
        }
      ],
      "labels": [
        {
          "id": 1,
          "label": "Label"
        }
      ]
    },

    {
      "id": 2,
      "title": "Safety folder",
      "parents": [
        {
          "id": 4,
          "title": "Parent folder"
        }
      ],
      "children": [
        {
          "id": 5,
          "title": "Child folder"
        }
      ],
      "users": [
        {
          "id": 1,
          "name": "Obi-Wan Kenobi",
          "email": "obi.wan@jediknights.com",
          "admin": 0
        }
      ],
      "entity_items": [
        {
          "id": 1,
          "title": "Entity item",
          "description": null
        }
      ],
      "labels": [
        {
          "id": 1,
          "label": "Label"
        }
      ]
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/entity-folders?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/entity-folders?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/entity-folders?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-folders?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-folders?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-folders?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/entity-folders",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your entity folders.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/entity-folders

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
users	No	Array	1,2,3	A list of user Ids, or a single Id
entityItems	No	Array	1,2,3	A list of entity items Ids, or a single Id
title	No	Text	warehouse	A string of text to try and find in the entity folders titles.

Get a Specific Entity Folder

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-folders/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "title": "Safety folder",
    "parents": [
      {
        "id": 2,
        "title": "Parent folder"
      }
    ],
    "children": [
      {
        "id": 3,
        "title": "Child folder"
      }
    ],
    "users": [
      {
        "id": 1,
        "name": "Obi-Wan Kenobi",
        "email": "obi.wan@jediknights.com",
        "admin": 0
      }
    ],
    "entity_items": [
      {
        "id": 1,
        "title": "Entity item",
        "description": null
      }
    ],
    "labels": [
      {
        "id": 1,
        "label": "Label"
      }
    ]
  }
}

This endpoint retrieves a specific Entity Folder.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/entity-folders/<EntityFolderId>

URL Parameters

Parameter	Required	Type	Example	Description
EntityFolderId	Yes	Number	1	The Id of the entity folder to retrieve.

Create an Entity Folder

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-folders' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"title":"Tatooine","children":[1],"labels":["Label 1","Label 2"],"entity_items":[1,2,3],"users":[1,2,3]}'

The above command returns JSON structured like this:

{
  "id": 1
}

This endpoint creates an Entity Folder.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/entity-folders

Update an Entity Folder

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-folders/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"title":"Tatooine","children":[1],"labels":["Label 1","Label 2"],"entity_items":[1,2,3],"users":[1,2,3]}'

The above command does not return any data

This endpoint updates a specific Entity Folder.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/entity-folders/<EntityFolderId>

URL Parameters

Parameter	Required	Type	Example	Description
EntityFolderId	Yes	Number	1	The Id of the Entity Folder to update.

This endpoint is a full replace. Any of users, entity_items, children and labels that you omit is treated as an empty list, and everything in it is detached. To change only the title, GET the folder first and send the current arrays back with your change.

Note: If your organization uses seat management, this request can fail with validation.entityFolderSeatManagement.noFreeSeats on users when the resulting assignments exceed the folder's remaining seats, or with validation.entityFolderSeatManagement.limitedFolderCannotBeNested on children when a folder that carries a seat limit would become nested. See Errors.

A folder update that exceeds the folder's remaining seats returns:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.noFreeSeats\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.noFreeSeats",
      "parameters": [],
      "field": "users"
    }
  ],
  "code": 422
}

Nesting a folder that still carries a seat limit returns:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.limitedFolderCannotBeNested\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.limitedFolderCannotBeNested",
      "parameters": [],
      "field": "children"
    }
  ],
  "code": 422
}

Delete an Entity Folder

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-folders/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific Entity Folder.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/entity-folders/<EntityFolderId>

URL Parameters

Parameter	Required	Type	Example	Description
EntityFolderId	Yes	Number	1	The Id of the Entity Folder to delete.

Note: If your organization uses seat management, a delete can fail with validation.entityFolderSeatManagement.noFreeSeats. Deleting a folder moves the users who reached it to whichever remaining folder can charge them, and that folder may have no capacity left. A DELETE carries no request body, so the error is reported on users. See Errors.

A delete that leaves users with no folder able to charge them returns:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.noFreeSeats\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.noFreeSeats",
      "parameters": [],
      "field": "users"
    }
  ],
  "code": 422
}

Entity Types

Note: If your organization uses seat management, create, update and delete requests on entity types can fail with validation.entityFolderSeatManagement.noFreeSeats, reported on users, when the resulting assignments exceed the remaining seats of a folder that carries a seat limit. See Errors.

Get All Entity Types

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

To include properties in the response, add the include_properties query parameter:

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types?include_properties=true' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Safety checklist",
      "description": "This checklist is about safety"
    },
    {
      "id": 2,
      "title": "Cleaning checklist",
      "description": "This checklist is about cleaning facility"
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/entity-types?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/entity-types?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/entity-types?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-types?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-types?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-types?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/entity-types",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your entity types. By default, properties are not included in the response. To include them, use the include_properties=true query parameter.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/entity-types

Response with Properties

When include_properties=true is included in the query string, the response will include a properties array for each entity type:

Properties included in response:

{
  "data": [
    {
      "id": 1,
      "title": "Safety checklist",
      "description": "This checklist is about safety",
      "properties": [
        {
          "id": 1,
          "label": "Location",
          "data_type": "text",
          "allow_multi": false
        },
        {
          "id": 2,
          "label": "Status",
          "data_type": "dropdown",
          "option_set_id": 1,
          "allow_multi": false,
          "option_values": [
            {
              "id": 1,
              "label": "Active"
            },
            {
              "id": 2,
              "label": "Inactive"
            }
          ]
        }
      ]
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/entity-types?page=1&include_properties=true",
    "last": "https://public-api.lumiformapp.com/api/v2/entity-types?page=2&include_properties=true",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/entity-types?page=2&include_properties=true"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "path": "https://public-api.lumiformapp.com/api/v2/entity-types",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

Properties Field Details:

id - The unique identifier of the property definition
label - The display label of the property
data_type - The type of property: "text" or "dropdown"
allow_multi - Whether multiple values are allowed for this property
option_set_id - The ID of the option set (only present for dropdown-type properties)
option_values - Array of available option values (only present for dropdown-type properties). Each option value contains:
- id - The unique identifier of the option value
- label - The display label of the option

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
title	No	Text	warehouse	A string of text to try and find in the entity types titles.
include_properties	No	Boolean	true	When set to `true`, includes property definitions for each entity type. Defaults to `false`.

Get a Specific Entity Type

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

To include properties in the response, add the include_properties query parameter:

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types/1?include_properties=true' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "title": "Safety checklist",
    "description": "This checklist is about safety"
  }
}

When include_properties=true is included, the response will also contain a properties array:

{
  "data": {
    "id": 1,
    "title": "Safety checklist",
    "description": "This checklist is about safety",
    "properties": [
      {
        "id": 1,
        "label": "Location",
        "data_type": "text",
        "allow_multi": false
      },
      {
        "id": 2,
        "label": "Status",
        "data_type": "dropdown",
        "option_set_id": 1,
        "allow_multi": false,
        "option_values": [
          {
            "id": 1,
            "label": "Active"
          },
          {
            "id": 2,
            "label": "Inactive"
          }
        ]
      }
    ]
  }
}

This endpoint retrieves a specific Entity Type. By default, properties are not included in the response. To include them, use the include_properties=true query parameter.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/entity-types/<EntityTypeId>

URL Parameters

Parameter	Required	Type	Example	Description
EntityTypeId	Yes	Number	1	The Id of the entity type to retrieve.

Query Parameters

Parameter	Required	Type	Example	Description
include_properties	No	Boolean	true	When set to `true`, includes property definitions for the entity type. Defaults to `false`.

Create an Entity Type

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description"}'

To create an entity type with property definitions, include the properties array:

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description","properties":[{"label":"Location","dataType":"text","allowMulti":false},{"label":"Status","dataType":"dropdown","optionSetId":1,"allowMulti":false}]}'

The above command returns JSON structured like this:

{
  "id": 1
}

This endpoint creates an Entity Type.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/entity-types

Request Body Parameters

Parameter	Required	Type	Example	Description
title	Yes	String	"Tatooine"	The title of the entity type.
description	No	String	"Some description"	The description of the entity type.
properties	No	Array	See below	Array of property definitions to create for this entity type.

Properties Array Structure:

Each property object in the properties array should contain:

Parameter	Required	Type	Example	Description
label	Yes*	String	"Location"	The display label of the property. Required when `properties` array is provided.
dataType	Yes*	String	"text" or "dropdown"	The data type of the property. Must be either `"text"` or `"dropdown"`. Required when `properties` array is provided.
optionSetId	No	Number	1	The ID of the option set. Required when `dataType` is `"dropdown"`. Not used for `"text"` properties.
allowMulti	No	Boolean	false	Whether multiple values are allowed for this property. Defaults to `false`.

Note: For dropdown properties, optionSetId is required. For text properties, optionSetId should not be provided.

Update an Entity Type

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description"}'

To update an entity type with property definitions, include the properties array:

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description","properties":[{"id":5,"label":"Updated Location","dataType":"text","allowMulti":false},{"label":"New Status","dataType":"dropdown","optionSetId":1,"allowMulti":false}]}'

The above command does not return any data

This endpoint updates a specific Entity Type.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/entity-types/<EntityTypeId>

URL Parameters

Parameter	Required	Type	Example	Description
EntityTypeId	Yes	Number	1	The Id of the Entity Type to update.

Request Body Parameters

Parameter	Required	Type	Example	Description
title	Yes	String	"Tatooine"	The title of the entity type.
description	No	String	"Some description"	The description of the entity type.
properties	No	Array	See below	Array of property definitions to update or create for this entity type.

Properties Array Structure:

Each property object in the properties array should contain:

Parameter	Required	Type	Example	Description
id	No	Number	5	The ID of an existing property to update. Omit to create a new property.
label	Yes*	String	"Updated Location"	The display label of the property. Required when `properties` array is provided.
dataType	Yes*	String	"text" or "dropdown"	The data type of the property. Must be either `"text"` or `"dropdown"`. Required when `properties` array is provided.
optionSetId	No	Number	1	The ID of the option set. Required when `dataType` is `"dropdown"`. Not used for `"text"` properties.
allowMulti	No	Boolean	false	Whether multiple values are allowed for this property. Defaults to `false`.

Note: For dropdown properties, optionSetId is required. For text properties, optionSetId should not be provided. Include id to update an existing property, or omit it to create a new property.

Delete an Entity Type

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-types/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific Entity Type.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/entity-types/<EntityTypeId>

URL Parameters

Parameter	Required	Type	Example	Description
EntityTypeId	Yes	Number	1	The Id of the Entity Type to delete.

Entity Type Response Sets

Get All Entity Type Response Sets

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

To include option values in the response, add the include_option_values query parameter:

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets?include_option_values=true' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "name": "Priority Levels"
    },
    {
      "id": 2,
      "name": "Status Options"
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/response-sets?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/response-sets?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/response-sets?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/response-sets?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/response-sets?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/response-sets?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/response-sets",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your entity type response sets. By default, option values are not included in the response. To include them, use the include_option_values=true query parameter.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/response-sets

Response with Option Values

When include_option_values=true is included in the query string, the response will include an option_values array for each entity type response set:

Option values included in response:

{
  "data": [
    {
      "id": 1,
      "name": "Priority Levels",
      "option_values": [
        {
          "id": 1,
          "label": "High"
        },
        {
          "id": 2,
          "label": "Medium"
        },
        {
          "id": 3,
          "label": "Low"
        }
      ]
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/response-sets?page=1&include_option_values=true",
    "last": "https://public-api.lumiformapp.com/api/v2/response-sets?page=2&include_option_values=true",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/response-sets?page=2&include_option_values=true"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "path": "https://public-api.lumiformapp.com/api/v2/response-sets",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

Option Values Field Details:

id - The unique identifier of the option value
label - The display label of the option value

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
name	No	Text	priority	A string of text to try and find in the entity type response set names.
include_option_values	No	Boolean	true	When set to `true`, includes option values for each entity type response set. Defaults to `false`.

Get a Specific Entity Type Response Set

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "name": "Priority Levels",
    "option_values": [
      {
        "id": 1,
        "label": "High"
      },
      {
        "id": 2,
        "label": "Medium"
      },
      {
        "id": 3,
        "label": "Low"
      }
    ]
  }
}

This endpoint retrieves a specific Entity Type Response Set with its option values.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/response-sets/<ResponseSetId>

URL Parameters

Parameter	Required	Type	Example	Description
ResponseSetId	Yes	Number	1	The Id of the entity type response set to retrieve.

Create an Entity Type Response Set

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Priority Levels"}'

To create an entity type response set with option values, include the optionValues array:

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Priority Levels",
    "optionValues": [
      {
        "label": "High",
        "value": "high",
        "isActive": true
      },
      {
        "label": "Medium",
        "value": "medium",
        "isActive": true
      },
      {
        "label": "Low",
        "value": "low",
        "isActive": true
      }
    ]
  }'

The above command returns JSON structured like this:

{
  "id": 1
}

This endpoint creates an Entity Type Response Set.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/response-sets

Request Body Parameters

Parameter	Required	Type	Example	Description
name	Yes	String	"Priority Levels"	The name of the entity type response set. Must be unique within your organization.
optionValues	No	Array	See below	Array of option values to create for this entity type response set.

Option Values Array Structure:

Each option value object in the optionValues array should contain:

Parameter	Required	Type	Example	Description
label	Yes*	String	"High"	The display label of the option value. Required when `optionValues` array is provided.
value	No	String	"high"	The value of the option. Can be null.
isActive	No	Boolean	true	Whether the option value is active. Defaults to `true`.

Note: The name field must be unique within your organization. If an entity type response set with the same name already exists, the request will fail with a validation error.

Update an Entity Type Response Set

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Priority Levels Updated"}'

To update an entity type response set with option values, include the optionValues array:

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Priority Levels Updated",
    "optionValues": [
      {
        "id": 1,
        "label": "High Updated",
        "value": "high",
        "isActive": true
      },
      {
        "label": "New Option",
        "value": "new",
        "isActive": true
      }
    ]
  }'

The above command does not return any data

This endpoint updates a specific Entity Type Response Set. When updating option values, existing values not included in the request will be deleted.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/response-sets/<ResponseSetId>

URL Parameters

Parameter	Required	Type	Example	Description
ResponseSetId	Yes	Number	1	The Id of the Entity Type Response Set to update.

Request Body Parameters

Parameter	Required	Type	Example	Description
name	Yes	String	"Priority Levels Updated"	The name of the entity type response set. Must be unique within your organization.
optionValues	No	Array	See below	Array of option values to update or create for this entity type response set.

Option Values Array Structure:

Each option value object in the optionValues array should contain:

Parameter	Required	Type	Example	Description
id	No	Number	1	The ID of an existing option value to update. Omit to create a new option value.
label	Yes*	String	"High Updated"	The display label of the option value. Required when `optionValues` array is provided.
value	No	String	"high"	The value of the option. Can be null.
isActive	No	Boolean	true	Whether the option value is active.

Note: The name field must be unique within your organization. Include id to update an existing option value, or omit it to create a new option value. Existing option values not included in the optionValues array will be deleted.

Delete an Entity Type Response Set

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/response-sets/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific Entity Type Response Set. Note that you cannot delete an entity type response set if it is being used by any entity type properties.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/response-sets/<ResponseSetId>

URL Parameters

Parameter	Required	Type	Example	Description
ResponseSetId	Yes	Number	1	The Id of the Entity Type Response Set to delete.

Entity Items

Note: If your organization uses seat management, create, update and delete requests on entity items can fail with validation.entityFolderSeatManagement.noFreeSeats, reported on users, when the resulting assignments exceed the remaining seats of a folder that carries a seat limit. See Errors.

Get All Entity Items

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

To include property values in the response, add the include_properties query parameter:

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items?include_properties=true' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "title": "Safety checklist",
      "description": "This checklist is about safety",
      "entity_type": {
        "id": 1,
        "title": "Safety",
        "description": "Safety related entities"
      },
      "users": [
        {
          "id": 1,
          "name": "John Doe",
          "email": "john.doe@lumiformapp.com",
          "admin": 0
        }
      ]
    },
    {
      "id": 2,
      "title": "Cleaning checklist",
      "description": "This checklist is about cleaning facility",
      "entity_type": {
        "id": 2,
        "title": "Cleaning",
        "description": "Cleaning related entities"
      },
      "users": [
        {
          "id": 1,
          "name": "John Doe",
          "email": "john.doe@lumiformapp.com",
          "admin": 0
        }
      ]
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/entity-items?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/entity-items?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/entity-items?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-items?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-items?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/entity-items?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/entity-items",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your entity items. By default, property values are not included in the response. To include them, use the include_properties=true query parameter.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/entity-items

Response with Properties

When include_properties=true is included in the query string, the response will include a properties array for each entity item:

Properties included in response:

{
  "data": [
    {
      "id": 1,
      "title": "Safety checklist",
      "description": "This checklist is about safety",
      "entity_type": {
        "id": 1,
        "title": "Safety",
        "description": "Safety related entities"
      },
      "users": [
        {
          "id": 1,
          "name": "John Doe",
          "email": "john.doe@lumiformapp.com",
          "admin": 0
        }
      ],
      "properties": [
        {
          "id": 1,
          "entity_type_property_id": 5,
          "value_text": "Some text value",
          "option_values": null
        },
        {
          "id": 2,
          "entity_type_property_id": 6,
          "value_text": null,
          "option_values": [
            {
              "id": 10,
              "label": "Option 1"
            },
            {
              "id": 11,
              "label": "Option 2"
            }
          ]
        }
      ]
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/entity-items?page=1&include_properties=true",
    "last": "https://public-api.lumiformapp.com/api/v2/entity-items?page=2&include_properties=true",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/entity-items?page=2&include_properties=true"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "path": "https://public-api.lumiformapp.com/api/v2/entity-items",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

Properties Field Details:

id - The unique identifier of the property value
entity_type_property_id - The ID of the property definition this value belongs to
value_text - The text value (for text-type properties). null for dropdown properties
option_values - Array of selected option values (for dropdown-type properties). null or omitted for text properties. Each option value contains:
- id - The unique identifier of the option value
- label - The display label of the option

Query Parameters

Parameter	Required	Item	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.
users	No	Array	1,2,3	A list of user Ids, or a single Id
entityType	No	Number	1	Single Entity Type Id
title	No	Text	warehouse	A string of text to try and find in the entity items titles.
include_properties	No	Boolean	true	When set to `true`, includes property values for each entity item. Defaults to `false`.

Get a Specific Entity Item

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

To include property values in the response, add the include_properties query parameter:

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items/1?include_properties=true' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "title": "Safety checklist",
    "description": "This checklist is about safety",
    "entity_type": {
      "id": 2,
      "title": "Cleaning",
      "description": "Cleaning related entities"
    },
    "users": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "john.doe@lumiformapp.com",
        "admin": 0
      }
    ]
  }
}

When include_properties=true is included, the response will also contain a properties array:

{
  "data": {
    "id": 1,
    "title": "Safety checklist",
    "description": "This checklist is about safety",
    "entity_type": {
      "id": 2,
      "title": "Cleaning",
      "description": "Cleaning related entities"
    },
    "users": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "john.doe@lumiformapp.com",
        "admin": 0
      }
    ],
    "properties": [
      {
        "id": 1,
        "entity_type_property_id": 5,
        "value_text": "Some text value",
        "option_values": null
      },
      {
        "id": 2,
        "entity_type_property_id": 6,
        "value_text": null,
        "option_values": [
          {
            "id": 10,
            "label": "Option 1"
          },
          {
            "id": 11,
            "label": "Option 2"
          }
        ]
      }
    ]
  }
}

This endpoint retrieves a specific Entity Item. By default, property values are not included in the response. To include them, use the include_properties=true query parameter.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/entity-items/<EntityItemId>

URL Parameters

Parameter	Required	Item	Example	Description
EntityItemId	Yes	Number	1	The Id of the entity item to retrieve.

Query Parameters

Parameter	Required	Item	Example	Description
include_properties	No	Boolean	true	When set to `true`, includes property values for the entity item. Defaults to `false`.

Create an Entity Item

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description","users":[1],"entity_type_id":1}'

To create an entity item with property values, include the properties array:

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description","users":[1],"entity_type_id":1,"properties":[{"entityTypePropertyId":5,"valueText":"Some text value"},{"entityTypePropertyId":6,"optionValueIds":[10,11]}]}'

The above command returns JSON structured like this:

{
  "id": 1
}

This endpoint creates an Entity Item.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/entity-items

Request Body Parameters

Parameter	Required	Item	Example	Description
title	Yes	String	"Tatooine"	The title of the entity item.
description	No	String	"Some description"	The description of the entity item.
entity_type_id	Yes	Number	1	The ID of the entity type this item belongs to.
users	No	Array	[1, 2, 3]	Array of user IDs assigned to this entity item.
properties	No	Array	See below	Array of property values to set for this entity item.

Properties Array Structure:

Each property object in the properties array should contain:

Parameter	Required	Item	Example	Description
entityTypePropertyId	Yes*	Number	5	The ID of the entity type property. Required when `properties` array is provided.
valueText	No	String	"Some text value"	The text value for text-type properties. Use this for properties with `data_type: "text"`.
optionValueIds	No	Array	[10, 11]	Array of option value IDs for dropdown-type properties. Use this for properties with `data_type: "dropdown"`.

Note: For text properties, provide valueText. For dropdown properties, provide optionValueIds. You should not provide both for the same property.

Update an Entity Item

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description","users":[1],"entity_type_id":1}'

To update an entity item with property values, include the properties array:

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Tatooine","description":"Some description","users":[1],"entity_type_id":1,"properties":[{"entityTypePropertyId":5,"valueText":"Updated text value"},{"entityTypePropertyId":6,"optionValueIds":[10,11]}]}'

The above command does not return any data

This endpoint updates a specific Entity Item.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/entity-items/<EntityItemId>

URL Parameters

Parameter	Required	Item	Example	Description
EntityItemId	Yes	Number	1	The Id of the Entity Item to update.

Request Body Parameters

Parameter	Required	Item	Example	Description
title	Yes	String	"Tatooine"	The title of the entity item.
description	No	String	"Some description"	The description of the entity item.
entity_type_id	Yes	Number	1	The ID of the entity type this item belongs to.
users	No	Array	[1, 2, 3]	Array of user IDs assigned to this entity item.
properties	No	Array	See below	Array of property values to set for this entity item.

Properties Array Structure:

Each property object in the properties array should contain:

Parameter	Required	Item	Example	Description
entityTypePropertyId	Yes*	Number	5	The ID of the entity type property. Required when `properties` array is provided.
valueText	No	String	"Updated text value"	The text value for text-type properties. Use this for properties with `data_type: "text"`.
optionValueIds	No	Array	[10, 11]	Array of option value IDs for dropdown-type properties. Use this for properties with `data_type: "dropdown"`.

Note: For text properties, provide valueText. For dropdown properties, provide optionValueIds. You should not provide both for the same property.

Delete an Entity Item

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/entity-items/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific Entity Item.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/entity-items/<EntityItemId>

URL Parameters

Parameter	Required	Item	Example	Description
EntityItemId	Yes	Number	1	The Id of the Entity Item to delete.

Users

Get All Users

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/users' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 868746486,
      "name": "Leia Organa",
      "email": "leia.organa@sw.com",
      "role": {
        "id": 1018907909,
        "name": "Administrator"
      },
      "admin": 1
    },
    {
      "id": 868746486,
      "name": "Luke Skywalker",
      "email": "luke@sw.com",
      "role": {
        "id": 576577251,
        "name": "Jedi"
      },
      "admin": 1      
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/users?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/users?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/users?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/users?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/users?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/users?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/users",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves all of your users.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/users

Query Parameters

Parameter	Required	Type	Example	Description
name	No	Text	luke	A string of text to try and find in the users names.
email	No	Text	luke@sw.com	A string of text to try and find in the users emails.

Get a Specific User

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/users/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 868746486,
    "name": "Luke Skywalker",
    "email": "luke@sw.com",
    "role": {
      "id": 576577251,
      "name": "Jedi"
    },
    "admin": 1
  }
}

This endpoint retrieves a specific user.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/users/<UserId>

URL Parameters

Parameter	Required	Type	Example	Description
UserId	Yes	Number	1	The ID of the user to retrieve.

Create a User

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/users' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"name": "User name", "email": "user@mail.com", "role": 123456}'

Mandatory fields: name, email, role

To have the user receive a "Set your password" email, set send_invite_email to true:

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/users' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"name": "User name", "email": "user@mail.com", "role": 123456, "send_invite_email": true}'

The above command returns JSON structured like this:

{
  "id": 123
}

This endpoint creates a user.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/users

Request Body Parameters

Parameter	Required	Type	Example	Description
name	Yes	String	"User name"	The name of the user.
email	Yes	String	"user@mail.com"	The email of the user.
role	Yes	Number	123456	The ID of the role to assign to the user.
send_invite_email	No	Boolean	true	Whether the user should receive a "Set your password" email. Defaults to `false`.

Note: If your organization uses seat management, the role you assign can make the new user consume a folder seat. When no seat is available, the request fails with validation.entityFolderSeatManagement.noFreeSeats reported on role, and the user is not created. See Errors.

Update a User

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/users/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --d '{"name": "User name", "email": "user@mail.com", "role": 123456}'

Mandatory fields: All

The above command does not return any data

This endpoint updates a specific user.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/users/<UserId>

URL Parameters

Parameter	Required	Type	Example	Description
UserId	Yes	Number	1	The ID of the user to update.

Note: If your organization uses seat management, changing a user's role can make that user consume a folder seat. When no seat is available in the folders the user can reach, the request fails with validation.entityFolderSeatManagement.noFreeSeats reported on role. See Errors.

A role change that leaves the user with no available seat returns:

{
  "message": "{\"type\":\"validation.entityFolderSeatManagement.noFreeSeats\",\"parameters\":[]}",
  "errors": [
    {
      "type": "validation.entityFolderSeatManagement.noFreeSeats",
      "parameters": [],
      "field": "role"
    }
  ],
  "code": 422
}

Delete a User

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/users/1' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific user.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/users/<UserId>

URL Parameters

Parameter	Required	Type	Example	Description
UserId	Yes	Number	1	The ID of the user to delete.

Schedules

Schedules create repeating inspections and todos from form templates.

List and retrieve responses include the stored rrule string. Create and update send an editor rule object, not that string. To change recurrence, decode the stored rrule, edit the returned rule, map related resource objects to IDs, and send the complete schedule through Update a Schedule.

Reads return related form templates, users, groups, and entity items as resource objects. Writes use arrays of those resources' IDs. Retrieved reminders include the derived read-only time_shift field. When writing reminders, send id where applicable, type, direction, scale, and value; time_shift does not need to be sent.

timezone is an IANA name such as Europe/Berlin. Send it on create and update. The Public API resolves it internally. Legacy reads may return null. Clients never send or receive a timezone identifier.

Related form templates, users, groups, entity items, and reminders must be accessible to your organization. Invalid or inaccessible IDs return a 422 validation error. A schedule that belongs to another organization cannot be retrieved, updated, or deleted.

All IDs in requests and responses are Public API IDs. created_at and updated_at are Unix timestamps.

A complete pass against a test organization is: create a schedule, list it, retrieve it, decode its rrule, edit the returned rule, map related resource objects to IDs, replace the schedule, then delete it.

Get All Schedules

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/schedules' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 739184205,
      "title": "Temple opening",
      "status": "active",
      "due_in": 90,
      "expire_after_days": 7,
      "timezone": "Europe/Berlin",
      "rrule": "DTSTART:20241028T121625Z\nRRULE:FREQ=DAILY",
      "created_at": 1730117785,
      "updated_at": 1730117785
    },
    {
      "id": 739184206,
      "title": "Archive review",
      "status": "inactive",
      "due_in": 60,
      "expire_after_days": null,
      "timezone": null,
      "rrule": "DTSTART:20241028T121625Z\nRRULE:FREQ=YEARLY;COUNT=1",
      "created_at": 1730117785,
      "updated_at": 1730117785
    }
  ],
  "links": {
    "first": "https://public-api.lumiformapp.com/api/v2/schedules?page=1",
    "last": "https://public-api.lumiformapp.com/api/v2/schedules?page=2",
    "prev": null,
    "next": "https://public-api.lumiformapp.com/api/v2/schedules?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/schedules?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/schedules?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://public-api.lumiformapp.com/api/v2/schedules?page=2",
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://public-api.lumiformapp.com/api/v2/schedules",
    "per_page": 15,
    "to": 15,
    "total": 30
  }
}

This endpoint retrieves the schedules in your organization. Results use the standard paginated data, links, and meta envelope.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/schedules

Query Parameters

Parameter	Required	Type	Example	Description
page	No	Number	1	The results page number to view. If omitted, the default is 1.

Response Fields

Field	Type	Description
id	Number	The schedule ID.
title	String or null	The schedule title.
status	String	`active` or `inactive`.
due_in	Number	Minutes after each occurrence starts until the inspection is due.
expire_after_days	Number or null	Extra days after each inspection due date before it expires.
timezone	String or null	IANA timezone name. `null` on some legacy schedules.
rrule	String	The stored recurrence string.
created_at	Number	Unix timestamp.
updated_at	Number	Unix timestamp.

Get a Specific Schedule

curl --request GET \
  --url 'https://public-api.lumiformapp.com/api/v2/schedules/739184205' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "data": {
    "id": 739184205,
    "title": "Temple opening",
    "status": "active",
    "due_in": 90,
    "expire_after_days": 7,
    "timezone": "Europe/Berlin",
    "rrule": "DTSTART:20241028T121625Z\nRRULE:FREQ=DAILY",
    "created_at": 1730117785,
    "updated_at": 1730117785,
    "separate_todo_for_all_users": false,
    "entity_item_specific_assignments": false,
    "form_templates": [
      {
        "id": 1018907909,
        "title": "Safety checklist",
        "status": "active"
      }
    ],
    "assignees": {
      "users": [
        {
          "id": 868746486,
          "name": "Obi-Wan Kenobi",
          "email": "obi.wan@jediknights.com",
          "admin": 0
        }
      ],
      "groups": [
        {
          "id": 868746478,
          "name": "Jedi Order"
        }
      ],
      "entity_items": [
        {
          "id": 412578903,
          "title": "Temple of Coruscant",
          "description": null
        }
      ],
      "all_entity_items": false
    },
    "supervisors": {
      "users": [
        {
          "id": 87913847,
          "name": "Yoda",
          "email": "yoda@jediknights.com",
          "admin": 1
        }
      ],
      "groups": []
    },
    "reminders": [
      {
        "id": 576577251,
        "type": "available",
        "direction": "before",
        "scale": "hour",
        "value": 2,
        "time_shift": -120
      }
    ]
  }
}

This endpoint retrieves a specific schedule, including related resources and reminders.

Do not send this payload unchanged to update. Map form_templates, assignees, and supervisors resource objects to arrays of IDs. Retrieved reminders include the derived read-only time_shift field; when writing, send id where applicable, type, direction, scale, and value.

HTTP Request

GET https://public-api.lumiformapp.com/api/v2/schedules/<ScheduleId>

URL Parameters

Parameter	Required	Type	Example	Description
ScheduleId	Yes	Number	739184205	The ID of the schedule to retrieve.

Additional Response Fields

Every index field, plus:

Field	Type	Description
separate_todo_for_all_users	Boolean	When `true`, each assignee receives a separate todo and inspection.
entity_item_specific_assignments	Boolean	When `true`, assignments are specific to the selected entity items.
form_templates	Array	Form templates on the schedule. Each object has `id`, `title`, and `status`.
assignees.users	Array	Assigned users (`id`, `name`, `email`, `admin`).
assignees.groups	Array	Assigned groups (`id`, `name`).
assignees.entity_items	Array	Assigned entity items (`id`, `title`, `description`).
assignees.all_entity_items	Boolean	When `true`, the schedule applies to all entity items.
supervisors.users	Array	Supervising users (`id`, `name`, `email`, `admin`).
supervisors.groups	Array	Supervising groups (`id`, `name`).
reminders	Array	Reminders with `id`, `type`, `direction`, `scale`, `value`, and `time_shift`.
reminders[].time_shift	Number	Derived read-only offset in minutes. Negative means before; positive means after. Not a timezone offset.

A schedule from another organization returns 403. An unknown or deleted schedule returns 404.

Create a Schedule

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/schedules' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Temple opening","due_in":90,"expire_after_days":7,"separate_todo_for_all_users":false,"entity_item_specific_assignments":false,"timezone":"Europe/Berlin","form_templates":[1018907909],"assignees":{"users":[868746486],"groups":[868746478],"entity_items":[412578903],"all_entity_items":false},"supervisors":{"users":[87913847],"groups":[]},"rule":{"start":1730117785,"repeat":"daily","interval":1},"reminders":[{"type":"available","direction":"before","scale":"hour","value":2}]}'

Request body:

{
  "title": "Temple opening",
  "due_in": 90,
  "expire_after_days": 7,
  "separate_todo_for_all_users": false,
  "entity_item_specific_assignments": false,
  "timezone": "Europe/Berlin",
  "form_templates": [1018907909],
  "assignees": {
    "users": [868746486],
    "groups": [868746478],
    "entity_items": [412578903],
    "all_entity_items": false
  },
  "supervisors": {
    "users": [87913847],
    "groups": []
  },
  "rule": {
    "start": 1730117785,
    "repeat": "daily",
    "interval": 1
  },
  "reminders": [
    {
      "type": "available",
      "direction": "before",
      "scale": "hour",
      "value": 2
    }
  ]
}

The above command returns JSON structured like this:

{
  "id": 739184205
}

This endpoint creates a schedule. Send form_templates and reminders even when they are empty arrays. Do not send rrule or status. Do not send reminder id on create.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/schedules

Request Body Parameters

Parameter	Required	Type	Example	Description
title	No	String or null	"Temple opening"	The schedule title.
due_in	Yes	Number	90	Integer number of minutes after each occurrence starts until the inspection is due. Must be `>= 0`.
expire_after_days	No	Number or null	7	Extra days after each inspection due date before it expires. `0`–`365`.
separate_todo_for_all_users	Yes	Boolean	false	When `true`, each assignee receives a separate todo and inspection.
entity_item_specific_assignments	Yes	Boolean	false	When `true`, assignments are specific to the selected entity items.
timezone	Yes	String	"Europe/Berlin"	IANA timezone name. Unknown values return 422. Omitting it also returns 422.
form_templates	Yes	Array	[1018907909]	Form template IDs. `[]` is valid.
assignees	No	Object or null	See example	Assignee users, groups, entity items, and `all_entity_items`.
assignees.users	No	Array or null	[868746486]	User IDs.
assignees.groups	No	Array or null	[868746478]	Group IDs.
assignees.entity_items	No	Array or null	[412578903]	Entity item IDs.
assignees.all_entity_items	No	Boolean	false	When `true`, the schedule applies to all entity items.
supervisors	No	Object or null	See example	Supervisor users and groups.
supervisors.users	No	Array or null	[87913847]	User IDs.
supervisors.groups	No	Array or null	[]	Group IDs.
rule	Yes	Object	See below	Editor recurrence object. See Recurrence Rule.
reminders	Yes	Array	See example	Reminder objects. `[]` is valid. Do not include `id`.

Each reminder object contains:

Parameter	Required	Type	Example	Description
type	Yes	String	"available"	Reminder type, such as `available` or `due`.
direction	Yes	String	"before"	`before` or `after`.
scale	Yes	String	"hour"	`month`, `week`, `day`, `hour`, or `minute`.
value	Yes	Number	2	Amount in the given scale.

The server derives the reminder minute offset from direction, scale, and value. Do not send time_shift on create or update.

An unknown timezone returns:

{
  "message": "The given data was invalid.",
  "errors": {
    "timezone": [
      "The selected timezone is invalid."
    ]
  }
}

Omitting required timezone also returns 422 with an error on timezone.

An inaccessible related ID returns:

{
  "message": "The given data was invalid.",
  "errors": {
    "form_templates": [
      "The selected form templates is invalid."
    ]
  }
}

Recurrence Rule

Create and update require a rule object. Retrieve returns the stored rrule string instead of this object.

Supported non-custom repeat values are daily, weekday, weekly, monthly, yearly, and no-repeat. Custom rules use repeat of custom with frequency of weekly or monthly.

start is a Unix timestamp. interval is required.

Daily:

{
  "start": 1730117785,
  "repeat": "daily",
  "interval": 1
}

Weekday:

{
  "start": 1730117785,
  "repeat": "weekday",
  "interval": 1
}

Does not repeat:

{
  "start": 1730117785,
  "repeat": "no-repeat",
  "interval": 1
}

Custom weekly. weekly is a list of MO, TU, WE, TH, FR, SA, SU:

{
  "start": 1730117785,
  "repeat": "custom",
  "interval": 1,
  "frequency": "weekly",
  "weekly": ["MO", "WE"]
}

Custom monthly. monthly.day is a weekday code, day, weekday, or weekend-day. monthly.setpos is the occurrence in the month:

{
  "start": 1730117785,
  "repeat": "custom",
  "interval": 1,
  "frequency": "monthly",
  "monthly": {
    "day": "MO",
    "setpos": 2
  }
}

Custom monthly on a weekend day:

{
  "start": 1730117785,
  "repeat": "custom",
  "interval": 1,
  "frequency": "monthly",
  "monthly": {
    "day": "weekend-day",
    "setpos": -1
  }
}

These are the editor shapes Lumiform already accepts. The API is not a comprehensive RFC RRULE validator.

Update a Schedule

curl --request PUT \
  --url 'https://public-api.lumiformapp.com/api/v2/schedules/739184205' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Temple opening","due_in":90,"expire_after_days":7,"separate_todo_for_all_users":false,"entity_item_specific_assignments":false,"timezone":"Europe/Berlin","form_templates":[1018907909],"assignees":{"users":[868746486],"groups":[868746478],"entity_items":[412578903],"all_entity_items":false},"supervisors":{"users":[87913847],"groups":[]},"rule":{"start":1730117785,"repeat":"custom","interval":1,"frequency":"weekly","weekly":["MO","WE"]},"reminders":[{"id":576577251,"type":"available","direction":"before","scale":"hour","value":2}]}'

Request body. Include every field you want to keep, including form_templates, reminders, and timezone:

{
  "title": "Temple opening",
  "due_in": 90,
  "expire_after_days": 7,
  "separate_todo_for_all_users": false,
  "entity_item_specific_assignments": false,
  "timezone": "Europe/Berlin",
  "form_templates": [1018907909],
  "assignees": {
    "users": [868746486],
    "groups": [868746478],
    "entity_items": [412578903],
    "all_entity_items": false
  },
  "supervisors": {
    "users": [87913847],
    "groups": []
  },
  "rule": {
    "start": 1730117785,
    "repeat": "custom",
    "interval": 1,
    "frequency": "weekly",
    "weekly": ["MO", "WE"]
  },
  "reminders": [
    {
      "id": 576577251,
      "type": "available",
      "direction": "before",
      "scale": "hour",
      "value": 2
    }
  ]
}

The above command does not return any data

This endpoint fully replaces a schedule. PATCH is not supported. Use PUT and send the complete writable representation. The request body matches Create a Schedule, with one difference for reminders: id is optional. An existing reminder ID updates that reminder and must belong to the schedule being updated. Omitting id creates a reminder. Reminders left out of the array are removed.

form_templates: [] and reminders: [] clear those collections. timezone is required. Do not send rrule or status.

A schedule from another organization returns 403. An unknown or deleted schedule returns 404.

HTTP Request

PUT https://public-api.lumiformapp.com/api/v2/schedules/<ScheduleId>

URL Parameters

Parameter	Required	Type	Example	Description
ScheduleId	Yes	Number	739184205	The ID of the schedule to update.

Clearing templates and reminders:

{
  "title": "Temple opening",
  "due_in": 90,
  "expire_after_days": 7,
  "separate_todo_for_all_users": false,
  "entity_item_specific_assignments": false,
  "timezone": "Europe/Berlin",
  "form_templates": [],
  "assignees": {
    "users": [868746486],
    "groups": [868746478],
    "entity_items": [412578903],
    "all_entity_items": false
  },
  "supervisors": {
    "users": [87913847],
    "groups": []
  },
  "rule": {
    "start": 1730117785,
    "repeat": "daily",
    "interval": 1
  },
  "reminders": []
}

Delete a Schedule

curl --request DELETE \
  --url 'https://public-api.lumiformapp.com/api/v2/schedules/739184205' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

The above command does not return any data

This endpoint deletes a specific schedule.

A schedule from another organization returns 403. An unknown or deleted schedule returns 404.

HTTP Request

DELETE https://public-api.lumiformapp.com/api/v2/schedules/<ScheduleId>

URL Parameters

Parameter	Required	Type	Example	Description
ScheduleId	Yes	Number	739184205	The ID of the schedule to delete.

Decode an RRULE

curl --request POST \
  --url 'https://public-api.lumiformapp.com/api/v2/rrules/decode' \
  --header 'Authorization: Bearer [your token here]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"rrule":"DTSTART:20241028T121625Z\nRRULE:FREQ=DAILY;BYDAY=MO,WE"}'

Request body:

{
  "rrule": "DTSTART:20241028T121625Z\nRRULE:FREQ=DAILY;BYDAY=MO,WE"
}

The above command returns JSON structured like this:

{
  "rule": {
    "start": 1730117785,
    "repeat": "custom",
    "interval": 1,
    "frequency": "weekly",
    "weekly": ["MO", "WE"]
  }
}

This endpoint turns a stored rrule string into the editor rule object used by create and update. Custom weekly rules return weekly as a list of weekday codes, ready to send back on update.

Use this flow to edit a schedule:

Get the schedule and read its stored rrule.
POST that string to /api/v2/rrules/decode.
Edit the returned rule.
Map related resource objects from retrieve to their IDs.
Update the schedule with the complete representation, including the edited rule.

The endpoint supports editor-representable forms handled by Lumiform's existing decoder. It is not a comprehensive RFC validator or canonicalizer.

Malformed RRULE syntax and frequencies rejected by the existing decoder return a 422 validation error on rrule using validation.rrule.invalid.

HTTP Request

POST https://public-api.lumiformapp.com/api/v2/rrules/decode

Request Body Parameters

Parameter	Required	Type	Example	Description
rrule	Yes	String	See above	The stored recurrence string.

A malformed RRULE or a frequency the decoder rejects returns:

{
  "code": "api.validation.errors",
  "message": "The given data was invalid.",
  "errors": {
    "rrule": [
      "validation.rrule.invalid"
    ]
  }
}