Locations API

Overview

The Locations API manages physical addresses where business entities operate, including registered offices, operating addresses, warehouses, branches, and points of sale. Locations are used for registration threshold determination, compliance tracking, and employee management.

Core endpoints

List locations

Get all locations for a business entity.

GET /business-entities/:businessEntityId/locations

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Unique identifier for the business entity

Response

{
  "locations": [
    {
      "id": "cm3f7a9k20001l508x2d4q6ve",
      "name": "San Francisco office",
      "locationTypes": ["PRINCIPAL_PLACE_OF_BUSINESS"],
      "address": {
        "id": 88,
        "addressLine1": "123 Main Street",
        "addressLine2": "Suite 100",
        "addressLine3": null,
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      },
      "startDate": "2020-01-15T00:00:00.000Z",
      "employeeCount": 25,
      "isVirtualAddress": false,
      "corporationId": 123,
      "createdAt": 1579082400000,
      "updatedAt": 1710948600000,
      "archivedAt": null
    }
  ],
  "count": 1
}

createdAt, updatedAt and archivedAt are Unix timestamps in milliseconds. endDate is included once the location has one.

Get location

Retrieve a single location by ID.

GET /business-entities/:businessEntityId/locations/:locationId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`locationId`	string	Location ID

Response

{
  "id": "cm3f7a9k20001l508x2d4q6ve",
  "name": "San Francisco office",
  "locationTypes": ["PRINCIPAL_PLACE_OF_BUSINESS"],
  "address": {
    "id": 88,
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "addressLine3": null,
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "startDate": "2020-01-15T00:00:00.000Z",
  "employeeCount": 25,
  "isVirtualAddress": false,
  "corporationId": 123,
  "createdAt": 1579082400000,
  "updatedAt": 1710948600000,
  "archivedAt": null
}

Create location

Add a new location to a business entity.

POST /business-entities/:businessEntityId/locations

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID

Request body

{
  "locationName": "San Francisco office",
  "locationTypes": ["PRINCIPAL_PLACE_OF_BUSINESS"],
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "startDate": "2020-01-15",
  "employeeCount": 25
}

Field	Type	Required	Description
`locationTypes`	string[]	Yes	One or more location types
`address`	object	Yes	The address, see Address fields
`locationName`	string	No	Display name for the location
`startDate`	string	No	ISO 8601 date the location became active
`endDate`	string	No	ISO 8601 date the location closed
`employeeCount`	number	No	Number of employees based at the location
`isVirtualAddress`	boolean	No	Whether the address is a virtual address

An entity can have only one REGISTERED_OFFICE location and one MAILING_ADDRESS location. Creating a second one returns 400 Bad Request. Response Returns 201 Created.

{
  "location": {
    "id": "cm3f7a9k20001l508x2d4q6ve"
  }
}

Update location

Update an existing location.

PATCH /business-entities/:businessEntityId/locations/:locationId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`locationId`	string	Location ID

Request body Takes the same fields as Create location, all optional. When you send address, include its required fields.

{
  "address": {
    "addressLine1": "456 Market Street",
    "addressLine2": "Floor 5",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "US"
  },
  "employeeCount": 30,
  "endDate": "2025-12-31"
}

An endDate before the location’s start date is rejected with 400 Bad Request. Response Returns 200 OK with no body.

Delete location

Remove a location from a business entity.

DELETE /business-entities/:businessEntityId/locations/:locationId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`locationId`	string	Location ID

Response Returns 204 No Content on success.

Location types

A single location can have multiple types (e.g., ["PRINCIPAL_PLACE_OF_BUSINESS", "REGISTERED_OFFICE"]):

Type	Description
`REGISTERED_OFFICE`	Official legal address on file with authorities. One per entity.
`MAILING_ADDRESS`	Correspondence address. One per entity.
`PRINCIPAL_PLACE_OF_BUSINESS`	Primary business operations location
`BRANCH_OFFICE`	Secondary office location
`RETAIL_LOCATION`	Customer-facing retail store
`FACTORY`	Manufacturing facility
`WAREHOUSE`	Inventory storage or distribution center
`NATURAL_RESOURCE_SITE`	Natural resource extraction site
`REPRESENTATIVE_OFFICE`	Representative office in a foreign jurisdiction
`CONSTRUCTION_SITE`	Active construction project site
`THIRD_PARTY_FULFILLMENT`	Third-party fulfillment center
`REMOTE_EMPLOYEE`	Location where remote employees work
`DEPENDENT_AGENT`	Agent who acts exclusively on behalf of the company
`INDEPENDENT_AGENT`	Agent who acts on behalf of multiple companies
`REGISTRATION`	Location linked to a tax registration
`OTHER`	Other location type

Address fields

The address object takes these fields:

Field	Type	Required	Description
`addressLine1`	string	Yes	Street address
`addressLine2`	string	No	Apartment, suite, unit, building, floor
`addressLine3`	string	No	Additional address line
`city`	string	No	City or locality
`state`	string	No	State or province code. Not every country has one.
`postalCode`	string	Yes	ZIP/postal code
`country`	string	Yes	ISO 3166-1 alpha-2 country code

Employee tracking

Track employee count at each location for:

Payroll tax threshold determination
Workers’ compensation requirements
Local tax obligations
Headcount reporting

Update employeeCount as staff levels change.

Registration threshold determination

Use startDate to track when physical presence began in a jurisdiction. This is critical for:

Indirect tax registration thresholds
Income tax registration thresholds
Payroll tax obligations
Registration requirements

Location sources

Locations you create through this API are recorded as entered in CommendaOS. The source of a location is not returned in location responses.

Time periods

Track location validity with startDate and endDate:

startDate: When the location became active (optional)
endDate: When the location was closed (optional, absent for active locations)

This enables historical tracking of where entities operated over time.

Business Entity API - Manage parent business entities
Registrations API - Registrations triggered by location-based thresholds

Get Started

Registrations

Registrations V2

Corporations

Tax Calculations

Transactions

Address Requirements

Registration Thresholds

Products

Customers

Exemption Certificates

Exemptions

Files

Credentials

Locations

Filings

Webhooks

Overview

Core endpoints

List locations

Get location

Create location

Update location

Delete location

Location types

Address fields

Employee tracking

Registration threshold determination

Location sources

Time periods

​Overview

​Core endpoints

​List locations

​Get location

​Create location

​Update location

​Delete location

​Location types

​Address fields

​Employee tracking

​Registration threshold determination

​Location sources

​Time periods

​Related resources

Overview

Core endpoints

List locations

Get location

Create location

Update location

Delete location

Location types

Address fields

Employee tracking

Registration threshold determination

Location sources

Time periods

Related resources