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-entity/:businessEntityId/locations

Path parameters

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

Response

{
  "locations": [
    {
      "id": "loc_abc123",
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 100",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US",
      "locationType": ["REGISTERED_OFFICE", "OPERATING"],
      "startDate": "2020-01-15",
      "endDate": null,
      "employeeCount": 25,
      "source": "COMMENDA",
      "sourceId": null
    }
  ],
  "count": 1
}

Get location

Retrieve a single location by ID.

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

Path parameters

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

Response

{
  "id": "loc_abc123",
  "addressLine1": "123 Main Street",
  "addressLine2": "Suite 100",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94105",
  "country": "US",
  "locationType": ["REGISTERED_OFFICE", "OPERATING"],
  "startDate": "2020-01-15",
  "endDate": null,
  "employeeCount": 25,
  "source": "COMMENDA",
  "sourceId": null
}

Create location

Add a new location to a business entity.

POST /business-entity/:businessEntityId/locations

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID

Request body

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

Response

{
  "location": {
    "id": "loc_abc123"
  }
}

Update location

Update an existing location.

POST /business-entity/:businessEntityId/locations/:locationId

Path parameters

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

Request body

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

Response Returns 200 OK on success.

Delete location

Remove a location from a business entity.

DELETE /business-entity/: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:

Type	Description	Use case
`REGISTERED_OFFICE`	Official legal address on file with authorities	Required for corporate filings
`OPERATING`	Primary business operations location	Main office or headquarters
`MAILING`	Correspondence address	Where mail is received
`HEADQUARTERS`	Main administrative office	Corporate HQ
`POINT_OF_SALE`	Retail or customer-facing location	Stores, showrooms
`WAREHOUSE`	Inventory storage facility	Distribution centers
`BRANCH`	Secondary office location	Regional offices
`EMPLOYEE_WORK_LOCATION`	Where staff are based	Remote offices, coworking spaces

Address fields

Field	Type	Required	Description
`addressLine1`	string	Yes	Street address
`addressLine2`	string	No	Apartment, suite, unit, building, floor
`city`	string	Yes	City or locality
`state`	string	Conditional	State/province (required for US, Canada, India, Australia)
`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 can be created from multiple sources:

Source	Description
`COMMENDA`	Manually entered in CommendaOS
`GUSTO`	Synced from Gusto payroll
`RIPPLING`	Synced from Rippling HRIS
`JUSTWORKS`	Synced from Justworks
`DEEL`	Synced from Deel

External locations include a sourceId for reference back to the originating system.

Time periods

Track location validity with startDate and endDate:

startDate: When the location became active (required)
endDate: When the location was closed (optional, null 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

Overview

Customer setup

Partner Incorporation API

Commenda OS Partner API

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