BeepQuest Api Documentation

Welcome to our Api documentation. Here you'll find all information on connecting, needed parameters and result information. We are always adding new functionality, if you have a request or issue, go to our main github repository. If you're not a BeepQuest subscription client, stop by our main web page to check out all the benefit of a tool like BeepQuest on supervision processes.

Initial Considerations

As a BeepQuest subscription client, you have the possibility to make use of your data on external systems, and also include information on our platform. On GH control panel, you'll have to configure or create 3 types or token depending on the information you need to access. These tokens are:

  • Application Tokens
  • Module Tokens
  • Visit Modules

You can create multiple token of each kind, and they identify the corresponding model on the platform.

We now review how can we create each type of token.

Application Tokens

These are the main identification token for our subscription, for creating it, go to General > API Configuration

ApplicationTokens

Press App Tokens button and then Create Token, a confirmation modal will appear on the button of the page, press Ok, and the Token will be created. You can copy the token to the clipboard from the corresponding button on the table.

ApplicationTokens

ApplicationTokens

ApplicationTokens

This token is required in all requests to our api, as BQAPPTOK.

Module Tokens

You'll need module tokens to query historical data on our API. For modules go to Content > Modules and search for your needed question engine module. Select edit and you'll see a colapsed panel called API

Visit Tokens

Lastly visit tokens are needed to query historical data on a visit level. For visits go to Visits > Visits and search for the needed visit and press edit button. Similarly you'll see an API panel where

Summary

All the information generated by question engine and visit processes is available to query through our API. Visits are composed by several question engine answers and you may need to query both endpoints to complete the information needed according to your requirements.

Remember that responses for your data depends on current configuration. Question Engine Modules have a series of fields of different types, and also on visits, they can have multiple different question engine answers as entry, exit and activities.

Get question module answers

Query for question engine module answers by app and module, for the given parameters.

Headers

Key Value
BQAPPTOK Application Api Token
BQMODTOK Module Api Token

Query String Parameters

Field Type Required Description
users string No
(Defaults all)
One or more user emails, comma separated
initialDate datetime
ISO Dates
Si initial data range
finalDate datetime
ISO Dates
No end date range
limit int Si Query results limit
skip int No
(Default 0)
Offset results

Response Structure

Field Name Type Description
total int Query answers count
list user [Object] email string
firstName string
lastName string
answers [Array] [Field Name i] string o Array Answers configured on module
correctAnswers int If trivia module configured
result int If trivia module configured
created string
(ISO Date)
Creation Date
GET
/v1/question-module-answers

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/question-module-answers', {
  method: 'GET',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}',
    'BQMODTOK': '{BQMODTOK}'
  }
});

Example response

{
  "total": 2,
  "list": [
    {
      "_id": "{_id}}",
      "user": {
        "firstName": "{firstName}",
        "lastName": "{lastName}",
        "email": "{email}"
      },
      "location": {
        "type": "Point",
        "coordinates": [
          0,
          0
        ]
      },
      "result": 0,
      "correctAnswers": 0,
      "timezone": "America/Mexico_City",
      "created": "{timestamp}}",
      "answers": {
        "field1": "{field1}",
        "field2": "{field2}",
        "field3": "{field3}"
      }
    },
    {
      "_id": "{_id}}",
      "user": {
        "firstName": "{firstName}",
        "lastName": "{lastName}",
        "email": "{email}"
      },
      "location": {
        "type": "Point",
        "coordinates": [
          0,
          0
        ]
      },
      "result": 0,
      "correctAnswers": 0,
      "timezone": "America/Mexico_City",
      "created": "{timestamp}}",
      "answers": {
        "field1": "{field1}",
        "field2": "{field2}",
        "field3": "{field3}"
      }
    }
  ]
}

Get question engine module answer

Get individual question engine module answer.

Headers

Key Value
BQAPPTOK Application Api Token
BQMODTOK Module Api Token

Query String Parameters

Field Type Required Description
users string No
(Defaults all)
One or more user emails, comma separated
initialDate datetime
ISO Dates
Si initial data range
finalDate datetime
ISO Dates
No end date range
limit int Si Query results limit
skip int No
(Default 0)
Offset results
GET
/v1/question-module-answers/{quesitonAnswerId}

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/question-module-answers/{quesitonAnswerId}', {
    method: 'GET',
    headers: {
      'BQAPPTOK': '{BQAPPTOK}',
      'BQMODTOK': '{BQMODTOK}'
    }
  });

Example response

{
  "_id": "{_id}}",
  "user": {
    "firstName": "{firstName}",
    "lastName": "{lastName}",
    "email": "{email}"
  },
  "location": {
    "type": "Point",
    "coordinates": [
      0,
      0
    ]
  },
  "result": 0,
  "correctAnswers": 0,
  "timezone": "America/Mexico_City",
  "created": "{timestamp}}",
  "answers": {
    "field1": "{field1}",
    "field2": "{field2}",
    "field3": "{field3}"
  }
}

Get visit answers

Query for visit answers by app and visit for the given parameters.

Headers

Key Value
BQAPPTOK Application Api Token
BQVISTOK Visit Api Token

Query String Parameters

Field Type Required Description
users string No
(Defaults all)
One or more user emails, comma separated
initialDate datetime
ISO Dates
Si initial data range
finalDate datetime
ISO Dates
No end date range
limit int Si Query results limit
skip int No
(Default 0)
Offset results

Response Structure

Campo Nombre Tipo Descripción
total int Número de resultados de query
list visitId string Visit Id
  checkInDate string
(ISO Date)
Check In Date for Visit
  checkOutDate string
(ISO Date)
Check Out Date for Visit
  checkIn [Object] module string Module Id
  moduleName string Module Name
  moduleAnswerId string Answer Id
  checkOut [Object] module string Module Id
  moduleName string Module Name
  moduleAnswerId string Answer Id
  activities [Array Object] module string Module Id
  moduleName string Module Name
  moduleAnswerId string Answer Id
  user [Object] email string
  firstName string
  lastName string
  extra array {object}
  userId string User Id
  folio string Auto generated folio if configured
  keys string array Keys for configured key fields
  keysAnswers [Object] [Nombre del campo i] string o Array Answers for check in module
  created string
(ISO Date)
Creation Date
GET
/v1/visit-answers

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/visit-answers', {
    method: 'GET',
    headers: {
      'BQAPPTOK': '{BQAPPTOK}',
      'BQVISTOK': '{BQVISTOK}'
    }
  });

Example response

{
  "total": 2,
  "list": [
    {
      "_id": "{_id}}",
      "visitId": "{visitId}",
      "checkIn": {
        "moduleAnswerId": "{moduleAnswerId}"
      },
      "checkOut": {
        "moduleAnswerId": "{moduleAnswerId}"
      },
      "activities": [
        {
          "module": "{moduleId}}",
          "moduleName": "{moduleName}",
          "moduleAnswerId": "{moduleAnswerId}"
        },
        {
          "module": "{moduleId}}",
          "moduleName": "{moduleName}",
          "moduleAnswerId": "{moduleAnswerId}"
        }
      ],
      "userId": "{userId}",
      "user": {
        "firstName": "{firstName}",
        "lastName": "{lastName}",
        "email": "{email}",
        "extra": []
      },
      "checkInDate": "{timestamp}",
      "checkOutDate": "{timestamp}",
      "keys": [
        "key1",
        "key2"
      ],
      "keysAnswers": {
        "key1": "{keyAnswer1}",
        "key2": "{keyAnswer2}",
        "fieldN": [
          "{value}}"
        ],
        "fieldM": "{value}}"
      },
      "approvalStatus": "{approvalStatus}",
      "created": "{timestamp}"
    },
    {
      "_id": "{_id}}",
      "visitId": "{visitId}",
      "checkIn": {
        "moduleAnswerId": "{moduleAnswerId}"
      },
      "checkOut": {
        "moduleAnswerId": "{moduleAnswerId}"
      },
      "activities": [
        {
          "module": "{moduleId}}",
          "moduleName": "{moduleName}",
          "moduleAnswerId": "{moduleAnswerId}"
        }
      ],
      "userId": "{userId}",
      "user": {
        "firstName": "{firstName}",
        "lastName": "{lastName}",
        "email": "{email}",
        "extra": []
      },
      "checkInDate": "{timestamp}",
      "checkOutDate": "{timestamp}",
      "keys": [
        "key1",
        "key2"
      ],
      "keysAnswers": {
        "key1": "{keyAnswer1}",
        "key2": "{keyAnswer2}",
        "fieldN": [
          "{value}}"
        ],
        "fieldM": "{value}}"
      },
      "approvalStatus": "{approvalStatus}",
      "created": "{timestamp}"
    }
  ]
}

Subscription Data

There are some parts of a subscription configuration that can be queried for getting information on how to process and where to connect. Some of these operations on our api allows getting information needed for other endpoints. e.g. webhoks

Get subscription data

Get basic information on subscription and validate your app token.

Headers

Key Value
BQAPPTOK Application Api Token

Response Structure

Field Name Type Description
app [Object] _id string
name string
description string
icon string(url)
GET
/v1/subscription

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription', {
  method: 'GET',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  }
});

Example response

{
  "app": {
    "_id": "{subscription_id}",
    "name": "{subscription_name}",
    "description": "{description}",
    "icon": "{image_route}.png",
    "iconThumbnails": {
      "original": "https://storage.googleapis.com/{image_route}.png"
    }
  }
}

Get Question Engine Modules for subscription

Get different active question engine modules for a subscription.

Headers

Key Value
BQAPPTOK Application Api Token
GET
/v1/subscription/question-modules

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/question-modules', {
  method: 'GET',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  }
});

Example response

[
  {
    "_id": "{module_id}",
    "module": {
      "_id": "{question_module_id}",
      "name": "{module_name}"
    }
  },
  {
    "_id": "{module_id}",
    "module": {
      "_id": "{question_module_id}",
      "name": "{module_name}"
    }
  },
  {
    "_id": "{module_id}",
    "module": {
      "_id": "{question_module_id}",
      "name": "{module_name}"
    }
  }
]

Get Individual Question Engine Module Configuration

Gets field configuration for a question engine module.

Headers

Key Value
BQAPPTOK Application Api Token

Params

Key Value
moduleId Module Id for required config
GET
/v1/subscription/question-modules/:moduleId/config

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/question-modules/{moduleId}/config', {
  method: 'GET',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  }
});

Example response

{
  "_id": "{module_id}",
  "app": "{subscription_id}",
  "name": "{module_name}",
  "properties": {
    "fields": [
      {
        "key": "{field_key}",
        "type": {field_type},
        "label": "{field_label}"
      },
      {
        "key": "{field_key}",
        "type": {field_type},
        "label": "{field_label}"
      }
    ]
  },
  "created": "{date_created}"
}

Get Visits for Subscription

Get different active visits for a subscription.

Headers

Key Value
BQAPPTOK Application Api Token
GET
/v1/subscription/visits

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/visits', {
  method: 'GET',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  }
});

Example response

[
  {
    "_id": "{visit_id}",
    "name": "{visit_name}"
  },
  {
    "_id": "{visit_id}",
    "name": "{visit_name}"
  }
]
Show examples in:
BQ Logo
BeepQuest API Documentation