---
title: "Create a facility for the tenant"
method: POST
path: "/facilities"
tags: ["Facility"]
---

# Create a facility for the tenant

`POST /facilities`

Creates a CoreFacility and its TenantFacility association for the tenant (create path; certifyFacilityId is not yet known). Use this to establish a new facility record; use PUT /facilities/{id} instead when the certifyFacilityId is already known. A crosswalk ID is generated from the facility's tenant-scoped identity (NPI+TIN, NCPDP, externalId, or an address hash, depending on tenant identity configuration) — this crosswalk, not any single submitted field, is what the platform treats as the facility's unique identity key. Request body is validated against the facility-upsert JSON Schema and, for tenants configured with isFacilityExternalIdAsCrosswalk=true, against additional externalId/address-hash uniqueness rules (see FacilityValidationService). The primary address, if present, may be standardized via the address cleanser before being persisted. When facility.upsert.sync-survivorship.enabled is true (default), a synchronous (not queued/async) survivorship call is also triggered to the core data layer. Returns HTTP 201 with an ID map only (crosswalkId, corefacilityId, tenantfacilityId, and related batch-alias IDs) — not the full facility object; call GET /facilities/{id} afterwards to read back the created record. See PUT /facilities/{id} for the update path.

## 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 created

- 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 (e.g. duplicate NPI/TIN, missing name/npi/tin).
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions
- `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)