Get Health Specialties

Returns a paginated list of HCP health specialties organized in a two-tier hierarchy (primary specialties and subspecialties). Supports filtering by tier, parent ID, free-text search, and specialty type. When export=true, the full result set is returned as a downloadable file in JSON or CSV format.

Endpoint

GET

https://lifeapi.pulsepoint.com/RestApi/v2/meta/healthSpecialties

Query Parameters

Name	Data Type	Required	Default	Notes
tier	integer	no		Specialty tier filter. `1` = primary specialties, `2` = subspecialties
parent_id	integer	no		Parent specialty ID to retrieve subspecialties under a specific primary specialty
include_children	boolean	no		When `true`, includes child subspecialties in the response. Only valid when `tier=1`
search	string	no		Free-text search across specialty names
sort	ENUM string	no	name	Sort field. Valid values: `name`, `tier`
order	ENUM string	no	asc	Sort direction. Valid values: `asc`, `desc`
limit	integer	no	50	Maximum number of results per page (max: 500)
cursor	string	no		Opaque pagination cursor. Pass the `next_cursor` value from a previous response to get the next page
export	boolean	no	false	When `true`, returns a downloadable file instead of the standard JSON response
format	ENUM string	no	json	Export format. Valid values: `json`, `csv`. Only applies when `export=true`

Sample Request

GET https://lifeapi.pulsepoint.com/RestApi/v2/meta/healthSpecialties?tier=1&search=Cardiology&limit=50

Response Field List

Name	Data Type	Notes
success	boolean	Returns `true` on a successful request
message	string	Human-readable result message
requestId	string	Unique identifier for the request
data	array of objects	List of health specialty objects
data.id	integer	Specialty ID
data.name	string	Specialty name
data.tier	integer	Hierarchy tier. `1` = primary specialty, `2` = subspecialty
data.parent_id	integer	Parent specialty ID. `null` for tier-1 specialties
data.has_children	boolean	Whether this specialty has child subspecialties
data.is_leaf	boolean	Whether this specialty is a leaf node with no children
data.children_count	integer	Number of child subspecialties
pagination	object	Pagination metadata
pagination.limit	integer	The page size used for this response
pagination.total	integer	Total number of records matching the query
pagination.has_more	boolean	Whether additional pages of results exist
pagination.next_cursor	string	Opaque cursor to pass as the `cursor` query parameter to retrieve the next page
pagination.next_cursor_url	string	Full URL for the next page of results
hierarchy	object	Hierarchy metadata for the result set
hierarchy.current_tier	integer	The tier level of the current result set
hierarchy.available_tiers	array of integers	List of tier levels available for navigation

Sample Response

{
  "success": true,
  "message": "Operation completed successfully",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "id": 101,
      "name": "Cardiology",
      "tier": 1,
      "parent_id": null,
      "has_children": true,
      "is_leaf": false,
      "children_count": 3
    }
  ],
  "pagination": {
    "limit": 50,
    "total": 85,
    "has_more": false,
    "next_cursor": null,
    "next_cursor_url": null
  },
  "hierarchy": {
    "current_tier": 1,
    "available_tiers": [1, 2]
  }
}

Errors

HTTP Status	Error	Description
400	Validation Error	Invalid query parameters. `tier` must be `1` or `2`. `limit` must be a valid integer. `sort` must be `name` or `tier`
401	Unauthorized	Invalid or expired access token
404	Not Found	Parent specialty does not exist (`parent_id` provided was not found)
422	Unprocessable Entity	Invalid parameter combination. `include_children` can only be `true` when `tier=1`
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error