---
title: "Bulk create or update facilities"
method: POST
path: "/v2/facilities/bulk"
tags: ["Facility Management"]
---

# Bulk create or update facilities

`POST /v2/facilities/bulk`

## Request

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

Create or update up to 20 facilities in one request. The response returns one result per input record, in the same order.

**Every record is a whole-record replace**, on the same terms as the single-facility route above. Omitted fields are cleared.

Records are processed independently. A record that fails a value check, such as a malformed email or an unknown country, is returned with `status: FAILED` and the rest still apply.

If any record is missing `externalId` or `name`, or has a field of the wrong type, the whole request is rejected with a `422` and nothing is written.

More than 20 facilities is rejected with a `400`.

## Request body

- BulkUpsertFacilitiesRequest
  - `facilities` PublicFacilityRequest[], required: Maximum 20 per request.
    - `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`

Bulk operation completed. Check each entry in `results`; a `200` does not mean every record succeeded.

- BulkUpsertFacilitiesResponse
  - `total` integer: Number of facilities in the request.
  - `successCount` integer: Number written.
  - `failureCount` integer: Number that failed.
  - `results` PublicFacilityResult[]: One result per input index, in request order.
    - `index` integer: Position of the facility in the request array.
    - `status` 'SUCCESS' | 'FAILED': Whether this record was written.
    - `externalId` string, nullable
    - `facilityId` string, nullable: Set when the record was written; null on failure.
    - `error` string, nullable: Why this record failed; null on success.

## Other responses

- `400`: Batch size exceeded; send at most 20 facilities per request.
- `401`: Unauthorized
- `403`: Forbidden
- `422`: A facility is missing a required field or has a field of the wrong type. Nothing is written.

---

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