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.

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: 0e3aad3f7031fcc655b349e5709c93fc

Responses

Response samples

Content type

application/json

{"message": "SUCCESS",
"data": {"docs": [{"issueID": "aeacd1a9-89b6-4249-beda-eb52089df8e3",
"createdAt": "2023-08-29T05:09:59.609Z",
"answer": 3,
"assignedDepartments": ["departmentA",
"departmentB"
],
"assignedTo": "User Sample",
"category": "Category A",
"createdBy": "User Sample",
"resolvedBy": "User Sample",
"status": "open",
"resolvedAt": "2023-08-29T05:09:59.609Z",
"dueAt": "2023-08-29T05:09:59.609Z",
"siteName": "Sample Site",
"questions": "This is sample questions A.",
"createdDepartment": "Sample Department",
"questionnaire": "Sample Questionnaire",
"priority": "Low",
"severity": "yellow",
"origin": "report"
}
],
"limit": 100,
"offset": 0,
"totalDocs": 100,
"totalPage": 1
}
}

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.