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}"
    }
  ]
}

Question Engine Module Webhooks

Our API allows connecting via webhooks to the main data events on the platform, question-engine-answers and visits. For each of these models, you first need to subscribe your endpoint through API to receive notifications. When you don't need the hook anymore, you should unsubscribe via the corresponding endpoint.

Webhook creation to question-engine-answer events

For being able to receive notifications on the creation of question engine answers, you should use this endpoint. For registering a webhook you first need to know the corresponding id for the question engine module. You can get this id by querying the corresponding Get Question Engine Modules for subscription endpoint. This endpoint returns a field called secret you can use this to make sure you are reacting to the official BeepQuest webhook.

Headers

Key Value
BQAPPTOK Application Api Token

Request

Field Name Type Description
body Object
url string Url to register. Required
POST
/v1/subscription/question-modules/:module/hook

Example request

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

Example response

{
  "active": true,
  "_id": "{hook_id}",
  "app": "{subscription_id}",
  "module": "{module_id}",
  "secret": "{validation_secret}",
  "url": "{url_registered}",
  "created": "{date_registered}",
  "__v": 0
}

Get all webhooks registered to question engine

You can review status of all registered webhooks for any question engine. This way you can make sure it is active or review which ones you are not using anymore and delete them.

Headers

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

Example request

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

Example response

[
  {
    "active": {
      active
    },
    "_id": "{hook_id}",
    "app": "{subscription_id}",
    "module": "{module_id}",
    "secret": "{validation_secret}",
    "url": "{url_registered}",
    "created": "{date_registered}",
    "__v": 0
  }
  ...
]

Deactivate webhook registered to question engine

If your configured endpoint changed, or you need to suspend notifications to your api, you need to delete the hook configured previously using this endpoint.

Headers

Key Value
BQAPPTOK Application Api Token
DELETE
/v1/subscription/question-modules/:module/hook/:hook

Example request

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

Example response

{
  "active": false,
  "_id": "{hook_id}",
  "app": "{subscription_id}",
  "module": "{module_id}",
  "secret": "{validation_secret}",
  "url": "{url_registered}",
  "created": "{date_registered}",
  "__v": 0
}

Visit Webhooks

You can connect via webhooks to visit answers events too. Endpoints are similar to question engine module ones. Remember you need to get the corresponding visit id first to subscribe.

Webhook creation to visit-answer events

For being able to receive notifications on the creation of visit answers, you should use this endpoint. For registering a webhook you first need to know the corresponding id for the visit. You can get this id by querying the corresponding Get Visits for Subscription endpoint. This endpoint returns a field called secret you can use this to make sure you are reacting to the official BeepQuest webhook. For this webhook subscription you need to specify the notification mode on the request parameters.

Note At this time, only exit notification is implemented, this means that your endpoint will be called after exit question engine on visit is completed.

Headers

Key Value
BQAPPTOK Application Api Token

Request

Field Name Type Description
body Object
url string Url to register. Required
exit boolean Configure notification on exit. Required
POST
/v1/subscription/visit/:visit/hook

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/visit/{visit_id}/hook', {
    method: 'GET',
    headers: {
      'BQAPPTOK': '{BQAPPTOK}'
    },
    body: JSON.stringify({
      "url": "{url}",
      "exit": true
    })
  });

Example response

{
  "active": true,
  "_id": "{hook_id}",
  "app": "{subscription_id}",
  "visit": "{visit_id}",
  "secret": "{validation_secret}",
  "modes": {
    "entry": true,
    "activities": false,
    "exit": false
  },
  "url": "{url_registered}",
  "created": "{date_registered}",
  "__v": 0
}

Get all webhooks registered to visit

Headers

Key Value
BQAPPTOK Application Api Token
GET
/v1/subscription/visit/:visit/hooks

Example request

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

Example response

[
  {
    "active": {true},
    "_id": "{hook_id}",
    "app": "{subscription_id}",
    "visit": "{visit_id}",
    "secret": "{validation_secret}",
    "modes": {
      "entry": true,
      "activities": false,
      "exit": false
    },
    "url": "{url_registered}",
    "created": "{date_registered}",
    "__v": 0
  },
  ...
]

Deactivate webhook registered to visit

Headers

Key Value
BQAPPTOK Application Api Token
DELETE
/v1/subscription/visit/:visit/hook/:hook

Example request

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

Example response

{
  "active": false,
  "_id": "{hook_id}",
  "app": "{subscription_id}",
  "visit": "{visit_id}",
  "secret": "{validation_secret}",
  "modes": {
    "entry": true,
    "activities": false,
    "exit": false
  },
  "url": "{url_registered}",
  "created": "{date_registered}",
  "__v": 0
}

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. webhooks

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}"
  }
]

Massive Lists

You can configure massive lists on the BeepQuest Panel, there you can import from a csv format or update elements manually. On this API you can query or create elements on your massive lists for more integration with other systems.

Get all massive lists configured

Before making changes to your massive lists you may need to query all configured to get _id field. You can query all using:

Headers

Key Value
BQAPPTOK Application Api Token
GET
/v1/subscription/massive-lists

Example request

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

Example response

[
  {
    "_id": "{massive_list_id}",
    "name": "{massive_list_name}"
  },
  {
    "_id": "{massive_list_id}",
    "name": "{massive_list_name}"
  },
  ...
]

Create massive list items

You can add elements to your massive lists using this endpoint.

Headers

Key Value
BQAPPTOK Application Api Token

Request

Field Name Type Description
body [Object] value string Element name. Required
index int Element index on list
emails string Comma separated list of emails for segmentation
POST
/v1/subscription/massive-lists/items

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/massive-lists/items', {
  method: 'POST',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  },
  body: JSON.stringify([{
    "value": "Element name",
    "emails": "user1@company.com,user2@company.com"
  }])
});
Show examples in:
BQ Logo
BeepQuest API Documentation