---
title: "Create a location."
method: POST
path: "/api/v1/locations"
tags: ["Locations"]
---

# Create a location.

`POST /api/v1/locations`

## Request

- Base URL: `https://api.mapulus.com`
- URL: `https://api.mapulus.com/api/v1/locations`
- Auth: HTTP bearer

This endpoint creates a single location when provided a valid layer_id in the JSON body. Locations must also have either a valid address or latitude and longitude. When adding `custom_attributes`, if the custom_attribute does not already exist on the layer (based on name), you can set the `create_or_update_custom_attributes` in the main body of the JSON or `create_or_update_custom_attribute` in the nested attribute object to create or ignore it. Without this flag, new custom_attributes will return an error.
Example request:
```
curl --location 'https://api.mapulus.com/api/v1/locations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-token>' \
--data '{
  "lat": -27.4704528,
  "lon": 153.0260341,
  "label": null,
  "title": "Head Office",
  "address": "Brisbane, Australia",
  "external_id": null,
  "travel_contour": true,
  "contour_mode": "driving",
  "contour_metric": "minutes",
  "contour_style": "polygons",
  "contour_minutes": "15",
  "layer_id": "<layer-id>",
  "create_or_update_custom_attributes": true,
  "custom_attributes": [
    {
      "object": "custom_attribute",
      "name": "Location Type",
      "value": "Public Store",
      "create_or_update_custom_attribute": false
    }
  ]
}'

## Request body

- object
  - `object` string
  - `lat` number, float, nullable
  - `lon` number, float, nullable
  - `label` string, nullable
  - `title` string, nullable
  - `address` string, nullable
  - `external_id` string, nullable
  - `travel_contour` boolean, nullable
  - `contour_mode` string, nullable
  - `contour_metric` string, nullable
  - `contour_style` string, nullable
  - `contour_minutes` string, nullable
  - `layer_id` string, uuid, required
  - `create_or_update_custom_attributes` boolean
  - `custom_attributes` object[]
    - `object` string, required
    - `name` string, required
    - `value` string, nullable
    - `create_or_update_custom_attribute` boolean

## Response `200`

Success: Creates a single location.

- object
  - `object` string, required
  - `id` string, uuid, required
  - `lat` number, float, nullable, required
  - `lon` number, float, nullable, required
  - `label` string, nullable
  - `title` string, nullable
  - `address` string, nullable
  - `external_id` string, nullable
  - `geocoding_error` boolean, nullable
  - `geocoding_error_type` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `travel_contour` boolean, nullable
  - `contour_mode` string, nullable
  - `contour_metric` string, nullable
  - `contour_style` string, nullable
  - `contour_minutes` string, nullable
  - `map_id` string, uuid, required
  - `layer_id` string, uuid, required
  - `custom_attributes` object[], required
    - `object` string, required
    - `name` string, required
    - `value` string, nullable, required
    - `custom_attribute_id` string, uuid, required
    - `custom_attribute_value_id` string, uuid, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `401`: Unauthorized: Invalid API Key or does not have the correct permission to access resource.
- `422`: Unprocessable Entity: The request because the request was well-formed, but the custom attribute does not exist.

---

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