Skip to main content

Group

APIs for managing group entities

📄️List groups matching filter criteria

Returns a paginated list of groups for the requesting tenant that match all supplied filter criteria (filters are combined with AND semantics); all filters are optional, and omitting them returns every group for the tenant. Use this endpoint to enumerate or search across groups; for a known certifyGroupId use GET /groups/{id}, and for autocomplete-style name/NPI/TIN prefix search use GET /groups/search. Pagination is offset-based via page and size; the default page size is 2 and no maximum page size is enforced.

📄️Create a new group for the tenant

Creates a new group record scoped to the requesting tenant. The request body must supply at least one of npi or externalGroupId; email is validated and returns 400 if malformed, but no other fields are currently enforced by request validation (schema validation is disabled for this endpoint). Not idempotent — repeated calls with identical payloads create duplicate group records. Note: the parentHealthcareOrgId query parameter is currently accepted but has no effect on the created group regardless of the value supplied.

📄️Update effective date for all group location network associations

Updates the effective date for ALL network associations linked to the specified group location in a single bulk operation — every network row for the location is overwritten to the same date. Use this endpoint when all associations for a location share the same effective date; to update a single specific network association instead, use PATCH /groups/locations/{locationId}/networks/{networkId}/effective-date. effectiveDate is required and must be in YYYY-MM-DD format.

📄️Associate a group location with networks

Associates an existing group location with one or more networks, creating group-location–network membership records. Use this endpoint after the group location has been added to the group (via POST /groups/{groupId}/locations); call once per set of networks to associate, and use PATCH /groups/locations/{locationId}/networks to update effective dates on existing associations. Not idempotent — if an active association between this location and a requested network already exists, the server returns 409 Conflict rather than silently succeeding; resolve or terminate the existing association first.

📄️Terminate a group location from specific networks

Terminates the association between a group location and one or more networks, ending the location's membership in those networks. Only the location–network associations are affected; this operation does not cascade to practitioner associations, specialty associations, or any other related records for this location. Use this endpoint for targeted network termination of a location while preserving its other relationships; to terminate the location from the group entirely, use PUT /groups/locations/{locationId}/terminate instead.

📄️Update location-network billing NPI and participation date for a group location

As of CP-36570: updates NPI and/or participation date on the practitioner-agnostic TenantGroupLocationNetwork and TenantGroupLocationFacilityNetwork records only, upserting into the `addressType2Npi` array (supports multiple NPIs per location-network). TenantGroupLocationPractitionerNetwork rows are no longer written by this endpoint. Preferred: pass `npiEntries` with the location-network's complete NPI set — it REPLACES the stored array, so an NPI omitted from the list is deleted (the only way to remove one) and an entry without `npiParticipationDate` is stored with no date. Deprecated: the scalar `npi`/`npiParticipationDate` fields still work (repeat the call to add/update additional NPIs; `npi` is required to disambiguate `npiParticipationDate` when more than one NPI exists) but are mutually exclusive with `npiEntries` in the same request.

📄️Terminate a group location

Terminates a group location from a group. The cascade terminates the location's practitioner associations (GroupPractitionerLocation), the location record itself (GroupLocation, TenantGroupLocation), and — by default — all of the location's still-active network associations (TenantGroupLocationNetwork), so networksAffected reflects the number of network associations terminated by this call. Set the group-location.terminate.cascade-network.enabled config flag to false to disable the network cascade (networksAffected will then always be 0, matching the legacy behavior). If the network cascade fails (lookup or termination), this call returns 500 even though the location itself has already been terminated and is not rolled back — retry the request to complete the cascade; already-terminated networks are skipped on retry. To terminate only specific network associations without terminating the location itself, call PUT /groups/locations/{locationId}/networks/terminate instead. The request body must include consentConfirmed set to true to confirm the termination; omitting it or supplying false returns 400.

📄️Update details for multiple group locations

Updates detail fields for one or more locations within a group in a single call, designed for bulk ingestion workflows where location data arrives as a batch from an external roster or source system. Each entry targets a specific location; this is a partial merge per location entry, not a full replace — omitted fields are preserved from the existing record rather than cleared. Use this endpoint when updating multiple locations at once; to add a new location to a group use POST /groups/{groupId}/locations.

📄️Add a new location to a group

Adds a new location to an existing group, creating the necessary location and group-location membership records (and, if address information is provided, linked address records). Designed for batch ingestion workflows where location data arrives from an external roster or source system, but also suitable for individual location additions. The request body only strictly requires locationData as an object — no field inside it is independently enforced by request validation. Not idempotent — repeated calls create additional location records; to update an existing location use PUT /groups/{groupId}/locations.

📄️Merge updated data into a group by ID

Merges the supplied fields into an existing group identified by its certifyGroupId — an UPSERT_DATA merge, not a full replace; omitted fields are preserved on the existing record rather than cleared. Updatable fields include the group's core attributes and tax information; taxInfo.billingTin, taxInfo.billingNpi, and email are validated and return 400 if malformed. Use this endpoint for non-legacy group updates — for groups sourced from an external system and identified by source type and crosswalk ID, use the deprecated PUT /groups/{sourceType}/{crosswalkId} instead. Every call publishes an audit event, even when the merged data is identical to the existing record (no database row update occurs in that case, but the audit event is still emitted).

📄️Associate practitioners with a group

Associates one or more practitioners with a group, creating group–practitioner membership records. Optionally also associates each practitioner with one or more specific locations within the group. Suitable for initial population as well as incremental additions. Idempotent — an UPSERT_DATA merge keyed on the group and practitioner, so calling again for an already-associated practitioner re-merges the supplied data into the existing association rather than creating a duplicate or returning a conflict.

📄️List all relationships for a group

Returns every relationship record associated with the specified group in one call: network associations, participations, specialty associations, entity addresses, group locations (each with its own nested networks, specialties, participations, and addresses), and group practitioners (each with their own networks, participations, specialties, and per-location associations). Use this endpoint for a consolidated view of everything a group participates in; for a targeted subset use the more specific sub-resource endpoints. Returns all rows currently present with no active/terminated filtering — the underlying query and tables have no status column, so distinguishing active from historical or terminated relationships, if possible at all, requires inspecting fields inside each item's own data payload.

📄️Update a group specialty's effective or termination date

Updates the effective date and/or termination date of an existing group specialty association, identified by tenantGroupSpecialtyId in the request body. At least one of effectiveDate or terminationDate must be supplied. This is a partial update — an omitted date field is preserved from the existing record, not cleared. For bulk specialty management (adding new specialties and updating existing ones in a single call) use PATCH /groups/{id}/specialties.

📄️Batch add and update group specialties

Adds new specialty associations and/or updates existing specialty associations for a group in a single request. New entries create group–specialty records; update entries modify existing associations (effective/termination dates, specialty linkage). Use this endpoint for bulk specialty management — for single-specialty additions use POST /groups/{id}/specialties, and for date-only updates to a single specialty use PUT /groups/{id}/specialties. Permission note: if any update entry includes a non-blank newTenantSpecialtyId (reassigning the specialty), the caller must also hold the group:correct:specialty permission — such a request without that permission returns 403. Pure additions or date/isPrimary-only updates only require the standard group:update permission.

📄️Add a specialty to a group

Adds a single specialty to an existing group, creating a group–specialty association. Optionally also adds the specialty to a specific group location and/or network in the same request via effective-date fields (groupSpecialtyEffectiveDate, groupLocationSpecialtyEffectiveDate, networkSpecialtyEffectiveDate). Supports effective-dating at creation but not termination-dating — use POST /groups/{id}/specialties/terminate to terminate a specialty. To add or update multiple specialties in a single call use PATCH /groups/{id}/specialties.

📄️Upload a supporting document for a group

Uploads a supporting document (license, certificate, insurance form, IRS document, etc.) for a group. The file is stored in cloud storage and its metadata is written into the group's supportingDocuments record list. No MIME-type or file-size restriction is currently enforced — any file is accepted and stored as application/octet-stream regardless of its actual type. Not idempotent — each call creates a new document entry even if the same file is uploaded again. The response contains only the uploaded fileName and a status message; it does not include the stored cloud storage path or URL.

📄️Update a group by source system identifier (deprecated)

**Deprecated.** Updates an existing group identified by its originating source system type and crosswalk identifier. Prefer PUT /groups/{id} for all new integrations; no removal date has currently been published for this endpoint. Unlike PUT /groups/{id}, this endpoint applies JSON Schema validation to the request body and returns 400 on failure. sourceType is validated against the core_sources table — a dynamic, tenant-managed lookup rather than a fixed enum — and the request fails with 400 if no matching source row exists.