# Create location

Canonical page: https://docs.ovok.com/slim-apis/location/create-location

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/location` |

[Authentication](/authentication) · [Access policies](/access-policies)

Creates a location (room or bed), optionally in a zone.

**Auth:** Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant `Location:create` and `Device:update` (admins and super admins skip this check).
**Scope:** The location is created in the caller's project (from the token). A super-admin caller can pass `?projectId=<uuid>` to create it in that project instead. Any other caller who passes `projectId` gets a 403.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string (uuid)` | No | Create the location in this project. Super admins only. Must name an existing project. |

### Body [#body]

The body is strict: a field that is not listed here fails validation.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Location name. At least 1 character. Must be unique. |
| `floor` | `string` | No | Floor code. |
| `room` | `string` | No | Room code. |
| `bed` | `string` | No | Bed code. |
| `organizationId` | `string` | No | Id of the zone the location belongs to. |

## Behaviour [#behaviour]

- `name` must be unique. The check is an exact name match against the locations your token can search. With `?projectId`, the check runs in that project only.
- When any of `floor`, `room` or `bed` is set, the combination of zone, floor, room and bed must also be unique. The comparison ignores case and extra whitespace. A location with only a name has no such check.
- `floor`, `room` and `bed` are stored as type codes on the location. `organizationId` sets the zone. The zone must be in your project, one of its sub-projects, or its parent project.
- The create is guarded against a concurrent create of the same floor, room and bed. If another request creates it first, you get a 409 that names the existing location.
- No devices or residents are attached. Use `PUT /v1/slim/location/{id}` for that.
- A location-created entry is added to the change history. A failure to write that entry does not fail the request.
- The response is the created location, in the same shape as `GET /v1/slim/location/{id}`.

## Example [#example]

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/location' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Room 201",
    "floor": "2",
    "room": "201",
    "bed": "A",
    "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918"
  }'
```

## Successful response [#successful-response]

`201` — Location created successfully.

```json
{
  "id": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
  "name": "Room 201",
  "floor": "2",
  "room": "201",
  "bed": "A",
  "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "organizationName": "Zone A"
}
```

The body is the created location, as `GET /v1/slim/location/{id}` returns it.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | Location id. |
| `name` | `string` | Location name. Empty string when the location has none. |
| `floor` | `string` | Floor code. Left out when not set. |
| `room` | `string` | Room code. Left out when not set. |
| `bed` | `string` | Bed code. Left out when not set. |
| `organizationId` | `string (uuid)` | Zone id. Left out when the location has no zone. |
| `organizationName` | `string` | Zone name. Left out when the location has no zone. |
| `deviceId` | `string[]` | Ids of every device at the location. Left out when there is none. |
| `deviceName` | `string` | Alphabetically first name among the devices at the location. Left out when there is none. |
| `patientId` | `string (uuid)` | Resident on the first device at the location that has one. Left out when there is none. |
| `patientName` | `string` | That resident's name. Left out when there is none. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | `organizationId` names no zone you can read, or the FHIR backend refuses the location. |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, you lack `Location:create` or `Device:update`, you set `projectId` without being a super admin, or the zone is outside your project, its parent or its sub-projects. |
| [`409`](/errors/conflict) | Another location in the zone already has the same floor, room and bed. The body names it in `existingLocationId` and `existingLocationName`. |
| [`422`](/errors/validation-failed) | The body or `projectId` fails validation, `projectId` names no project, or another location has the same name. |
