> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Places

> List, add, correct, deactivate and delete an organization's own physical places — stores, warehouses, farms, plants — with their coordinates, phone numbers, websites and email addresses, the programmatic equivalent of the organization's Locations page in the dashboard.

Programmatic equivalent of the organization's Locations page in the
dashboard (the list, and its add, edit and delete forms, including the
phone number, website and email address rows). The page and the API write
through the same service and the same form validation, so a place saved on
one reads back on the other, and a value one refuses the other refuses too.

A place is a physical location the organization itself runs: a store, a
warehouse, a farm, a plant. Local search ranks places by distance, so a
place without `latitude` and `longitude` is stored but cannot be found by a
shopper nearby.

## When to use

* The organization has no places recorded yet, or is missing some.
* An address, phone number, website or email address has changed.
* A place has closed (mark it inactive).

## Auth

`X-API-Key` header or OAuth token. Reading needs any member of the
organization (or any API key of it). Writing needs an OWNER, MANAGER or
EDITOR (or an API key with the EDITOR role or above): a read-only key gets
`403`. An organization the caller does not belong to, or a place another
organization owns, is `404`.

## Flow

```
GET    /locations/api/v1/organizations/{organization_id}/places
POST   /locations/api/v1/organizations/{organization_id}/places
GET    /locations/api/v1/organizations/{organization_id}/places/{place_id}
PATCH  /locations/api/v1/organizations/{organization_id}/places/{place_id}
DELETE /locations/api/v1/organizations/{organization_id}/places/{place_id}
```

* **`GET .../places`** — every place by name, inactive ones included,
  paginated: `id`, `name`, the address (`address_line_1`,
  `address_line_2`, `city`, `region`, `county`, `postal_code`,
  `country`), `latitude`, `longitude`, `gln`, `supply_chain_type`,
  `google_place_id`, `is_active`, the lists `urls`, `phones` and
  `emails`, `created`, `modified`.
* **`POST .../places`** — add a place. `address_line_1`, `city`,
  `region`, `postal_code` and `country` (ISO alpha-2, such as `US`) are
  required. Optional: `name`, `address_line_2`, `latitude` with
  `longitude`, `gln`, `supply_chain_type`, `google_place_id`,
  `is_active` (default `true`), and the contact lists:
  * `phones`: `label` (required), `number`, optional `extension`;
  * `urls`: `url` (http or https), optional `label` (default `Website`);
  * `emails`: `email`, optional `label` (default `Inquiries`);
  * each row takes an optional `sort_order`.
    Returns `201` with the place.
* **`PATCH .../places/{place_id}`** — send only the fields you are
  changing. A contact list you send replaces the place's whole list (an
  empty list clears it); a list you leave out is untouched. `null` clears
  `gln` and `supply_chain_type` and is `422` anywhere else.
* **`DELETE .../places/{place_id}`** — delete the place and its contact
  rows (`204`). A place that traceability records (harvest areas,
  critical tracking events) still name is `409`; send
  `{"is_active": false}` instead.

A value the dashboard form would refuse — a postal code over 20 characters, an
invalid phone number or email address, a non-web URL, a GLN that is not 13
digits, a `supply_chain_type` without a `gln`, `latitude` without
`longitude` — is `422`, with one `details` row per field. A contact row's
error is located by its position in the list you sent, such as
`["body", "data", "phones", 1, "number"]`.

## Verify

1. `GET .../places` again and confirm each place you added or changed
   reads back with the address, coordinates and contact details you
   intended.
2. Confirm no place you did not mean to touch changed or disappeared.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.