563848e0ecc0
List practitioners matching filter criteria
Returns a paginated list of practitioners matching the supplied filter criteria; all filters are combined with AND logic, and omitting a filter returns all practitioners accessible to the caller. Use this endpoint to search across practitioners by name, NPI, CAQH ID, external ID, type, roles, or delegation status — for a single known practitioner, prefer GET /practitioners/{id} instead, and for bulk NPI lookup, supply multiple npi values (the response shape changes when NPI bulk-search mode is active, adding identifiersSearched and matchedCount fields). The tenant-id header identifies which tenant's data is queried; include the X-PII-View: true header to receive PII fields, which requires the practitioner read:pii permission — callers without it receive 403. The size parameter's default of 2 is intentional, and unlike the NPI bulk-search and roster-ID list parameters, api-layer does not enforce any maximum on size — it is passed through unclamped.
Query parameters
Search by Caqh Provider Id
Filter by delegation status (Direct, Delegated, or CredNotRequired)
Search by External Id
Filter criteria as JSON (must be URL encoded). Multiple filters are combined with AND logic.
Filterable Fields:
- credentialingStatus (String): Workflow status (eq, neq, in, nin, contains)
- data.lineOfBusiness (Array): Line of business values (in, nin)
- data.userDefinedFields.* (Any): User-defined fields with dot notation (eq, neq, in, nin, contains)
- data.* (Any): Any data field (eq, neq, in, nin, contains, gt, gte, lt, lte)
Operations:
- String: eq, neq, in, nin, contains
- Array: in, nin (use in for arrays, not eq)
- Numeric/Date: eq, neq, gt, gte, lt, lte
Examples:
{"credentialingStatus":{"eq":"PSV_READY"}}
{"credentialingStatus":{"in":["PSV_READY","PSV_COMPLETED"]}}
{"data.lineOfBusiness":{"in":["MEDICARE","MEDICAID"]}}
{"data.userDefinedFields.market":{"in":["MARKET1","MARKET2"]}}
{"credentialingStatus":{"eq":"PSV_READY"},"data.lineOfBusiness":{"in":["MEDICARE"]}}
Notes:
- Filter must be URL encoded when sent as query parameter
- tenantId from header always takes precedence (cannot be overridden)
- Credentialing status derived from latest workflow timeline event
- String operations are case-sensitive
Search by Practitioner First Name
Search by Practitioner Last Name
Filter by licensed states (comma-separated list of state codes)
Search by NPI. May contain one or more values for bulk search (copy-paste): separate with comma, newline, tab, semicolon, or space. When one or more NPI values are provided via this parameter, the response includes optional identifiersSearched, matchedCount, notFoundCount, unmatchedIdentifiers. When the query parameter is omitted (standard list request), those fields are null.
Sort criteria as JSON (must be URL encoded). Format: {"orderBy":"fieldName","orderByDirection":"ASC|DESC"}.
Accepted now; sort activates once the DAL client bump deploys (CP-32265). The endpoint accepts this parameter and threads it through the api-layer so the OpenAPI contract is stable and callers can adopt sort immediately. The value is currently held (not yet forwarded to the DAL) because the pinned DAL client (v1.181.0) does not yet expose an order param on the practitioner OV list endpoint. DAL PR #1351 adds it; sort begins reaching the DAL as soon as this service is bumped to the client version that publishes it — the immediate post-DAL-merge step. Until then a sorted request returns the same rows as an unsorted one.
Sortable field (on activation):
- credentialingDueDate — Credentialing due date from the latest credentialing workflow (index-backed on the DAL, NULLs sort last).
- Example: {"orderBy":"credentialingDueDate","orderByDirection":"ASC"}
Page number for offset-based pagination (0-based index). Defaults to 0 if not specified.
Search by Practitioner Roles (comma-separated list)
Search by Practitioner Type (comma-separated list)
Search by Roster: comma-separated roster IDs (UUIDs), max 20 per request. Returns practitioners linked to any of the given rosters. Omit for a standard (non-roster) search.
Number of items per page in offset-based pagination. Defaults to 2 if not specified.
Filter by states to credential (comma-separated list of state codes)
Headers
Include PII in response; requires practitioner read:pii permission
Response
List of Practitioner