---
title: "Create a company location"
method: POST
path: "/v1/companies/{company_id}/locations"
tags: ["Locations"]
---

# Create a company location

`POST /v1/companies/{company_id}/locations`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/companies/{company_id}/locations`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gusto/apis/gusto-api/docs/v1/companies/:company_id/locations/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a company location, which represents any address associated with a company: mailing
addresses, filing addresses, or work locations. A single address may serve multiple, or all, purposes.

Since all company locations are subsets of locations, use the Locations endpoints to
[get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record.

scope: `companies:write`

## Path parameters

- `company_id` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Request body

- CompanyLocationRequest: Request body for creating a company location (company address).
  - `street_1` string, required: Street address line 1.
  - `street_2` string, nullable: Street address line 2.
  - `city` string, required: City.
  - `state` string, required: State code (e.g. CA). Must be a valid two-letter state code.
  - `zip` string, required: ZIP code. Must be a valid US zip (e.g. 12345 or 12345-6789).
  - `country` string: Country code. Defaults to USA.
  - `phone_number` string, required: Phone number. Must be 10 digits.
  - `mailing_address` boolean: Specify if this location is the company's mailing address.
  - `filing_address` boolean: Specify if this location is the company's filing address.

## Response `201`

Created

- Location: The representation of an address in Gusto.
  - `uuid` string, required: The UUID of the location object.
  - `version` string: The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field.
  - `company_uuid` string: The UUID for the company to which the location belongs. Only included if the location belongs to a company.
  - `phone_number` string: The phone number for the location. Required for company locations. Optional for employee locations.
  - `street_1` string
  - `street_2` string, nullable
  - `city` string
  - `state` string
  - `zip` string
  - `country` string
  - `mailing_address` boolean: Specifies if the location is the company's mailing address. Only included if the location belongs to a company.
  - `filing_address` boolean: Specifies if the location is the company's filing address. Only included if the location belongs to a company.
  - `created_at` string: Datetime for when location is created
  - `updated_at` string: Datetime for when location is updated
  - `active` boolean: The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.
  - `inactive` boolean: The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.
  - `warnings` WarningObject[]: An array of warning objects that provide additional information about the address. Warnings do not prevent the address from being saved.
    - `error_key` string: Specifies where the warning occurs. Typically identifies the attribute or parameter related to the warning.
    - `category` string: Specifies the type of warning. Can be used to build custom warning handling.
    - `message` string: Provides details about the warning. The message can be surfaced directly to the end user.

## Other responses

- `404`: Not Found
- `422`: Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

## Changes

- **2026-11-03** `f98575fa2a5e`: 1 info
  - added the optional property `warnings` to the response with the `201` status

[Operation history](https://skmtc.dev/gusto/apis/gusto-api/changes/v1/companies/:company_id/locations/post.md)

---

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