Introduction
BeepQuest Api Documentation
Initial Considerations
Initial Considerations
Querying Historical Data
Configuring Webhooks
Question Engine Module WebhooksVisit Webhooks
Subscription Information and Config
Subscription Data
Massive Lists
Massive Lists
Geofences
Geofences
Incidents
Incidents
External Api on Question Modules
Interaction with an ongoing question engine module answerGeneral steps for using an external api on a question engine moduleTechnical considerations

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}",
      "pdfUrl": "{pdfUrl}",
      "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}",
      "pdfUrl": "{pdfUrl}",
      "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}"
  },
  ...
]

Get massive list items

You can also list all items related to a massive list. You can filter by value.

Headers

Key Value
BQAPPTOK Application Api Token

Query String Parameters

Field Type Required Description
valueContains string No Filter for value on item
all bool No Allows to get all elements at once, skip and limit are ignored when true
limit int No Query results limit (Max 100)
skip int No
(Default 0)		 Offset results
GET
/v1/subscription/massive-lists/:massiveList/elements

Example request

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

Example response

[
  {
    "_id": "{element_id}",
    "value": "{element_name}"
  },
  {
    "_id": "{element_id}",
    "value": "{element_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({
    items: [
      {
        "value": "Element name",
        "emails": "user1@company.com,user2@company.com"
      }
    ]
  })
});

Update massive list item

After adding elements it's possible to change its main fields like value and emails for segmentation.

Headers

Key Value
BQAPPTOK Application Api Token

Request

Field Name Type Required Description
body [Object] value string Yes Element name. Required
index int No Element index on list
emails string No Comma separated list of emails for segmentation
PUT
/v1/subscription/massive-lists/:massiveListItem/item

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/massive-lists/:massiveListItem/item', {
  method: 'PUT',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  },
  body: JSON.stringify({
    "value": "Element name",
    "emails": "user1@company.com,user2@company.com"
  })
});

Delete massive list item

If needed, massive list items can be removed, remember that ultimately only the alphanumeric value is referenced for an answer in a question engine form.

Headers

Key Value
BQAPPTOK Application Api Token
DELETE
/v1/subscription/massive-lists/:massiveListItem/item

Example request

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

Delete all massive list items

If needed, ALL massive list items can be removed, remember that ultimately only the alphanumeric value is referenced for an answer in a question engine form.

Headers

Key Value
BQAPPTOK Application Api Token
DELETE
/v1/subscription/massive-lists/:massiveList/elements

Example request

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

Example response

[
  {
    "_id": "{element_id}",
    "value": "{element_name}"
  },
  {
    "_id": "{element_id}",
    "value": "{element_name}"
  }
]

Geofences

Geofences represent a zone in a map that can be related to answers on a question engine form. You can control your geofence resources with this API. First we have a hierarchy of a geofence group that then has many geofences or zones. You can only create geofence groups on the BeepQuest Panel, but you can administer and query individual geofences from this API.

Get all geofence groups

Before making changes to your geofences you may need to query all configured geofence groups to get _id field. You can query all using:

Headers

Key Value
BQAPPTOK Application Api Token
GET
/v1/subscription/geofence-groups

Example request

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

Example response

[
  {
    "_id": "{geofence_group_id}",
    "name": "{geofence_group_name}"
  },
  {
    "_id": "{geofence_group_id}",
    "name": "{geofence_group_name}"
  },
  ...
]

Get geofences from group

You can also list all geofences related to a group. You can also filter by name.

Headers

Key Value
BQAPPTOK Application Api Token

Query String Parameters

Field Type Required Description
nameContains string No Filter for value on item
all bool No Allows to get all elements at once, skip and limit are ignored when true
limit int No Query results limit (Max 100, Defaults to 10)
skip int No
(Default 0)		 Offset results
GET
/v1/subscription/geofence-groups/:geofenceGroup/geofences

Example request

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

Example response

[
  {
    "_id": "{geofence_id}",
    "value": "{geofence_name}"
  },
  {
    "_id": "{geofence_id}",
    "value": "{geofence_name}"
  }
]

Create geofences on a group

You can add geofences to your groups using this endpoint.

Headers

Key Value
BQAPPTOK Application Api Token

Request

Field Name Type Required Description
items [Object] name string Yes Element name. Required
radius int Yes Radius for geofence in meters
lat float Yes Latitude
lng float Yes Longitude
POST
/v1/subscription/geofence-groups/:geofenceGroup/geofences

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/geofence-groups/:geofenceGroup/geofences', {
  method: 'POST',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  },
  body: JSON.stringify({
    items: [
      {
        "name": "Element name", 
        "radius": 100, 
        "lng": -99.13715721166993, 
        "lat": 19.434280778073443
      }
    ]
  })
});

Update geofence

You can update a geofence with the corresponding fields it has. Make sure you send all the required fields. It is advised that name is reviewed before usage as geofence responses are linked to current name on geofence.

Headers

Key Value
BQAPPTOK Application Api Token

Request

Field Name Type Required Description
body Object name string Yes Element name. Required
radius int Yes Radius for geofence in meters
lat float Yes Latitude
lng float Yes Longitude
PUT
/v1/subscription/geofences/:geofence

Example request

const response = await fetch(
  'https://api.beepquest.com/v1/subscription/geofences/:geofence', {
  method: 'PUT',
  headers: {
    'BQAPPTOK': '{BQAPPTOK}'
  },
  body: JSON.stringify({
    "name": "Element name",
    "radius": 100,
    "lng": -99.13715721166993,
    "lat": 19.434280778073443
  })
});

Delete geofence

If needed, geofences can be removed.

Headers

Key Value
BQAPPTOK Application Api Token
DELETE
/v1/subscription/geofences/:geofence

Example request

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

Incidents

Get all incidents rpeorts

Before making changes to your incidents you may need to create incidents token. You can query all using:

Headers

Key Value
BQAPPTOK Application Api Token
BQINCIDENTTOK Incident Api Token

Query String Parameters

Field Type Required Description
inciatlDate datetime ISO Dates Yes initial data range
finalDate datetime ISO Dates No end date range
limit int No Query results limit (Max 100, Defaults to 10)
skip int No
(Default 0)		 Offset results
GET
/v1/subscription/incidets

Example request

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

Example response

[
  {
		"_id": "{Id}",
		"status": "{status}",
		"created": "{reportedDate}",
		"triggerAnswers": [
			{
				"user": {
					"firstName": "{firstName}",
					"lastName": "{lastName}",
					"email": "{Email}",
				},
				"answers": {
					"keyField1": "{Answer}",
                    "keyField2": "{Answer}",
					...
				}
			}
		],
		"resolvedAnswers": [
			{
				"user": {
					"firstName": "{firstName}",
					"lastName": "{lastName}",
					"email": "{Email}",
				},
				"answers": {
					"keyField1": "{Answer}",
                    "keyField2": "{Answer}",
					...
				}
			}
		]
	}
  ...
]

Interaction with an ongoing question engine module answer

On this document we have reviewed mechanisms for querying, updating and connecting to certain events or data saved on BeepQuest. A Question Engine module being the main model for operation, has now the flexibility to include any external logic and complete data live on process. Here we describe information related for planning, configuring and testing an external communication with a question engine module.

General steps for using an external api on a question engine module

  1. Define parameters and result fields for the required functionality.
  2. Implement external logic and deploy
  3. Configure question engine module and external api
  4. Test configured question engine on mobile application.

Configuration on Panel

Go to the question engine module edit form for the module you want to integrate this functionality on. you should see a new panel called Api en Modulo.

ApiInModule

Click on New API button and then on edit button for the created configuration. You should see ui for all the configuration. The main config is the verb and the endpoint.

ApiInModule

On the first tab you can configure static headers you need. Then you can configure on the body tab, all the parameters you want to send from the current question engine answer been filled up.

ApiInModule

Finally on the return tab, you can configure as an action currently implemented the processing of the api response into fields on the current answer.

ApiInModule

Technical considerations

  • Api Requests to external endpoints are processed as Content-Type: application/json. All requests processed by BeepQuest include this header.
  • For processing returned data, response should be handled with http status code 200, otherwise an error will appear on the mobile application.
Show examples in:
JScURLPython
BQ Logo
BeepQuest API Documentation