FAQ content

Create a POST API for a custom, shared, reference (individual transactions), or gate count dataset

In this article

Like widgets, an API (or Application Programming Interface) allows you to post data to a custom, shared, reference (individual transactions), or gate count dataset. The big difference is that an API allows you to create your own custom app or script that posts data from another source.

For example, if your security gate has an API for retrieving gate count readings, you could develop your own script that takes the data from your gate and post it to your gate count dataset in LibInsight.

As you can tell, APIs are intended for users who have some programming know-how. If you are looking for a simple way to manually record data from outside of LibInsight, consider creating widgets instead.

Creating an API

  1. Log into LibInsight and go to Admin > Widgets and APIs.
  2. Click on the  Create API button.

the Create API button on the Widgets and APIs page

  1. In the New API window, choose a supported dataset from the Select Dataset dropdown. You can create APIs for the following dataset types:
    • Custom
    • Shared
    • Reference (individual transactions)
    • Gate count
  2. Enter a Name for your API. This will help you identify it later.
  3. If you selected a gate count dataset, use the Select Library dropdown to choose the library to which you'll be posting data. Select All Libraries if you'd like to be able to post to all libraries using your API.
  4. Save your new API.

Options in the New API window 

Viewing an API's code

  1. On the Widgets and APIs page, locate your API in the list and click on its code () button in the Actions column.

The code button in the Actions column

  1. In the API Code window, you'll find an overview of the API's data, parameters, and response data.
    1. Form Data: this provides you with the API's unique POST URL for receiving data.
    2. Form Data parameters: this lists each available field name in the dataset, along with it's required/optional status and field type. The field type will indicate the correct format for the data you're posting to the field (so you don't post text to a date field, for example).
    3. Return: this provides a list of the possible responses that the API will return. This will indicate whether or not your POST request was successful.
    4. Sending multiple data at once: if you want to post multiple records in one request, you can send up to 500 records using the unique POST URL listed here. When using this option, you will need to post an array of JSON objects, with one object per record.
  2. When finished, click the Close button.

The API Code modal

For gate count APIs: unlike entering data manually via the Record Data page or a widget, rollover values are not automatically calculated when posting data using the API. As a result, if your gate_end is less than your gate_start (meaning your gate reached its maximum amount and rolled over to zero), you must provide the adjusted gate_end value. For example: if your gate_start is 90, your gate_end is 10, and your gate rolls over after 99, you would need to post a gate_end of 110 to ensure an accurate count of visitors for that time period.

Using the API

The API can be called using an HTTP POST request. For your request to be successful, please note the following:

  • Only System Field and Custom Field keys can be passed
    • System Field keys are optional (they can be omitted from the POST request body)
    • Custom Field keys are required to be passed, but their values are optional (unless a specific field has been set as required in your dataset's settings, in which case you would have to pass a value for that field)
  • You cannot pass a Custom Field key that is not listed in the API code (see above section)