Nimbly Technologies Logo
API docs by Redocly

Nimbly API Documentation (1.0.0)

URL: https://hellonimbly.com License: MIT

Welcome to the API documentation for Nimbly Technologies. Our mission is to make your integration experience seamless and efficient. Whether you're a seasoned developer or just getting started, this documentation is your gateway to understanding and leveraging the full potential of Nimbly's API. Dive in to explore endpoints, authentication methods, data formats, and everything you need to successfully integrate with our services.

Authentication

To access our Nimbly API, you need to authenticate using a secret token as an API key. API keys are a simple and secure way to identify your application when making requests to our API.

Obtaining the API Key

To obtain API keys for authentication, please reach out to our team. Once your request for API keys has been approved, we will securely send them to you via email, ensuring that you have the necessary credentials to access our API.

Your API keys are sensitive credentials. Avoid sharing them publicly to maintain the confidentiality of your data and the security of your API resources.

Using the API Key

For authenticating your API requests, include your API key in the request headers as shown below:

GET /reports
x-api-key: YOUR_API_KEY

Replace YOUR_API_KEY with the actual API key you received from our team.

This x-api-key header is used to allow the server to identify and authorize your organization account. Please note that any API call made without including the 'x-api-key' header will result in a failed request.

Rate Limits

Our Nimbly API use rate limiter to ensure equitable access to our API resources while maintaining system stability. This document outlines our rate limiting policies, how to handle rate limit errors, and tips for optimizing your API usage within these limits.

Rate Limiting Policy

Our rate limiter enforces the following rate limiting policy:

  • Rate Limit: You can make up to 3 requests per second (RPS) to our API per API key.

Error Response

When you exceed the rate limit, our API will respond with a 429 Too Many Requests status code. This indicates that you have reached the maximum allowed request rate. The response will include additional information in the headers for your reference:

  • X-RateLimit-Limit: The total number of requests allowed per second.
  • X-RateLimit-Remaining: The number of requests remaining in the current rate-limiting window.

Here's an example of a rate-limited response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 0

{
  "message": "Limit Exceeded"
}

Guidelines

To ensure smooth API interactions and avoid rate-limiting errors:

  • Implement Backoff: If you receive a 429 error, implement a backoff mechanism in your code to retry the request after a delay.
  • Monitor Headers: Pay attention to the X-RateLimit-Limit and X-RateLimit-Remaining headers in the response to track your rate limit usage.
  • Cache Data: Consider caching data locally to reduce the number of API requests when possible.
  • Contact Support: If you consistently encounter rate-limiting issues, please contact our support team for assistance or to discuss rate limit adjustments.

By following these guidelines, you can work effectively within our rate limits and ensure a smooth experience while using the Nimbly API.

Postman Collections

Simplify your API interaction with our Exported Postman Collections. This collection contains a curated set of API endpoints and request examples that will accelerate your development and integration processes.

How to Get Started

Simply follow these steps to start interact with our Nimbly API

  • Download Postman if you haven't already.
  • Download our Exported Postman Collection (by Right-click the link and choose "Save link as…") and import it into your Postman workspace.
  • Begin exploring our API by making requests, testing responses, and integrating the functionality into your applications.

Statistics

Endpoints for accessing Nimbly statistics dashboard data.

Report Dashboard

Fetches report analytics based on the specified metric.

Authorizations:
API Keys
header Parameters
x-api-key
required
string
Request Body schema: application/json
required
startDate
required
string <date>
endDate
required
string <date>
metric
required
string
Enum: "rcr" "report-overview" "report-insight-overview" "reportList" "reportChart" "reportPieChart"
viewBy
string
Enum: "site" "completeCount" "missedCount" "rcr" "completionTime" "submittedCount" "reportStatus" "reportType"
groupBy
string
Enum: "site" "department" "user" "questionnaire" "date" "siteGroup" "reportStatus" "reportType"
groupByID
string
sortBy
string
sortDirection
string
Enum: "asc" "desc"
limit
number
period
string
Enum: "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "YEARLY"
siteIDs
Array of strings
departmentIDs
Array of strings
userIDs
Array of strings
questionnaireIDs
Array of strings
reportStatus
Array of strings

Responses

Request samples

Content type
application/json
{
  • "startDate": "2026-01-01",
  • "endDate": "2026-01-31",
  • "metric": "rcr",
  • "viewBy": "site",
  • "groupBy": "site",
  • "groupByID": "string",
  • "sortBy": "string",
  • "sortDirection": "asc",
  • "limit": 10,
  • "period": "DAILY",
  • "siteIDs": [
    ],
  • "departmentIDs": [
    ],
  • "userIDs": [
    ],
  • "questionnaireIDs": [
    ],
  • "reportStatus": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": { }
}

Issue Dashboard

Fetches issue analytics based on the specified metric.

Authorizations:
API Keys
header Parameters
x-api-key
required
string
Request Body schema: application/json
required
startDate
required
string <date>
endDate
required
string <date>
metric
required
string
Enum: "issue-voc" "irr" "health" "issue-overview" "issue-insight-overview" "heatmap" "issueList" "issueInsightList" "issueChart" "issuePieChart" "issueReoccurred"
viewBy
string
Enum: "site" "irr" "openIssueCount" "irrTime" "issueFlag" "issueRedFlag"
groupBy
string
Enum: "site" "department" "user" "questionnaire" "category" "issueSeverity" "issueStatus" "issuePriority" "issueSecondaryStatus" "approvalStatus"
groupByID
string
primaryStatus
Array of strings
Items Enum: "open" "in-progress" "in-review" "blocked" "resolved"
priority
Array of strings
Items Enum: "high" "medium" "low"
categories
Array of strings

Responses

Request samples

Content type
application/json
{
  • "startDate": "2026-01-01",
  • "endDate": "2026-01-31",
  • "metric": "issue-voc",
  • "viewBy": "site",
  • "groupBy": "site",
  • "groupByID": "string",
  • "primaryStatus": [
    ],
  • "priority": [
    ],
  • "categories": [
    ]
}

Home Page Metrics

Fetches real-time platform statistics overview.

Authorizations:
API Keys
header Parameters
x-api-key
required
string

Responses

Search

Endpoints for searching Nimbly entities (sites, users, questionnaires).

Search Sites

Search sites by name. Returns siteID, name, and city.

Authorizations:
API Keys
query Parameters
search
required
string

Site name or partial name (case-insensitive)

page
number
Default: 1
limit
number <= 100
Default: 10
header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": {
    }
}

Search Users

Search active users by name or email.

Authorizations:
API Keys
query Parameters
search
required
string

User name, partial name, or email

page
number
Default: 1
limit
number <= 100
Default: 10
header Parameters
x-api-key
required
string

Responses

Search Questionnaires

Search questionnaires by title. Returns questionnaireIndexID and title.

Authorizations:
API Keys
query Parameters
search
required
string

Questionnaire title or partial title

page
number
Default: 1
limit
number <= 100
Default: 10
header Parameters
x-api-key
required
string

Responses

Issues

Nimbly API for issue's related usecase. Issues are generated based on your report's answer. One example for this usecase is to get list of all issues created within your organization.

List All Issues

Returns list of your issue's data. The returned data will be based on the query, using pagination format.

Authorizations:
API Keys
query Parameters
site_name
string (optional)
Example: site_name=Store A

Multiple Example: site_name=siteA&site_name=siteB

Filter based on the site name. Multiple site name query is supported.

created_dept
string (optional)
Example: created_dept=Department A

Multiple Example: created_dept=deptA&created_dept=deptB

Filter based on the reporter department name. Multiple reporter department name query is supported.

assigned_dept
string (optional)
Example: assigned_dept=Department A

Multiple Example: assigned_dept=deptA&assigned_dept=deptB

Filter based on the assigned department name. Multiple assigned department name query is supported.

qnr_name
string (optional)
Example: qnr_name=FnB - Coffee Shop

Multiple Example: qnr_name=qnrA&qnr_name=qnrB

Filter based on the questionnaire name. Multiple questionnaire name query is supported.

title
string (optional)
Example: title=Food items stored properly

Multiple Example: title=titleA&title=titleB

Filter based on the issue's title. Multiple issue's title query is supported.

category_name
string (optional)
Example: category_name=Food/Beverage Safety

Multiple Example: category_name=catA&category_name=catB

Filter based on the issue's category name. Multiple category name query is supported.

created_by
string (optional)
Example: created_by=Auditor A

Multiple Example: created_by=userA&created_by=userB

Filter based on the issue's creator name. Multiple issue's creator name query is supported.

assigned_to
string (optional)
Example: assigned_to=Auditor A

Multiple Example: assigned_to=userA&assigned_to=userB

Filter based on the issue's assignee name. Multiple issue's assignee name query is supported.

member
string (optional)
Example: member=Auditor A

Multiple Example: member=userA&member=userB

Filter based on the issue's member name. Multiple issue's member name query is supported.

status
string (optional)
Enum: "open" "resolved" "expired" "blocked" "in-review" "in-progress"
Example: status=open

Multiple Example: status=open&status=resolved

Filter based on the issue's status. Multiple issue's status query is supported.

severity
string (optional)
Enum: "red" "yellow"
Example: severity=yellow

Multiple Example: severity=red&severity=yellow

Filter based on the issue's severity. Multiple issue's severity query is supported.

priority
string (optional)
Enum: "low" "medium" "high"
Example: priority=medium

Multiple Example: priority=medium&priority=high

Filter based on the issue's priority. Multiple issue's priority query is supported.

origin
string (optional)
Enum: "report" "report-adhoc" "report-scheduled" "manual-addition" "customer-feedback"
Example: origin=report-scheduled

Multiple Example: origin=report-adhoc&origin=report-scheduled

Filter based on the issue's origin. Multiple issue's origin query is supported.

date_filter_type
string (optional)
Enum: "created_date" "resolved_date" "due_date"
Example: date_filter_type=created_date

An enum that indicates the date type filter. It will affect on how start_date and end_date should be based on.

  • created_date - filter will be based on when the issue is created
  • resolved_date - filter will be based on when the issue is resolved
  • due_date - filter will be based on when the issue is due
start_date
string (optional) <date>
Example: start_date=2023-10-23

String with format of YYYY-MM-DD as a start date filter on the requested issue. The meaning behind will follow the value from date_filter_type.

end_date
string (optional) <date>
Example: end_date=2023-11-23

String with format of YYYY-MM-DD as an end date filter on the requested issue. The meaning behind will follow the value from date_filter_type.

sort_by
string (optional)
Enum: "created_date" "resolved_date" "due_date"
Example: sort_by=created_date

An enum that indicates the date where sorting is based on.

  • created_date - sort will be based on when the issue is created
  • resolved_date - sort will be based on when the issue is resolved
  • due_date - sort will be based on when the issue is due
sort_type
string (optional)
Enum: "asc" "desc"
Example: sort_type=asc

An enum that indicates the sorting type. It will affect on how sort_by should be based on.

  • asc - sort will be done in ascending rule
  • desc - sort will be done in descending rule
limit
number (optional)
Example: limit=100

Limit number on how many data will be returned. Limit can range between 1 and 100, with default number is 100.

offset
number (optional)

Offset number on how many data will be skipped before returning the next data. Offset can range between 0 and total sites, with default number is 0.

header Parameters
x-api-key
required
string
Example: 4921f457d0277b412e13dc3e38df27e8

Responses

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "data": {
    }
}

Get Issue by ID

Returns a single issue detail by its unique identifier.

Authorizations:
API Keys
path Parameters
issueID
required
string <uuid>

Unique identifier of the issue (UUID)

header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": { }
}

Get Issue Status History

Returns the status change audit trail for an issue.

Authorizations:
API Keys
path Parameters
issueID
required
string <uuid>

Unique identifier of the issue (UUID)

header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": [
    ]
}

Reports

Nimbly API for report's related usecase. Reports are generated when you do a checklist in the form of questionnaire from the nimbly app. One example for this usecase is to get list of all reports generated within your organization.

List All Reports

Returns list of your report's data. The returned data will be based on the query, using pagination format.

Authorizations:
API Keys
query Parameters
site_name
string (optional)
Example: site_name=Store A

Multiple Example: site_name=siteA&site_name=siteB

Filter based on the site name. Multiple site name query is supported.

dept_name
string (optional)
Example: dept_name=Department A

Multiple Example: dept_name=deptA&dept_name=deptB

Filter based on the department name. Multiple department name query is supported.

qnr_name
string (optional)
Example: qnr_name=FnB - Coffee Shop

Multiple Example: qnr_name=questionnaireA&qnr_name=questionnaireB

Filter based on the questionnaire name. Multiple questionnaire name query is supported.

user_name
string (optional)
Example: user_name=Auditor A

Multiple Example: qnr_name=qnrA&qnr_name=qnrB

Filter based on the user/auditor name. Multiple user name query is supported.

date_filter_type
string (optional)
Enum: "scheduled_date" "submitted_date"
Example: date_filter_type=scheduled_date

An enum that indicates the date type filter. It will affect on how start_date and end_date should be based on.

  • scheduled_date - filter will be based on when the schedule for this report is
  • submitted_date - filter will be based on when the report is submitted
start_date
string (optional) <date>
Example: start_date=2023-10-23

String with format of YYYY-MM-DD as a start date filter on the requested report. The meaning behind will follow the value from date_filter_type.

end_date
string (optional) <date>
Example: end_date=2023-11-23

String with format of YYYY-MM-DD as a end date filter on the requested report. The meaning behind will follow the value from date_filter_type.

pagination_type
string (optional)
Enum: "record" "site"
Example: pagination_type=record

An enum that indicates pagination type. It will affect how data is divided using the limit and offset field. The default of this field is record

  • record - data will be paginated based on total number of report records.
  • site - data will be paginated based on total number of site.
limit
number (optional)
Example: limit=100

Limit number on how many data will be returned. If pagination_type is site, the data will be sorted based on the site name before the pagination. Limit can range between 1 and 100, with default number is 100.

offset
number (optional)

Offset number on how many data will be skipped before returning the next data. If pagination_type is site, the data will be sorted based on the site name before the pagination. Offset can range between 0 and total sites, with default number is 0.

header Parameters
x-api-key
required
string
Example: 4921f457d0277b412e13dc3e38df27e8

Responses

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "data": {
    }
}

Get Report by ID

Returns a single report detail by its unique identifier.

Authorizations:
API Keys
path Parameters
reportID
required
string

MongoDB identifier of the report

header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": { }
}

Sites

Nimbly API for site's related usecase. Sites are locations where reports and issues are generated within your organization. One example for this usecase is to get list of all sites created within your organization.

List All Sites

Returns list of your site's data. The returned data will be based on the query, using pagination format.

Authorizations:
API Keys
query Parameters
site_name
string (optional)
Example: site_name=Store A

Multiple Example: site_name=siteA&site_name=siteB

Filter based on the site name. Multiple site name query is supported.

dept_name
string (optional)
Example: dept_name=Department A

Multiple Example: dept_name=deptA&dept_name=deptB

Filter based on the department name. Multiple department name query is supported.

limit
number (optional)
Example: limit=100

Limit number on how many data will be returned. Limit can range between 1 and 100, with default number is 100.

offset
number (optional)

Offset number on how many data will be skipped before returning the next data. Offset can range between 0 and total sites, with default number is 0.

header Parameters
x-api-key
required
string
Example: 4921f457d0277b412e13dc3e38df27e8

Responses

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "data": {
    }
}

Get Site by ID

Returns a single site detail by its unique identifier.

Authorizations:
API Keys
path Parameters
siteID
required
string <uuid>

Unique identifier of the site (UUID)

header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": { }
}

Users

Endpoints for listing and retrieving user details.

List Users

Returns a paginated list of active users. Optionally filter by name or email.

Authorizations:
API Keys
query Parameters
search
string

User name, partial name, or email

startDate
required
string <date>
Example: startDate=2026-05-01
endDate
required
string <date>
Example: endDate=2026-05-31
page
number
Default: 1
limit
number <= 100
Default: 10
header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": {
    }
}

Get User by ID

Returns a single user detail by their unique identifier.

Authorizations:
API Keys
path Parameters
userID
required
string

Unique identifier of the user

header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": { }
}

Questionnaires

Endpoints for listing questionnaires.

List Questionnaires

Returns a paginated list of questionnaires. Optionally filter by title.

Authorizations:
API Keys
query Parameters
search
string

Questionnaire title or partial title

page
number
Default: 1
limit
number <= 100
Default: 10
header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": {
    }
}

Schedules

Endpoints for listing schedules.

List Schedules

Returns a paginated list of active schedules.

Authorizations:
API Keys
query Parameters
page
number
Default: 1
limit
number <= 100
Default: 10
header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": {
    }
}

Departments

Endpoints for listing departments.

List Departments

Returns a paginated list of departments. Optionally filter by name.

Authorizations:
API Keys
query Parameters
search
string

Department name or partial name

page
number
Default: 1
limit
number <= 100
Default: 10
header Parameters
x-api-key
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data": {
    }
}