NMASSIST API

The NIDA-Modified ASSIST (NM ASSIST) tool guides clinicians through a series of questions to identify risky substance use in their adult patients. The accompanying resources assist clinicians in providing patient feedback and arranging for specialty care, where necessary, using the 5 As of intervention.

How do you query the API?

The NMASSIST API does not have any parameters and will return all questions or summaries. As such, simply using the API endpoints is enough. To access the APIs you must have an API key. The API key must be passed as a header value assigned to the x-api-key property.

You can register for an API key by completing the API Gateway Registration form.

The endpoint is as follows:
https://api.drugabuse.gov/prod/nmassist/questions

For additional information, terms of use, and FAQs, please see our NIDA Screening Tool APIs: Overview for Developers page.

What does the question response data look like?

Below is an example of the response from the endpoint.

          
{
  "questions": [
    {
      "question_id": 1,
      "description": "In the past year, how often have you used the following?",
      "comment": null,
      "sub_questions": [
        {
          "name": "Alcohol",
          "question_id": 1,
          "sub_question_id": 1,
          "description":"For men, 5 or more drinks a day. For women, 4 or more drinks a day"
        },
        {
          "name": "Tobacco Products",
          "question_id": 1,
          "sub_question_id": 2
        },
        {
          "name": "Prescription Drugs for Non-Medical Reasons",
          "question_id": 1,
          "sub_question_id": 3
        },
        {
          "name": "Illegal Drugs",
          "question_id": 1,
          "sub_question_id": 4
        }
      ],
      "options": [
        {
          "name": "Never",
          "option_id": 1,
          "option_value": 0,
          "question_id": 1
        },
        {
          "name": "Once or Twice",
          "option_id": 2,
          "option_value": 1,
          "question_id": 1
        },
        {
          "name": "Monthly",
          "option_id": 3,
          "option_value": 1,
          "question_id": 1
        },
        {
          "name": "Weekly",
          "option_id": 4,
          "option_value": 1,
          "question_id": 1
        },
        {
          "name": "Daily or Almost Daily",
          "option_id": 5,
          "option_value": 1,
          "question_id": 1
        }
      ],
      "rules": [
        {
          "order": 1,
          "left_operand": "sq_1",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "message": "Patient is an at-risk drinker.One or more days of heavy drinking (e.g. drinking more than the amounts shown in the previous screen for men or women) places a patient at risk.",
            "more_info_link": "http://pubs.niaaa.nih.gov/publications/Practitioner/CliniciansGuide2005/clinicians_guide.htm",
            "more_info_text": "Please see 'Helping Patients Who Drink Too Much: A Clinician's Guide' for information to help assess, advise, and assist at-risk drinkers or patients with alcohol use disorders."
          }
        },
        {
          "order": 2,
          "left_operand": "sq_2",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "message": "Any current tobacco use places a patient at risk. Advise all tobacco users to quit.",
            "more_info_link": "http://www.ahrq.govclinic/tobacco/clinhlpsmksqt.htm",
            "more_info_text": "For more information on smoking cessation, please see 'Helping Smokers Quit: A Guide for Clinicians.'"
          }
        },
        {
          "order": 3,
          "left_operand": "sq_3",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "next_question_id": "2"
          }
        },
        {
          "order": 4,
          "left_operand": "sq_4",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "next_question_id": "2"
          }
        },
        {
          "order": 5,
          "left_operand": "q_sum_all",
          "operator": "==",
          "right_operand": "0",
          "success": {
            "message": "Reinforce absistence. Screening is complete."
          }
        }
      ]
    }
          
        

Properties

questions
An array which include all the questions, sub questions, options and its next rules.
question_id
To identify each question
sub_questions
An array which include all the sub questions of the question. Each sub question has a sub_question_id, name and question_id.
options
An array which includes option_id, its name, value and question_id as its fields
rules
An array which include limited number of rules. Each rule has an order, left_operand, operator, right_operand and a success.
result_rules

How do you use the question and summary data together?

First please consider going through the tool that exist at https://www.drugabuse.gov/nmassist

Going through this tool will give a general idea of how the two api parts should work together. In short:

  1. A patient or clinician (user) is expected to either go through or administer these screenings
  2. The application makes a call to the API go get all the data
  3. The application will guide the user through the questions based on dependencies while storing the answers and the score based on the answers
  4. The application will provide a summary based on the score for each drug.

In general, your application will need to make a call to get the all the questions and handle the logic to proceed through the questions. The logic for the questions is handled via the dependency field on each question.

How to evaluate rules

Each question may have set of rules. In addition to the question rule the response includes a set of rules to find the result of each sub question.

Question rules

Each rule have a left_operand, operator, right_operand, order and a success.

  • left_operand will be either one of the following:
    • q_sum_all : Sum of selected option values of all the sub questions in the current question.
    • sq_1 : Option value of the first sub question in the current question.
    • sq_2 : Option value of the second sub question in the current question.
    • sq_3 : Option value of the third sub question in the current question.
    • sq_4 : Option value of the fourth sub question in the current question.
    • q_2_sq_1: Option value of first sub question of question id 2.
    • q_2_sq_2: Option value of second sub question of question id 2 and so on.
  • operator will be either one of the following:
    • >
    • <
    • ==
  • right_operand will be any integer.
  • Each rule will be evaluated one by one as per the order.
  • success will have any one or two of the following:
    • message
    • more_info_text and more_info_link
    • next_question_id

Substitute the value of left_operand and evaluate the rule . If it returns false evaluate next rule and if it returns true, following should be considered:

  • If the success has a message part then the message should be prompted to the user.
  • if the success has a more_info_text and more_info_link then the link with the text should be prompted to the user.
  • If the success has a next_question_id then go to the next question of the corresponding question_id

Result rules

Each rule in result rules have a left_operand, operator, right_operand and a success. The result should be calculated for each sub question which marked 'Yes' in the second question.

  • left_operand should be either the sum of the scores of each sub question from question 3 to 8 of questionnaire type1 or the sum of scores of each of the questions from question 3 to 11 of questionnaire type 2.
  • operator will be either one of the following:
    • >
    • <
    • ==
  • right_operand will be any integer.
  • Each rule will be evaluated one by one as per the order.
  • success will have a message.

When evaluating, if any of them returns true the message is prompted to the user for the corresponding sub question and should ignore the following rules for the corresponding sub question.