---
title: "Update a facility and its tenant association"
method: PUT
path: "/facilities/{id}"
tags: ["Facility"]
---

# Update a facility and its tenant association

`PUT /facilities/{id}`

Updates the CoreFacility identified by the path certifyFacilityId and its TenantFacility association for the tenant (update path). Use this when the certifyFacilityId is already known; use POST /facilities instead to create a new facility. Stored identity fields not present in the payload are merged in before validation, then the same crosswalk identity used at create time is re-resolved and updated — retrying this call with the same payload is safe and updates the same rows (idempotent). Request body is validated against the same facility-upsert JSON Schema and tenant-specific rules used by POST /facilities. Returns HTTP 201 (not 200) on success — this matches the create endpoint's status code by historical convention rather than by REST semantics for an update; treat any 2xx as success rather than branching on the exact code. Response body is the same ID map as create (crosswalkId, corefacilityId, tenantfacilityId, etc.), not the full facility object. See POST /facilities for the create path.

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string, required

## Request body

- FacilityUpsertRequest — Facility create/upsert payload. Top-level required: name only (matches facility-upsert.schema.json). npi and tin are required for default tenants; Pharmacy facilities use ncpdpId; external-id and address-hash modes follow FacilityValidationService rules. If initialCredentialingDate is provided, lastCredentialingDate is also required.
  - `facilityId` string — Certify facility ID; only relevant for update flows
  - `name` string, required — Facility name
  - `npi` string — 10-digit National Provider Identifier. Required for default tenants; optional for Pharmacy (ncpdpId) and some external-id / address-hash flows.
  - `tin` string — 9-digit Tax Identification Number. Required for default tenants; optional for Pharmacy (ncpdpId) and some external-id / address-hash flows.
  - `ncpdpId` string — NCPDP identifier for Pharmacy facilities (CP-33224). Required when facilityType is Pharmacy.
  - `facilityType` string — Facility type
  - `facilityEffectiveDate` string, date — Effective date of the facility (YYYY-MM-DD)
  - `externalId` string — External identifier for the facility, used as crosswalk for some tenants
  - `dba` string — Doing-business-as name
  - `attestationDate` string, date — Attestation date (YYYY-MM-DD)
  - `effectiveDate` string, date — Effective date (YYYY-MM-DD)
  - `delegationStatus` 'Delegated' | 'Direct' — Delegation status of the facility
  - `addresses` FacilityUpsertAddress[] — Addresses associated with the facility
    - `address1` string — Address line 1
    - `address2` string — Address line 2
    - `city` string — City
    - `state` string — State
    - `country` string — Country
    - `zipcode` string — Zip code
    - `source` string — Source of the address
    - `type` string — Type of address
    - `createdAt` string, date-time — The date the record was created
    - `createdBy` string — The user who created the record
    - `updatedAt` string, date-time — The date the record was last updated
    - `updatedBy` string — The user who last updated the record
    - `isPrimary` boolean — States if the address is the primary address for the facility
    - `zipExtension` string — ZIP+4 extension returned by the address cleanser (CP-28784)
    - `latitude` number, double — Latitude returned by the address cleanser (CP-28784)
    - `longitude` number, double — Longitude returned by the address cleanser (CP-28784)
    - `stateFips` string — State FIPS code returned by the address cleanser (CP-28784)
    - `countyFips` string — County FIPS code returned by the address cleanser (CP-28784)
    - `formattedAddress` string — Fully formatted address returned by the address cleanser (CP-28784)
  - `businessPurpose` FacilityUpsertBusinessPurpose — Facility business purpose flags
    - `isForCredentialing` FacilityUpsertBusinessPurposeFlag — A business purpose flag and its reason
      - `value` boolean — The flag value
      - `reason` string — The reason for the flag value
    - `isForMonitoring` FacilityUpsertBusinessPurposeFlag — A business purpose flag and its reason
      - `value` boolean — The flag value
      - `reason` string — The reason for the flag value
  - `contacts` FacilityUpsertContact[] — Contacts associated with the facility
    - `name` string, required — Contact name
    - `type` string, required — Contact type
    - `phone` string, required — Contact phone number
    - `email` string, email — Contact email address
    - `fax` string — Contact fax number
  - `serviceAddress` FacilityUpsertTypedAddress — A single-purpose facility address
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — Two-letter US state code
    - `county` string — County
    - `country` string — Country
    - `zip` string — Zip code
    - `zipExtension` string — ZIP+4 extension returned by the address cleanser (CP-28784)
    - `latitude` number, double — Latitude returned by the address cleanser (CP-28784)
    - `longitude` number, double — Longitude returned by the address cleanser (CP-28784)
    - `stateFips` string — State FIPS code returned by the address cleanser (CP-28784)
    - `countyFips` string — County FIPS code returned by the address cleanser (CP-28784)
    - `formattedAddress` string — Fully formatted address returned by the address cleanser (CP-28784)
  - `officeAddress` FacilityUpsertTypedAddress — A single-purpose facility address
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — Two-letter US state code
    - `county` string — County
    - `country` string — Country
    - `zip` string — Zip code
    - `zipExtension` string — ZIP+4 extension returned by the address cleanser (CP-28784)
    - `latitude` number, double — Latitude returned by the address cleanser (CP-28784)
    - `longitude` number, double — Longitude returned by the address cleanser (CP-28784)
    - `stateFips` string — State FIPS code returned by the address cleanser (CP-28784)
    - `countyFips` string — County FIPS code returned by the address cleanser (CP-28784)
    - `formattedAddress` string — Fully formatted address returned by the address cleanser (CP-28784)
  - `billingAddress` FacilityUpsertTypedAddress — A single-purpose facility address
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — Two-letter US state code
    - `county` string — County
    - `country` string — Country
    - `zip` string — Zip code
    - `zipExtension` string — ZIP+4 extension returned by the address cleanser (CP-28784)
    - `latitude` number, double — Latitude returned by the address cleanser (CP-28784)
    - `longitude` number, double — Longitude returned by the address cleanser (CP-28784)
    - `stateFips` string — State FIPS code returned by the address cleanser (CP-28784)
    - `countyFips` string — County FIPS code returned by the address cleanser (CP-28784)
    - `formattedAddress` string — Fully formatted address returned by the address cleanser (CP-28784)
  - `mailingAddress` FacilityUpsertTypedAddress — A single-purpose facility address
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — Two-letter US state code
    - `county` string — County
    - `country` string — Country
    - `zip` string — Zip code
    - `zipExtension` string — ZIP+4 extension returned by the address cleanser (CP-28784)
    - `latitude` number, double — Latitude returned by the address cleanser (CP-28784)
    - `longitude` number, double — Longitude returned by the address cleanser (CP-28784)
    - `stateFips` string — State FIPS code returned by the address cleanser (CP-28784)
    - `countyFips` string — County FIPS code returned by the address cleanser (CP-28784)
    - `formattedAddress` string — Fully formatted address returned by the address cleanser (CP-28784)
  - `irsAddress` FacilityUpsertTypedAddress — A single-purpose facility address
    - `addressLine1` string — Address line 1
    - `addressLine2` string — Address line 2
    - `city` string — City
    - `state` string — Two-letter US state code
    - `county` string — County
    - `country` string — Country
    - `zip` string — Zip code
    - `zipExtension` string — ZIP+4 extension returned by the address cleanser (CP-28784)
    - `latitude` number, double — Latitude returned by the address cleanser (CP-28784)
    - `longitude` number, double — Longitude returned by the address cleanser (CP-28784)
    - `stateFips` string — State FIPS code returned by the address cleanser (CP-28784)
    - `countyFips` string — County FIPS code returned by the address cleanser (CP-28784)
    - `formattedAddress` string — Fully formatted address returned by the address cleanser (CP-28784)
  - `userDefinedFields` object — Custom tenant-defined fields. Replaces the entire userDefinedFields object (PUT semantics).
  - `lastCredentialingDate` string, date — Date of the last credentialing (YYYY-MM-DD). Required when initialCredentialingDate is provided.
  - `initialCredentialingDate` string, date — Date the facility was initially credentialed (YYYY-MM-DD)
  - `nextCredentialingDate` string, date — Date of the next credentialing due (YYYY-MM-DD)
  - `groupDetails` FacilityUpsertGroupDetail[] — Tenant group associations for the facility
    - `tenantGroupId` string, required — Tenant group ID
    - `effectiveDate` string, date — Effective date of the group association (YYYY-MM-DD)
    - `networkLinks` FacilityUpsertNetworkLink[] — Network associations for this group
      - `networkId` string, required — Network ID
      - `effectiveDate` string, date — Effective date of the network association (YYYY-MM-DD)

## Response `201`

Facility successfully updated

- FacilityUpsertResponse — Result of a facility create/update. Always includes crosswalkId, corefacilityId, and tenantfacilityId. May include additional batch-alias keys (e.g. facilityentityaddressId) depending on which optional sections were submitted.
  - `crosswalkId` string — Crosswalk ID generated for the CoreFacility record
  - `corefacilityId` string — Certify facility ID of the upserted CoreFacility record
  - `tenantfacilityId` string — ID of the upserted TenantFacility record
  - `facilityentityaddressId` string — ID of the upserted FacilityEntityAddress record; present only when an office, billing, or mailing address was submitted

## Other responses

- `400` — Invalid request body. One of: a list of JSON Schema validation messages; {"errors": ["..."]} from tenant-specific validation (e.g. externalId/address-hash rules); or a plain-string message for other invalid requests.
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions
- `409` — Conflict - Initial credentialing workflow already exists
- `500` — Internal server error

---

[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)