Skip to main content

​
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 nexus determination, compliance tracking, and employee management.

​
Core endpoints

​
List locations

Get all locations for a business entity. 
GET /business-entity/:businessEntityId/locations
Path parameters
ParameterTypeDescription
businessEntityIdintegerUnique 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
ParameterTypeDescription
businessEntityIdintegerBusiness entity ID
locationIdstringLocation 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
ParameterTypeDescription
businessEntityIdintegerBusiness 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
ParameterTypeDescription
businessEntityIdintegerBusiness entity ID
locationIdstringLocation 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
ParameterTypeDescription
businessEntityIdintegerBusiness entity ID
locationIdstringLocation ID
Response Returns 204 No Content on success.

​
Location types

A single location can have multiple types:
TypeDescriptionUse case
REGISTERED_OFFICEOfficial legal address on file with authoritiesRequired for corporate filings
OPERATINGPrimary business operations locationMain office or headquarters
MAILINGCorrespondence addressWhere mail is received
HEADQUARTERSMain administrative officeCorporate HQ
POINT_OF_SALERetail or customer-facing locationStores, showrooms
WAREHOUSEInventory storage facilityDistribution centers
BRANCHSecondary office locationRegional offices
EMPLOYEE_WORK_LOCATIONWhere staff are basedRemote offices, coworking spaces

​
Address fields

FieldTypeRequiredDescription
addressLine1stringYesStreet address
addressLine2stringNoApartment, suite, unit, building, floor
citystringYesCity or locality
statestringConditionalState/province (required for US, Canada, India, Australia)
postalCodestringYesZIP/postal code
countrystringYesISO 3166-1 alpha-2 country code

​
Employee tracking

Track employee count at each location for:
  • Payroll tax nexus determination
  • Workers’ compensation requirements
  • Local tax obligations
  • Headcount reporting
Update employeeCount as staff levels change.

​
Nexus determination

Use startDate to track when physical presence began in a jurisdiction. This is critical for:
  • Sales tax nexus
  • Income tax nexus
  • Payroll tax obligations
  • Registration requirements

​
Location sources

Locations can be created from multiple sources:
SourceDescription
COMMENDAManually entered in CommendaOS
GUSTOSynced from Gusto payroll
RIPPLINGSynced from Rippling HRIS
JUSTWORKSSynced from Justworks
DEELSynced 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.