---
title: "Merge updated data into a group by ID"
method: PUT
path: "/groups/{id}"
tags: ["Group"]
---

# Merge updated data into a group by ID

`PUT /groups/{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).

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string

## Request body

- UpdateGroupRequest — Request to update an existing group with complete data
  - `certifyGroupId` string — Primary key - Certify Group ID
  - `sourceId` string — Foreign key - Source ID
  - `crosswalkId` string — Foreign key - Crosswalk ID
  - `affiliation` string — Group affiliation
  - `npi` string — National Provider Identifier
  - `name` string — Group name
  - `contacts` Contact1[] — Group contacts
    - `name` string — Contact name
    - `email` string — Contact email
    - `phone` string — Contact phone
    - `title` string — Contact title
    - `department` string — Contact department
  - `parentHealthcareOrg` string — Parent healthcare organization ID
  - `tin` string — Tax Identification Number
  - `type` string — Group type
  - `legalTaxName` string — Legal tax name
  - `email` string — Group Overview email address — an email with no associated contact type (CP-35967). Distinct from contacts[] entries and from the typed contractingContact/officeManager/credentialingContact emails.
  - `active` boolean — Whether the group is active
  - `telemedicineAvailable` boolean — Whether telemedicine is available
  - `taxInfo` TaxInfo
    - `legalTaxName` string
    - `taxEntityStates` string[]
    - `irs575File` string
    - `w9File` string
    - `billingTin` string — Billing Tax Identification Number (TIN) used for billing purposes.
    - `billingNpi` string — Billing National Provider Identifier (NPI) used for billing purposes.
  - `bedCount` integer — Number of beds
  - `dea` string — DEA number
  - `specialtyIds` string[] — Specialty IDs to associate with the group (consistent with create practitioner pattern)
  - `groupEffectiveDate` string, date
  - `externalGroupId` string — External group ID from tenant system
  - `contactPerson` object — Contact person information as JSON
  - `userDefinedFields` object — Custom user-defined fields. Replaces the entire userDefinedFields object (PUT semantics).
  - `credentialingContact` CredentialingContact — Credentialing contact information
    - `name` string — Contact name
    - `email` string — Contact email
    - `phone` string — Contact phone
    - `title` string — Contact title
    - `department` string — Contact department
  - `npdbEnrollmentEnabled` boolean — Whether NPDB enrollment is enabled
  - `createdAt` string, date-time
  - `createdBy` string — Foreign key - Created by User ID
  - `addresses` GroupAddressData[] — Group addresses to update
    - `addressType` string — Address type
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — State
    - `zip` string — ZIP code
    - `county` string — County
    - `country` string — Country
    - `isPrimary` boolean — Whether this is the primary address

## Response `200`

Group successfully updated

- GroupResponse — Complete group information including core data, tenant data, and addresses
  - `certifyId` string — Primary key - Certify Group ID
  - `crosswalkId` string — Crosswalk ID
  - `sourceId` string — Source ID
  - `sourceUrl` string — Source URL
  - `sourceType` string — Source type
  - `sourceName` string — Source name
  - `sourceDescription` string — Source description
  - `survivorId` string — Survivor ID
  - `groupData` object — Complete group data
  - `addresses` GroupAddressData[] — Group addresses (billing, remittance, service)
    - `addressType` string — Address type
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — State
    - `zip` string — ZIP code
    - `county` string — County
    - `country` string — Country
    - `isPrimary` boolean — Whether this is the primary address
  - `data` object — Raw data object (legacy)
  - `tenantGroupId` string — Tenant Group ID (legacy)
  - `lastUpdated` string, date-time
  - `addressesCopy` GroupAddressData[]
    - `addressType` string — Address type
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — State
    - `zip` string — ZIP code
    - `county` string — County
    - `country` string — Country
    - `isPrimary` boolean — Whether this is the primary address

## Other responses

- `400` — Invalid request body — taxInfo.billingTin or taxInfo.billingNpi failed format validation
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions
- `404` — Group not found
- `500` — Internal server error during request processing (e.g., network timeout, etc.)

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)