Skip to main content

Get Care Categories V2 API

The get-care-categories-v2 endpoint allows you to search for available care categories (specialties, procedures, or conditions) based on a query string. This is the first step in finding care - you search for categories, then use the results to find nearby providers using find-nearby-care-v2.

Endpoint​

POST /get-care-categories-v2

Request Headers​

HeaderRequiredDescription
Content-TypeYesMust be application/json

Request Body​

{
  query: string;  // Required: Search query for care categories
}

Request Parameters​

query (required)​

  • Type: string
  • Description: Search query to find matching care categories. This can be a specialty name (e.g., "cardiology"), procedure name (e.g., "MRI"), or condition name (e.g., "diabetes")
  • Example: "cardiology" or "physical therapy"

Success Response​

Status Code: 200

{
  statusCode: 200;
  data: [
    {
      care_category_id: string;      // Unique identifier for the care category
      care_category_name: string;     // Human-readable name of the care category
      care_category_type: string;     // Type: "specialty", "procedure", or "condition"
    },
    // ... more care categories
  ];
  message: "OKAY";
}

Response Fields​

Each care category in the array contains:

care_category_id​

  • Type: string
  • Description: Unique identifier for the care category. This ID should be used when calling find-nearby-care-v2
  • Example: "12345" or "CARDIOLOGY"

care_category_name​

  • Type: string
  • Description: Human-readable name of the care category
  • Example: "Cardiology" or "Magnetic Resonance Imaging (MRI)"

care_category_type​

  • Type: string
  • Description: Type of care category
  • Possible Values:
    • "specialty" - Medical specialty
    • "procedure" - Medical procedure
    • "condition" - Medical condition

Error Responses​

Missing Required Fields (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Query is required";
}

Causes:

  • Missing query parameter in request body

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "An unexpected error occurred. Please try again.";
}

Example Requests​

Example 1: Search for Cardiology Specialties​

This example shows searching for cardiology-related care categories:

curl -X POST https://api.example.com/get-care-categories-v2 \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cardiology"
  }'

Response:

{
  "statusCode": 200,
  "data": [
    {
      "care_category_id": "CARDIOLOGY",
      "care_category_name": "Cardiology",
      "care_category_type": "specialty"
    },
    {
      "care_category_id": "PEDIATRIC_CARDIOLOGY",
      "care_category_name": "Pediatric Cardiology",
      "care_category_type": "specialty"
    }
  ],
  "message": "OKAY"
}

Example 2: Search for Procedures​

This example shows searching for MRI-related procedures:

curl -X POST https://api.example.com/get-care-categories-v2 \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MRI"
  }'

Response:

{
  "statusCode": 200,
  "data": [
    {
      "care_category_id": "72141",
      "care_category_name": "Magnetic Resonance Imaging (MRI) of Brain",
      "care_category_type": "procedure"
    },
    {
      "care_category_id": "72146",
      "care_category_name": "Magnetic Resonance Imaging (MRI) of Lower Extremity",
      "care_category_type": "procedure"
    }
  ],
  "message": "OKAY"
}

Example 3: Complete Workflow - Search and Find Providers​

This example shows the complete workflow of searching for categories and then finding providers:

# Step 1: Search for care categories
curl -X POST https://api.example.com/get-care-categories-v2 \
  -H "Content-Type: application/json" \
  -d '{
    "query": "dermatology"
  }'

# Response:
# {
#   "statusCode": 200,
#   "data": [
#     {
#       "care_category_id": "DERMATOLOGY",
#       "care_category_name": "Dermatology",
#       "care_category_type": "specialty"
#     }
#   ],
#   "message": "OKAY"
# }

# Step 2: Use the care category to find nearby providers
curl -X POST https://api.example.com/find-nearby-care-v2 \
  -H "Content-Type: application/json" \
  -H "domain: your-domain" \
  -d '{
    "zipcode": "10001",
    "care_category_id": "DERMATOLOGY",
    "care_category_name": "Dermatology",
    "care_category_type": "specialty"
  }'

Behavior Notes​

Search Matching​

  • The search uses fuzzy matching to find care categories that match the query
  • Results are sorted by relevance
  • Multiple care categories may be returned for a single query

Care Category Types​

  • Specialty: Returns medical specialties (e.g., "Cardiology", "Dermatology")
  • Procedure: Returns medical procedures (e.g., "MRI", "Colonoscopy")
  • Condition: Returns medical conditions (e.g., "Diabetes", "Hypertension")

Using Results​

  • Use the care_category_id, care_category_name, and care_category_type from the response when calling find-nearby-care-v2
  • All three fields (care_category_id, care_category_name, care_category_type) are required for find-nearby-care-v2

Empty Results​

  • If no care categories match the query, an empty array [] is returned
  • This is not an error condition - try a different or more general query