Find Nearby Care V2 API

The find-nearby-care-v2 endpoint allows you to find healthcare providers and facilities near a specific location based on care categories. This endpoint should be called after get-care-categories-v2 to get the care category information needed for the search.

Endpoint

POST /find-nearby-care-v2

Authentication

This endpoint requires authentication using the access token obtained from generate-client-auth-token.

Include the token in the Authorization header:

Authorization: Bearer {access_token}

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer access_token from `generate-client-auth-token`
`Content-Type`	Yes	Must be `application/json`
`domain`	Yes	Domain/group name for the request

Request Body

{
  zipcode: string;                    // Required: Zipcode for location search
  care_category_type: string;         // Required: Type of care category ("specialty", "procedure", or "condition")
  care_category_name: string;         // Required: Name of the care category
  care_category_id?: string;          // Optional: ID of the care category (from get-care-categories-v2)
  payer_name?: string;                // Optional: Payer name
  plan_name?: string;                 // Optional: Insurance plan name
  source?: string;                    // Optional: Source of request ("chat" or "ui")
  accepts_new_patients?: boolean;     // Optional: Filter for providers accepting new patients
}

Request Parameters

`zipcode` (required)

Type: string
Description: Zipcode for the location to search for providers
Example: "10001" or "90210"

`care_category_type` (required)

Type: string
Description: Type of care category from get-care-categories-v2 response
Allowed Values: "specialty", "procedure", "condition"
Example: "specialty"

`care_category_name` (required)

Type: string
Description: Name of the care category from get-care-categories-v2 response
Example: "Cardiology" or "Magnetic Resonance Imaging (MRI)"

`care_category_id` (optional)

Type: string
Description: ID of the care category from get-care-categories-v2 response. Recommended to include for better matching
Example: "CARDIOLOGY" or "72141"

`payer_name` (optional)

Type: string
Description: Payer name for filtering providers
Example: "Blue Cross" or "Aetna"

`plan_name` (optional)

Type: string
Description: Insurance plan name for filtering providers. Should be used together with payer_name
Example: "Premium Plan"

`source` (optional)

Type: string
Description: Source of the request. Affects result limits: "chat" returns 5 results, "ui" returns up to 500 results
Allowed Values: "chat", "ui"
Default: If not provided, defaults to UI behavior (more results)

`accepts_new_patients` (optional)

Type: boolean
Description: Filter for providers that accept new patients
Example: true

Success Response

Status Code: 200

{
  statusCode: 200;
  data: [
    {
      provider_id?: string | number;      // Unique provider identifier
      name: string;                       // Provider or facility name
      description: string;                // Provider specialty or description
      phone: string;                      // Contact phone number
      email: string;                       // Contact email address
      address: string;                     // Full address
      latitude: number;                    // Latitude coordinate
      longitude: number;                   // Longitude coordinate
      city: string;                        // City name
      state: string;                        // State abbreviation
      zipcode: string;                     // Zipcode
      rating: number;                      // Provider rating (0-5)
      review_count?: string;              // Number of reviews
      website: string;                     // Provider website URL
      insurance_accepted?: string[];      // Array of accepted insurance plans
      image: string;                       // Provider image URL
      languages: string[];                 // Languages spoken
      gender?: string;                     // Provider gender
      has_booking_links?: boolean;         // Whether provider has booking links
      accepts_new_patients?: boolean;      // Whether provider accepts new patients
      booking_links?: {                    // Booking links (if available)
        url: string;
        serviceProvider: string;
      }[];
      reward_amount?: number;              // Reward amount (if applicable)
      bundle_median_price?: number;        // Bundle median price (if applicable)
    },
    // ... more providers
  ];
  message: "OKAY";
}

Response Fields

Each provider in the array contains:

`provider_id`

Type: string | number (optional)
Description: Unique identifier for the provider. Can be used to get detailed provider information
Example: "1234567890" or 1234567890

`name`

Type: string
Description: Full name of the provider or facility
Example: "Dr. John Smith" or "City Medical Center"

`description`

Type: string
Description: Provider specialty or facility description
Example: "Cardiology" or "General Practice"

`phone`

Type: string
Description: Contact phone number
Example: "(555) 123-4567"

`email`

Type: string
Description: Contact email address (may be empty)
Example: "contact@example.com"

`address`

Type: string
Description: Full street address
Example: "123 Main St, New York, NY 10001"

`latitude` / `longitude`

Type: number
Description: Geographic coordinates for mapping
Example: 40.7128 / -74.0060

`city` / `state` / `zipcode`

Type: string
Description: Location information
Example: "New York" / "NY" / "10001"

`rating`

Type: number
Description: Provider rating (typically 0-5 scale)
Example: 4.5

`review_count`

Type: string (optional)
Description: Number of reviews
Example: "150"

`website`

Type: string
Description: Provider website URL
Example: "https://www.example.com"

`insurance_accepted`

Type: string[] (optional)
Description: Array of accepted insurance plans
Example: ["Multiplan", "Blue Cross Blue Shield"]

`languages`

Type: string[]
Description: Languages spoken by the provider
Example: ["English", "Spanish"]

`accepts_new_patients`

Type: boolean (optional)
Description: Whether the provider is currently accepting new patients
Example: true

Error Responses

Missing Required Fields (435)

{
  statusCode: 435;
  data: {
  }
  message: "Zipcode is Required";
}

{
  statusCode: 435;
  data: {
  }
  message: "Care Category Type and Name are Required";
}

Causes:

Missing zipcode parameter
Missing care_category_type parameter
Missing care_category_name parameter

Unauthorized (403)

{
  statusCode: 403;
  data: {
  }
  message: "UNAUTHORIZED";
}

Causes:

Missing or invalid Authorization header
Expired or invalid access token

Server Fault (500)

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

Example Requests

Example 1: Find Cardiology Providers

This example shows finding cardiology providers near a zipcode:

# Step 1: Generate access token
curl -X POST https://api.example.com/generate-client-auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "fingerprint": "device-fingerprint-123",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "group_name": "my-domain"
    }
  }'

# Response:
# {
#   "statusCode": 200,
#   "data": {
#     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
#   },
#   "message": "OKAY"
# }

# Step 2: Search for 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"
#     }
#   ],
#   "message": "OKAY"
# }

# Step 3: Find nearby providers using the care category
curl -X POST https://api.example.com/find-nearby-care-v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "domain: my-domain" \
  -d '{
    "zipcode": "10001",
    "care_category_id": "CARDIOLOGY",
    "care_category_name": "Cardiology",
    "care_category_type": "specialty"
  }'

Response:

{
  "statusCode": 200,
  "data": [
    {
      "provider_id": "1234567890",
      "name": "Dr. Jane Smith",
      "description": "Cardiology",
      "phone": "(555) 123-4567",
      "email": "jane.smith@example.com",
      "address": "123 Medical Center Dr, New York, NY 10001",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "rating": 4.5,
      "review_count": "150",
      "website": "https://www.example.com",
      "insurance_accepted": ["Multiplan"],
      "image": "https://example.com/image.jpg",
      "languages": ["English", "Spanish"],
      "accepts_new_patients": true
    },
    {
      "provider_id": "0987654321",
      "name": "Dr. John Doe",
      "description": "Cardiology, Internal Medicine",
      "phone": "(555) 987-6543",
      "email": "john.doe@example.com",
      "address": "456 Health Ave, New York, NY 10001",
      "latitude": 40.7580,
      "longitude": -73.9855,
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "rating": 4.8,
      "review_count": "200",
      "website": "https://www.example2.com",
      "insurance_accepted": ["Multiplan"],
      "image": "https://example.com/image2.jpg",
      "languages": ["English"],
      "accepts_new_patients": true
    }
  ],
  "message": "OKAY"
}

Example 2: Find Providers with Insurance Filtering

This example shows finding providers with specific insurance plan filtering:

curl -X POST https://api.example.com/find-nearby-care-v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "domain: my-domain" \
  -d '{
    "zipcode": "90210",
    "care_category_id": "DERMATOLOGY",
    "care_category_name": "Dermatology",
    "care_category_type": "specialty",
    "payer_name": "Blue Cross",
    "plan_name": "Premium Plan",
    "accepts_new_patients": true
  }'

Example 3: Find Facilities for a Procedure

This example shows finding facilities that perform a specific procedure:

curl -X POST https://api.example.com/find-nearby-care-v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "domain: my-domain" \
  -d '{
    "zipcode": "10001",
    "care_category_id": "72141",
    "care_category_name": "Magnetic Resonance Imaging (MRI) of Brain",
    "care_category_type": "procedure"
  }'

Behavior Notes

Care Category Types

Specialty: Returns individual healthcare providers matching the specialty
Procedure: Returns facilities that perform the procedure
Condition: Returns providers who treat the condition

Result Limits

Chat source: Returns 5 results
UI source: Returns up to 500 results
No source specified: Defaults to UI behavior (more results)

Sorting

Results are automatically sorted by rating and review count (50% weight each)

Empty Results

If no providers are found, an empty array [] is returned
This is not an error condition - try adjusting search parameters (zipcode, care category, filters)

Finding Care Overview - Learn about Finding Care API concepts
Get Care Categories V2 API - Search for care categories first
Client Credentials API - Authentication endpoint
API Guidelines - General API response formats and error codes

Endpoint​

Authentication​

Request Headers​

Request Body​

Request Parameters​

zipcode (required)​

care_category_type (required)​

care_category_name (required)​

care_category_id (optional)​

payer_name (optional)​

plan_name (optional)​

source (optional)​

accepts_new_patients (optional)​

Success Response​

Response Fields​

provider_id​

name​

description​

phone​

email​

address​

latitude / longitude​

city / state / zipcode​

rating​

review_count​

website​

insurance_accepted​

languages​

accepts_new_patients​

Error Responses​

Missing Required Fields (435)​

Unauthorized (403)​

Server Fault (500)​

Example Requests​

Example 1: Find Cardiology Providers​

Example 2: Find Providers with Insurance Filtering​

Example 3: Find Facilities for a Procedure​

Behavior Notes​

Care Category Types​

Result Limits​

Sorting​

Empty Results​

Related Documentation​