---
title: "Adds a location (job site / address) to a customer."
method: POST
path: "/api/v1/customers/{id}/locations"
tags: ["Customers"]
---

# Adds a location (job site / address) to a customer.

`POST /api/v1/customers/{id}/locations`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/customers/{id}/locations`
- Auth: HTTP bearer

Requires `ManageCustomers` and an `Idempotency-Key` header. Same rules as
Customers → Addresses → Add in the app: `name`, `address`, `city`, `state`
and `postalCode` are required; `isMailingAddress: true` moves the mailing flag here
from the customer's other locations, and a customer's first location is always the mailing
address. Attributed to the user who created the API key.

## Path parameters

- `id` integer, required

## Request body

- CustomerLocationWriteRequest: Body of `POST /api/v1/customers/{id}/locations` and `PATCH /api/v1/customers/{id}/locations/{locationId}`. On create, `name`, `address`, `city`, `state` and `postalCode` are required (as on the Customers → Addresses form). On PATCH only the fields sent change, `""` clears an optional field, and the required ones cannot be cleared. Example: `{ "name": "Rental Property 1", "address": "12 Oak St", "city": "Springfield", "state": "IL", "postalCode": "62701" }`.
  - `name` string, nullable: Label for the location, 1–100 characters. Example: `"Main Office"`.
  - `address` string, nullable: Street address line 1, up to 200 characters. Example: `"12 Oak St"`.
  - `address2` string, nullable: Street address line 2 (suite, unit), up to 200 characters.
  - `city` string, nullable: City, up to 100 characters. Example: `"Springfield"`.
  - `state` string, nullable: State / province, up to 50 characters. Example: `"IL"`.
  - `postalCode` string, nullable: ZIP / postal code, up to 20 characters. Example: `"62701"`.
  - `country` string, nullable: Country, up to 100 characters. Example: `"USA"`.
  - `isMailingAddress` boolean, nullable: True makes this the customer's mailing address and unmarks every other location of the customer. Default `false` on create — except that a customer's first location is always the mailing address.
  - `isActive` boolean, nullable: False retires the location (kept for history, no longer offered for new jobs). Default `true` on create.
  - `notes` string, nullable: Free-text notes about the site (gate codes, parking), up to 500 characters.

## Response `201`

The new location; `Location` points at `/api/v1/customers/{id}/locations/{locationId}`.

- CustomerLocationDto: An additional address / job site belonging to a customer, as returned by `GET /api/v1/customers/{id}/locations`. Jobs can reference one of these as the site to work at; the customer's primary address is on the customer itself.
  - `id` integer: Numeric id of the location. Stable within this organization.
  - `syncId` string, uuid: Globally unique sync id (GUID). Use it as the `after` pagination cursor.
  - `customerId` integer: Id of the owning customer (matches the `{id}` in the URL).
  - `name` string: Label given to the location, e.g. `"Main Office"` or `"Rental Property 1"`.
  - `address` string, nullable: Street address line 1.
  - `address2` string, nullable: Street address line 2 (suite, unit).
  - `city` string, nullable: City.
  - `state` string, nullable: State / province.
  - `postalCode` string, nullable: ZIP / postal code.
  - `country` string, nullable: Country.
  - `isMailingAddress` boolean: True when this is the customer's mailing address.
  - `isActive` boolean: False when the location has been retired and should not be offered for new jobs.
  - `notes` string, nullable: Free-text notes about the site (gate codes, parking), max 500 characters.
  - `createdAt` string, date-time: UTC creation timestamp.
  - `updatedAt` string, date-time, nullable: UTC timestamp of the last edit; null when never edited.

## Other responses

- `400`: Malformed body, a field over its length limit, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: No such customer in this organization (also for deleted customers).
- `409`: The key's creator is unknown on this server, so the write cannot be attributed.
- `422`: A required field is missing; the fields are listed in `errors`.
- `429`: Too Many Requests

---

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