REST API

Introduction

Welcome to the Gimlet REST API. You can use our API to access Gimlet API endpoints, which can get information on questions, branches, facets, and users from your account in our database.

We have language examples for both Ruby and PHP (download). You can view the code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Getting help

If this guide isn't enough for you, please create a support ticket by contacting us at support@gimlet.us and we'll give you a hand.

Authentication

API Key Required

To get an API key, have an account administrator head to:

Account -> Branches -> Users -> (Choose an Email)

and click the "Generate API Key" button.

The API key grants a user access to add and query questions for sites they are a member of. Gimlet requires the API key to be included in all API requests to the server.

# Create a file named vars.rb for your API calls
#
# Required API Variables
DOMAIN  = 'your_domain' # Without .gimlet.us
EMAIL   = 'your_email_address'
API_KEY = 'your_api_key'
SITE_ID = 0 # Get this integer from listing branches, or looking at the URL in the new question form

<?php
// Create a file named vars.php for your API calls
$DOMAIN = "<your_gimlet_domain>";  // Without .gimlet.us
$EMAIL = "<your_email>";
$API_KEY = "<your_api_key>";
$SITE_ID = 0;  // Get this integer from listing branches, or looking at the URL in the new question form
?>

Questions

List Questions JSON

require 'date'
require 'faraday'
require 'json'

#
# List all Questions from a Branch/Site for the past 30 days as JSON
#

# Required API Variables
require './vars.rb'

# Report Dates
today = Date.today
thirty_days_ago = today - 30

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/sites/#{SITE_ID}/questions.json?start_date=#{thirty_days_ago.to_s}&end_date=#{today.to_s}"

# New connection with base URL and path
conn = Faraday.new(url: url)    # New connection with base URL
conn.basic_auth(EMAIL, API_KEY) # Set the authentication header
response = conn.get(path)       # GET API request

# Print the results
results = JSON.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require 'vars.php';

$thirty_days_ago = date('Y-m-d', strtotime('-30 days'));
$today = date('Y-m-d');

$api_url = "https://${DOMAIN}.gimlet.us/api/v1/sites/${SITE_ID}/questions?start_date=${thirty_days_ago}&end_date=${today}";

$req = curl_init($api_url);
$credentials = "${EMAIL}:${API_KEY}";
curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);
$parsed = json_decode($data);

// Do what you need with the data
var_dump($parsed);
// ?>

The above command returns JSON structured like this:

{
  "questions":
  [
    {
      "question_number": 801,
      "initials": "test",
      "email": "jane@library.org",
      "location": "Reference",
      "duration": "0-5 minutes",
      "format": "Phone",
      "asked_by": "Staff",
      "question_type": "Technology",
      "difficulty": null,
      "asked_at": "2021-03-24 10:42:00 AM",
      "question_date": "2021-03-24",
      "question_time": "10:42:00 AM",
      "question_half_hour": "10:30:00 AM",
      "question_weekday": "Wednesday",
      "added_at": "2021-03-24 10:42:32 AM",
      "tags": "example_tag",
      "site": "Humanities Library",
      "account": "Big Campus",
      "question": "Test at 10:42 AM!",
      "answer": "Test question."
    },
    {
      ...
    }
  ]
}

This endpoint retrieves all questions as JSON.

HTTP Request

GET https://<DOMAIN>.gimlet.us/api/v1/sites/<SITE_ID>/questions.json

Query Parameters

Parameter	Default	Description
start_date	null	YYYY-MM-DD
end_date	null	YYYY-MM-DD

List Questions CSV

require 'csv'
require 'date'
require 'faraday'

#
# List all Questions from a Branch/Site for the past 30 days as CSV
#

# Required API Variables
require './vars.rb'

# Report Dates
today = Date.today
thirty_days_ago = today - 30

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/sites/#{SITE_ID}/questions.csv?start_date=#{thirty_days_ago.to_s}&end_date=#{today.to_s}"

# New connection with base URL, path, and accepting CSV
conn = Faraday.new(url: url, headers: {'Accept': 'text/csv'})
conn.basic_auth(EMAIL, API_KEY) # Set the authentication header
response = conn.get(path)       # GET API request

# Print the results
results = CSV.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require 'vars.php';

$thirty_days_ago = date('Y-m-d', strtotime('-30 days'));
$today = date('Y-m-d');

$api_url = "https://${DOMAIN}.gimlet.us/api/v1/sites/${SITE_ID}/questions?start_date=${thirty_days_ago}&end_date=${today}";

$req = curl_init($api_url);
$credentials = "${EMAIL}:${API_KEY}";
curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_HTTPHEADER, array('Accept: text/csv'));
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);

echo($data);
?>

The above command returns CSV structured like this:

[["800", "test", "jane@library.org", "Reference", "0-5 minutes", "Phone", "Staff", "Technology", nil, "2021-03-24 10:40:00 AM", "2021-03-24", "10:40:00 AM", "10:30:00 AM", "Wednesday", "2021-03-24 10:40:28 AM", "example_tag", "Humanities Library", "Big Campus", "Test at 10:40 AM!", "Another test!"], ["801", "test", "jane@library.org", "Reference", "0-5 minutes", "Phone", "Staff", "Technology", nil, "2021-03-24 10:42:00 AM", "2021-03-24", "10:42:00 AM", "10:30:00 AM", "Wednesday", "2021-03-24 10:42:32 AM", "example_tag", "Humanities Library", "Big Campus", "Test at 10:42 AM!", "Another test!"][...]]

This endpoint retrieves all account questions as CSV.

HTTP Request

GET https://<DOMAIN>.gimlet.us/api/v1/sites/<SITE_ID>/questions.csv

Query Parameters

Parameter	Default	Description
start_date	null	YYYY-MM-DD
end_date	null	YYYY-MM-DD

Add Question

require 'date'
require 'faraday'

#
# Add a Question to a Branch/Site
#

# Required API Variables
require './vars.rb'

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/sites/#{SITE_ID}/questions"

date_time = DateTime.now

# Field values
fields = {}
fields["site_id"] = SITE_ID
fields["question"]= {}
fields["question"]["location_name"] = "Reference"
fields["question"]["duration_name"] = "0-5 minutes"
fields["question"]["format_name"]   = "Phone"
fields["question"]["questioner_name"] = "Staff"
fields["question"]["question_type_name"] = "Technology"
fields["question"]["difficulty_name"] = "1"
fields["question"]["tag_list"] = "example_tag"
fields["question"]["question"] = "Test at #{Time.now.strftime("%I:%M %p")}!"
fields["question"]["answer"] = "Another test!"
fields["question"]["initials"] = "test"
fields["question"]["asked_at_time"] = date_time.strftime("%I:%M %p")
fields["question"]["asked_at_date"] = date_time.strftime("%m/%d/%Y")

# New connection with base URL and path
conn = Faraday.new(url: url)        # New connection with base URL
conn.basic_auth(EMAIL, API_KEY)     # Set the authentication header
response = conn.post(path, fields)  # POST API request

# Print the results
results = response.body
puts "RESULTS: #{results.inspect}"

<?php
require 'vars.php';

$api_url = "https://${DOMAIN}.gimlet.us/api/v1/sites/${SITE_ID}/questions";

$now_time = date('G:i');
$now_date = date('m/d/Y');

// Change these to be what you actually need!
$fields = [
    "site_id" => $SITE_ID,
    "question[location_name]" => "Reception desk",
    "question[duration_name]" => "0-9 minutes",
    "question[format_name]" => "Phone",
    "question[questioner_name]" => "Staff",
    "question[question_type_name]" => "Administrative",
    "question[difficulty_name]" => "1",
    "question[tag_list]" => "",
    "question[question]" => "Test at ${now_time}!",
    "question[answer]" => "Another test!",
    "question[initials]" => "test",
    "question[asked_at_time]" => $now_time,
    "question[asked_at_date]" => $now_date,
];

$req = curl_init($api_url);
$credentials = "${EMAIL}:${API_KEY}";
curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, $fields);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);
$response_code = curl_getinfo($req, CURLINFO_RESPONSE_CODE);
// Do what you need with the data
echo("${response_code} ${data}");

// ?>

The above command returns JSON structured like this:

{
  "status": "success",
  "message": "Created"
}

This endpoint adds a new question.

HTTP Request

POST https://<DOMAIN>.gimlet.us/api/v1/sites/<SITE_ID>/questions

URL Parameters

Parameter	Example	Description
site_id	0	The ID of the brand/site for the new question
question[location_name]	Reference	The LOCATION facet value
question[duration_name]	0-5 minutes	The DURATION facet value
question[format_name]	Phone	The FORMAT facet value
question[questioner_name]	Staff	The QUESTIONER facet value (aka "Asked by")
question[question_type_name]	Technology	The TYPE facet value
question[difficulty_name]	1	The DIFFICULTY facet value
question[tag_list]	example_tag	Space separated list of tags (can leave blank)
question[question]	text	Question text (can leave blank)
question[answer]	text	Answer text (can leave blank)
question[initials]	EWL	User Initials value (can leave blank)
question[asked_at_time]	"04:22 PM"	Time of question
question[asked_at_date]	"03/24/2021"	Date of question

Branches

List Branches JSON

require 'faraday'
require 'json'

#
# List all Branches/Sites from an Account
#

# Required API Variables
require './vars.rb'

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/sites.json"

# New connection with base URL and path
conn = Faraday.new(url: url)    # New connection with base URL
conn.basic_auth(EMAIL, API_KEY) # Set the authentication header
response = conn.get(path)       # GET API request

# Print the results
results = JSON.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require './vars.php';

$api_url = "https://{$DOMAIN}.gimlet.us/api/v1/sites";

$req = curl_init($api_url);
$credentials = "{$EMAIL}:{$API_KEY}";

curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);
$parsed = json_decode($data);

// Do what you need with the data
var_dump($data);
?>

The above command returns JSON structured like this:

{
  "branches": [
    {
      "id": 2,
      "name": "Engineering Library",
      "status": "active",
      "help_url": null,
      "question_count": 422,
      "use_initials": true,
      "use_difficulty": true,
      "use_qa": true,
      "use_tagging": true
    },
    {
      "id": 1,
      "name": "Humanities Library",
      "status": "active",
      "help_url": null,
      "question_count": 380,
      "use_initials": true,
      "use_difficulty": true,
      "use_qa": true,
      "use_tagging": true
    }
  ]
}

This endpoint retrieves all account branches/sites as JSON.

HTTP Request

GET https://<DOMAIN>.gimlet.us/api/v1/sites.json

require 'faraday'
require 'json'

#
# List all Facets from a Branch/Site
#

# Required API Variables
require './vars.rb'

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/sites/#{SITE_ID}/facets.json"

# New connection with base URL and path
conn = Faraday.new(url: url)    # New connection with base URL
conn.basic_auth(EMAIL, API_KEY) # Set the authentication header
response = conn.get(path)       # GET API request

# Print the results
results = JSON.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require 'vars.php';

$api_url = "https://${DOMAIN}.gimlet.us/api/v1/sites/${SITE_ID}/facets";

$req = curl_init($api_url);
$credentials = "${EMAIL}:${API_KEY}";
curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);
$parsed = json_decode($data);

// Do what you need with the data
var_dump($parsed);
?>

The above command returns JSON structured like this:

{
  "facets": [
    {
      "id": 1,
      "type": "Duration",
      "name": "0-5 minutes"
    },
    {
      "id": 14,
      "type": "Format",
      "name": "In person"
    },
    {
      "id": 19,
      "type": "Location",
      "name": "Reference"
    },
    {
      "id": 9,
      "type": "Questioner",
      "name": "Adult"
    },
    {
      "id": 4,
      "type": "QuestionType",
      "name": "Directional"
    },
    {...}

This endpoint retrieves all account facets as JSON.

HTTP Request

GET https://<DOMAIN>.gimlet.us/api/v1/facets.json

Users

List Users JSON

require 'faraday'
require 'json'

#
# List all Users within an Account
#

# Required API Variables
require './vars.rb'

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/users.json"

# New connection with base URL and path
conn = Faraday.new(url: url)    # New connection with base URL
conn.basic_auth(EMAIL, API_KEY) # Set the authentication header
response = conn.get(path)       # GET API request

# Print the results
results = JSON.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require './vars.php';

$api_url = "https://{$DOMAIN}.gimlet.us/api/v1/users";

$req = curl_init($api_url);
$credentials = "{$EMAIL}:{$API_KEY}";

curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);
$parsed = json_decode($data);

// Do what you need with the data
var_dump($data);
?>

The above command returns JSON structured like this:

{
  "users": [
    {
      "id": 1,
      "email": "jane@library.org",
      "current_sign_in_at": "2021-03-24T10:39:48.000-05:00",
      "last_sign_in_at": "2021-03-23T13:19:42.000-05:00",
      "administrator":true,
      "sites": [
        {
          "id": 2
        },
        {
          "id": 1
        }
      ]
    },
    {...}
  ]
}

This endpoint retrieves all account users as JSON.

HTTP Request

GET https://<DOMAIN>.gimlet.us/api/v1/users.json

Add User

require 'faraday'
require 'json'

#
# Add a User to an Account
#

# Required API Variables
require './vars.rb'

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/users.json"

# Example User values
params = {}
params['user'] = {}
params['user']['email'] = 'example@library.org' # New email/user to create
params['user']['site_ids']= [1,2]            # Your site ids for membership

# New connection with base URL and path
conn = Faraday.new(url: url)              # New connection with base URL
conn.basic_auth(EMAIL, API_KEY)           # Set the authentication header
response = conn.post(path, params)        # POST API request

# Print the results
results = JSON.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require './vars.php';

$api_url = "https://{$DOMAIN}.gimlet.us/api/v1/users.json";

// Change these to be what you actually need!
$fields = [
  "user[email]=example@library.org",
  "user[site_ids][]=1",
  "user[site_ids][]=2"
];

$req = curl_init($api_url);
$credentials = "{$EMAIL}:{$API_KEY}";
curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, join($fields,'&'));
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);
$parsed = json_decode($data);

// Do what you need with the data
var_dump($parsed);
// ?>

The above command returns JSON structured like this:

{
  "id": 3,
  "email": "example@library.org",
  "site_ids": [
    2,
    1
  ]
}

This endpoint adds a new user.

HTTP Request

POST https://<DOMAIN>.gimlet.us/api/v1/users.json

URL Parameters

Parameter	Example	Description
user[email]	example@library.org	The EMAIL for a new user
user[site_ids]	[1,2]	The Branch/Site IDs for user membership

Update User

require 'faraday'
require 'json'

#
# Update a User from an Account
#
# * Add or remove user site memberships
# * Grant or revoke the account administrator role
# * Update a user's email address
#

# Required API Variables
require './vars.rb'

# Set API method variables
user_id = 1                                  # User ID to update

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/users/#{user_id}.json"

# Example User values
params = {}
params['user'] = {}
params['user']['email'] = 'jane_doe@library.org' # Update user email address
params['user']['administrator'] = true # Grant administrator role
params['user']['site_ids']= [1] # Update site ids for membership /
                                # Cannot be an empty array

# New connection with base URL and path
conn = Faraday.new(url: url)                 # New connection with base URL
conn.basic_auth(EMAIL, API_KEY)              # Set the authentication header
response = conn.put(path, params)            # PUT API request

# Print the results
results = JSON.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require './vars.php';

// Set API method variables
$user_id = 1; // User ID to update

$api_url = "https://{$DOMAIN}.gimlet.us/api/v1/users/{$user_id}.json";

// Change these to be what you actually need!
$fields = [
  "user[email]=example@library.org",
  "user[site_ids][]=1",
  "user[administrator]=true"
  "user[site_ids][]=2"
];

$req = curl_init($api_url);
$credentials = "{$EMAIL}:{$API_KEY}";
curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($req, CURLOPT_POSTFIELDS, join($fields,'&'));
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);
$parsed = json_decode($data);

// Do what you need with the data
var_dump($parsed);
// ?>

The above command returns JSON structured like this:

{
  "id": 1,
  "email": "jane_doe@library.org",
  "administrator": true,
  "site_ids": [
    2,
    1
  ]
}

This endpoint updates an existing user.

HTTP Request

PUT https://<DOMAIN>.gimlet.us/api/v1/users/<USER_ID>.json

URL Parameters

Parameter	Example	Description
user[email]	example@library.org	Update the EMAIL for an existing user
user[administrator]	true/false	Grant or revoke the account admin role
user[site_ids]	[1,2]	Update the Branch/Site IDs for user membership

Delete User

require 'faraday'
require 'json'

#
# Delete a User from an Account
#

# Required API Variables
require './vars.rb'

# Set API method variables
user_id = 1                               # User ID to destroy /
                                          # You cannot destroy your own account

# URL and Path
url = "https://#{DOMAIN}.gimlet.us"
path = "/api/v1/users/#{user_id}.json"

# New connection with base URL and path
conn = Faraday.new(url: url)              # New connection with base URL
conn.basic_auth(EMAIL, API_KEY)           # Set the authentication header
response = conn.delete(path)              # DELETE API request

# Print the results
results = JSON.parse(response.body)
puts "RESULTS: #{results.inspect}"

<?php
require './vars.php';

// Set API method variables
$user_id = 1; // User ID to delete
              // You cannot destroy your own account

$api_url = "https://{$DOMAIN}.gimlet.us/api/v1/users/{$user_id}.json";

$req = curl_init($api_url);
$credentials = "{$EMAIL}:{$API_KEY}";
curl_setopt($req, CURLOPT_USERPWD, $credentials);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);

$data = curl_exec($req);

// Do what you need with the data
var_dump($data);

// ?>

The above command returns JSON structured like this:

{"status":"success"}

This endpoint deletes a user.

HTTP Request

DELETE https://<DOMAIN>.gimlet.us/api/v1/users/<USER_ID>.json

REST API

Introduction

Getting help

Authentication

API Key Required

Questions

List Questions JSON

HTTP Request

Query Parameters

List Questions CSV

HTTP Request

Query Parameters

Add Question

HTTP Request

URL Parameters

Branches

List Branches JSON

HTTP Request

Facets

List Facets JSON

HTTP Request

Users

List Users JSON

HTTP Request

Add User

HTTP Request

URL Parameters

Update User

HTTP Request

URL Parameters

Delete User

HTTP Request