---
title: "Create or update a facility"
method: POST
path: "/v2/facilities"
tags: ["Facility Management"]
---

# Create or update a facility

`POST /v2/facilities`

## Request

- Base URL: `https://api.prod.goaugment.com`
- URL: `https://api.prod.goaugment.com/v2/facilities`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/goaugment/apis/augment-api/docs/v2/facilities/post.ts> (a function with typed inputs; its response is checked against the schema)

Create or update a single facility, keyed on the `externalId` you send. An `externalId` not yet seen for your brokerage creates a facility; one already stored updates it.

**This is a whole-record replace, not a partial update.** Any field omitted from the body is cleared on an existing facility rather than left as it was. Send the complete record on every call. Posting a facility without `notes`, for example, erases notes already stored against it.

## Request body

- PublicFacilityRequest
  - `externalId` string, required: Your identifier for the facility. Used as the upsert key.
  - `name` string, required
  - `address` PublicFacilityAddressRequest: Address as posted. An omitted `country` resolves to US.
    - `street1` string, required
    - `street2` string, nullable
    - `city` string, required
    - `stateOrProvince` string, nullable: Uppercased and validated against the country. Required for US addresses.
    - `postalCode` string, required
    - `country` string: ISO alpha-2 or alpha-3 code, or a country name. Stored as alpha-2.
  - `email` string, email, nullable
  - `phone` string, nullable: Normalized to E.164.
  - `phoneExtension` string, nullable
  - `notes` string, nullable

## Response `200`

Facility created or updated

- PublicFacilityResponse
  - `facilityId` string: Augment's identifier for the facility.
  - `externalId` string, nullable
  - `name` string
  - `address` PublicFacilityAddress: Address as stored, with every field resolved.
    - `street1` string
    - `street2` string, nullable
    - `city` string
    - `stateOrProvince` string, nullable
    - `postalCode` string
    - `country` string
  - `email` string, nullable
  - `phone` string, nullable
  - `phoneExtension` string, nullable
  - `notes` string, nullable

## Other responses

- `400`: Invalid request data
- `401`: Unauthorized
- `403`: Forbidden
- `422`: A field is missing or invalid. `details` names the field.

---

[API](https://skmtc.dev/goaugment/apis/augment-api.md) - [All operations](https://skmtc.dev/goaugment/apis/augment-api/llms.txt) - [OpenAPI document](https://skmtc.dev/goaugment/apis/augment-api/revisions/b61097634d79?raw)