NAV
shell

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:

  1. Concatenate your API key and API secret with a colon like so: apikey:apisecret
  2. Generate a base64 encoded token from your key and secret concatenated string. You can use this website for example.
  3. 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.
  4. 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]

Filters

Get All Users

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

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 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

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": "« 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 »",
        "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.

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.

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 are incorrectly specified. Check the examples!
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.