Auto-Assign Provider Workflow Documentation

Overview

The auto-assign feature automatically assigns cases to available physicians based on patient information, state requirements, and physician availability. This document outlines the required fields and conditions in the /dynamic-case API request body for auto-assignment to work correctly.

Prerequisites

Before auto-assignment can occur, the following system-level conditions must be met:

1. Auto-Assign Setting: Make sure to confirm with the CareValidate team to enable the autoAssignCase flag for your organization
2. Auto-Assignable Physicians: At least one of the following must be configured:
   • Product bundle with providers assigned
   • Organization setting with providers onboarded for auto assignment
3. State Configuration: The respondent's state must belong to a state eligible for auto assignment

Request Body Fields for /dynamic-case endpoint for Auto Assignment

1. Basic User Information (MANDATORY for API)

These fields are required by the /dynamic-case API endpoint:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "questions": [...]  // Array of question responses
}

2. Age / Date of Birth (MANDATORY for physician matching)

Purpose: Matches physicians with age restrictions. Each physician has a minimum age and maximum age configured for auto-assignment.

Option A: DOB field passed at the root level along with patient information

{
  ...
  "dob": "1990-05-15"  // ISO format date
}

Option B: Date of Birth Question

{
  "type": "DATE",
  "questionId": "<question-id>",
  "question": "What is your date of birth?",  // Should contain "date of birth" or "dob"
  "answer": "1990-05-15"  // ISO format date
}

3. Language Preferences (OPTIONAL but recommended)

Purpose: Matches physicians who speak the patient's preferred languages

Option A: Language Preferences in Case Creation Request

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@example.com",
  ...
  "languagePreferences": ["en", "es", "fr"],
  ...
}

Option B: Organization Default Languages If not provided, the system retrieves languages from organization settings.

Notes:

• Languages are matched against physician's languages array
• If patient has language preferences and physician has language requirements, at least one language must match
• If no languages are specified, all physicians are considered (language-agnostic)

4. Address Information (MANDATORY for State Determination)

Purpose: Determines the respondent's state, which is required for:

• Validating whether the state allows async operations
• Filtering physicians available in that state

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "shippingAddress": {
    "addressLine1": "123 main st",
    "addressLine2": "Apt 1",
    "state": "NJ", // 2-character valid state code
    "city": "Jersey City",
    "postalCode": "10000",
    "country": "US"
  }
  "questions": [...]  // Array of question responses
}

Notes:

• The address must include a valid US state name or abbreviation
• If neither the user's state nor address is available, auto-assignment will fail

5. Visit Type Widget (MANDATORY)

Purpose: Determines case eligibility for auto-assignment. Only async visit types are eligible.

Required Question:

{
  "type": "WIDGET_VISIT_TYPE",
  "questionId": "<unique-question-id>",  // Required if using existing form
  "answer": "ASYNC_TEXT_EMAIL"    // Must be exactly "ASYNC_TEXT_EMAIL"
}

Notes:

• The response value must be "ASYNC_TEXT_EMAIL" (case-sensitive)
• If the visit type is sync (e.g., SYNC_VIDEO, SYNC_PHONE, SYNC_IN_PERSON), auto-assignment will be skipped
• If this question is missing or has a different value, auto-assignment will not occur

Notes:

• Age is calculated from DOB
• If patient age doesn't fall within a physician's age range, that physician will be excluded
• Patients must be 18 years or older (minimum age requirement)

6. BMI Information

Purpose: Matches physicians with BMI thresholds (patientBmiThreshold)

Option A: BMI Widget (Recommended)

{
  "type": "WIDGET_BMI",
  "questionId": "<question-id>",
  "answer": "{
     "height": "5'10\"",
     "weight": "180",
     "bmi": "25.8"
   }"  // JSON string with bmi value or height and weight value
}

Option B: Weight and Height Questions

[
  {
    "type": "TEXT",
    "questionId": "<question-id>",
    "question": "What is your weight?",  // Should contain "weight" or "weigh"
    "answer": "180 lbs" 
  },
  {
    "type": "TEXT",
    "questionId": "<question-id>",
    "question": "What is your height?",  // Should contain "height"
    "answer": "5'10\"" 
  }
]

Notes:

• BMI widget takes precedence if both are provided
• BMI is calculated from weight and height if individual values are provided
• Weight question text should contain "weight" or "weigh" (but not "weight goal" or "weight initiative")
• If patient BMI is below a physician's threshold, that physician will be excluded
• If BMI is missing, only physicians without BMI restrictions will be considered

Auto-Assignment Flow

1. Prerequisites Check:
   • Verifies the Auto Assign setting is enabled for your organization (Contact the CareValidate team to enable this).
   • Retrieves auto-assignable physicians (from product bundle or organization setting)
2. Case Creation: Create the case via the /dynamic-case endpoint
3. Visit Type Validation: Checks if visit type is ASYNC_TEXT_EMAIL
4. State Extraction:
   • First tries to use respondent's state field
   • Falls back to extracting state from address question
   • Validates state code format
5. State Async Check: Verifies state is configured as async allowed state
6. Physician Filtering:
   • Filters physicians by state availability (availableInStates)
   • Checks physician capacity limits
7. Patient Preference Matching:
   • Extracts age from DOB or age question
   • Extracts BMI from BMI widget or calculates from weight/height
   • Retrieves language preferences
8. Best Match Selection:
   • Filters physicians by age range compatibility
   • Filters physicians by BMI threshold compatibility
   • Filters physicians by language compatibility
   • Selects physician with best capacity/load balance
9. Assignment: Assigns case to selected physician with VisitType.AsyncTextEmail

Example Request Body

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com",
  "dob": "1985-03-20",
  "gender": "FEMALE",
  "formId": "existing-form-id",  // or use formTitle
  "productBundleId": "bundle-id",  // Optional but recommended
  "languagePreferences": ["en"],
  "shippingAddress": {
    "addressLine1": "123 main st",
    "addressLine2": "Apt 1",
    "state": "NJ", // 2-character valid state code
    "city": "Jersey City",
    "postalCode": "10000",
    "country": "US"
  }
  "questions": [
    {
      "questionId": "visit-type-question-id",
      "type": "WIDGET_VISIT_TYPE",
      "answer": "ASYNC_TEXT_EMAIL"
    },
    {
      "questionId": "bmi-question-id",
      "type": "WIDGET_BMI",
      "answer": "{\"bmi\": 28.3}"
    },
    {
      "questionId": "weight-question-id",
      "type": "TEXT",
      "question": "What is your current weight?",
      "answer": "165 lbs"
    },
    {
      "questionId": "height-question-id",
      "type": "TEXT",
      "question": "What is your height?",
      "answer": "5'8\""
    }
  ]
}

Common Failure Scenarios

1. Auto-assign not enabled: The autoAssignCase flag is not enabled for your organization. Contact the CareValidate team to enable this feature.
2. No auto-assignable physicians: No physicians configured in product bundle or organization setting
3. Wrong visit type: Visit type is not ASYNC_TEXT_EMAIL
4. State not async: Respondent's state does not belong to allowed async states
5. No state available: Cannot determine state from user profile or address question
6. No physicians in state: No auto-assignable physicians available in respondent's state
7. No matching physician: All physicians fail age, BMI, or language compatibility checks
8. Physician capacity exceeded: All available physicians have reached their daily case limits