---
updatedAt: 2026-10-01T07:06:01.000Z
agentTools:
  projectIndex: https://docs.nexhealth.com/v2.2.2/llms.txt
---

# View insurance plans

This endpoint returns insurance plans for the institution, optionally filtered by `payer_id` or `group_num`.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "NexHealth API v2.2.2 (Deprecated)",
    "description": "> **⚠️ Deprecated.** v2.2.2 is the legacy version of the NexHealth API and is deprecated; new development should target v3.0.0 (also known by its original date-based name v20240412). Our migration guide walks through every breaking change: https://docs.nexhealth.com/v20240412/docs/api-v2-to-v20240412-migration-guide\n\nWelcome to the developer hub and documentation for NexHealth API. This section of guide describes the operations, response parameters, request parameters, and parameter constraints related to User API. The term Operations refer to functions or methods. The operations are included in requests and send to the web server. Each operation performs a different action or a query on database.",
    "termsOfService": "https://www.nexhealth.com/terms-of-service",
    "contact": {
      "name": "NexHealth",
      "email": "info@nexhealth.com"
    },
    "license": {
      "name": "NexHealth License 1.0",
      "url": "https://www.nexhealth.com/privacy"
    },
    "version": "v2"
  },
  "security": [
    {
      "Authorization": []
    }
  ],
  "tags": [
    {
      "name": "Insurance Plans",
      "description": "An insurance plans resource"
    }
  ],
  "paths": {
    "/insurance_plans": {
      "get": {
        "summary": "View insurance plans",
        "description": "This endpoint returns insurance plans for the institution, optionally filtered by `payer_id` or `group_num`.",
        "parameters": [
          {
            "in": "header",
            "name": "Nex-Api-Version",
            "description": "The NexHealth API version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v2"
            }
          },
          {
            "in": "query",
            "name": "subdomain",
            "description": "Used to scope the request to the specified institution",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "page",
            "description": "Page number. Starts with page 1",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "per_page",
            "description": "Number of results to return per page. Defaults is 5 per page and Max 300 per page",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 5
            }
          },
          {
            "in": "query",
            "name": "payer_id",
            "description": "A unique ID number that is assigned to an insurance company for the purpose of transmitting provider claims electronically",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "group_num",
            "description": "Group number",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include[]",
            "description": "Resources to be included in the response",
            "required": false,
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "patient_coverages",
                  "subscribers"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_V2_Entities_Insurance_EhrPlanWithIncludes_Collection_Response"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_Forbidden"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_InternalServerError"
                }
              }
            }
          }
        },
        "tags": [
          "Insurance Plans"
        ],
        "operationId": "getInsurancePlans"
      }
    }
  },
  "servers": [
    {
      "url": "https://nexhealth.info"
    }
  ],
  "components": {
    "securitySchemes": {
      "Authorization": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
      }
    },
    "schemas": {
      "API_Errors_BadRequest": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_BadRequest model"
      },
      "API_Errors_Unauthorized": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_Unauthorized model"
      },
      "API_Errors_Forbidden": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_Forbidden model"
      },
      "API_Errors_InternalServerError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_InternalServerError model"
      },
      "API_V2_Entities_Insurance_EhrPlanWithIncludes_Collection_Response": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "example": false,
            "description": "Indicates the success or failure of the request"
          },
          "description": {
            "type": "string",
            "example": "Description",
            "description": "Additional context on the request to help with debugging."
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Error message"
            ],
            "description": "Any errors that occur during the execution of the request."
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/API_V2_Entities_Insurance_EhrPlanWithIncludes"
            }
          },
          "count": {
            "type": "integer",
            "format": "int32",
            "example": 2,
            "description": "Number of total objects, in case of collection."
          }
        },
        "description": "API_V2_Entities_Insurance_EhrPlanWithIncludes_Collection_Response model"
      },
      "API_V2_Entities_Insurance_EhrPlanWithIncludes": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "example": 18,
            "description": "Plan id"
          },
          "payer_id": {
            "type": "string",
            "example": "87726",
            "description": "A unique ID number that is assigned to an insurance company for the purpose of transmitting provider claims electronically",
            "nullable": true
          },
          "name": {
            "type": "string",
            "example": "United Healthcare",
            "description": "Plan name",
            "nullable": true
          },
          "address": {
            "type": "string",
            "example": "123 Law St",
            "description": "Street address",
            "nullable": true
          },
          "address2": {
            "type": "string",
            "example": "85335, North East",
            "description": "Street address 2",
            "nullable": true
          },
          "city": {
            "type": "string",
            "example": "New York",
            "description": "City",
            "nullable": true
          },
          "state": {
            "type": "string",
            "example": "NY",
            "description": "2 letter state code",
            "nullable": true
          },
          "zip_code": {
            "type": "string",
            "example": "54700",
            "description": "Zip code",
            "nullable": true
          },
          "country_code": {
            "type": "string",
            "example": "US",
            "description": "2 letter country code",
            "nullable": true
          },
          "group_num": {
            "type": "string",
            "example": "12345",
            "description": "Group number",
            "nullable": true
          },
          "employer_name": {
            "type": "string",
            "example": "Walmart",
            "description": "Employer name",
            "nullable": true
          },
          "foreign_id": {
            "type": "string",
            "example": "1",
            "description": "Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Insurance Plan update date in UTC"
          },
          "patient_coverages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/API_V2_Entities_Insurance_PatientCoverage"
            },
            "description": "List of patient coverages"
          },
          "subscribers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/API_V2_Entities_Insurance_Subscriber"
            },
            "description": "List of individuals who hold subscriptions to this plan."
          }
        }
      },
      "API_V2_Entities_Insurance_PatientCoverage": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "example": 18,
            "description": "Coverage id"
          },
          "subscription_relation": {
            "type": "string",
            "enum": [
              "self",
              "spouse",
              "child",
              "employee",
              "handicap_dep",
              "signif_other",
              "injured_plaintiff",
              "life_partner",
              "dependent",
              "other"
            ],
            "example": "self",
            "description": "The relationship of this patient to the subscriber"
          },
          "patient_id": {
            "type": "integer",
            "format": "int32",
            "example": 25,
            "description": "The ID of the covered patient",
            "nullable": true
          },
          "priority": {
            "type": "integer",
            "format": "int32",
            "example": 2,
            "description": "The relative priority of this insurance coverage where the lowest value is the patient's primary insurance\nand higher values represent secondary and tertiary policies",
            "nullable": true
          },
          "plan_id": {
            "type": "integer",
            "format": "int64",
            "example": 18,
            "description": "The ID of the insurance plan this coverage subscribes to",
            "nullable": true
          },
          "subscriber_num": {
            "type": "string",
            "example": "123456789",
            "description": "The subscriber's identification number for the plan",
            "nullable": true
          },
          "effective_date": {
            "type": "string",
            "format": "date",
            "example": "2022-01-01",
            "description": "The date the coverage takes effect",
            "nullable": true
          },
          "expiration_date": {
            "type": "string",
            "format": "date",
            "example": "2022-12-31",
            "description": "The date the coverage expires",
            "nullable": true
          }
        }
      },
      "API_V2_Entities_Insurance_Subscriber": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32",
            "example": 415,
            "description": "The subscriber's id"
          },
          "name": {
            "type": "string",
            "example": "John Smith",
            "description": "The subscriber's full name"
          },
          "date_of_birth": {
            "type": "string",
            "example": "1990-06-05",
            "description": "The subscriber's date of birth in YYYY-MM-DD format",
            "nullable": true
          }
        }
      }
    }
  }
}
```