vsmsconnect — API — locations

← all endpoints

GET/api/v1/businesses/:businessId/locations auth: jwt (administrator | update_taxcore_credentials)

List all Locations for a business.

handlers: LocationsController.list

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID. Administrator bypass via requireBusinessAccess.

Outputs

200
APIResponseDataList<LocationDTO>
All Locations for the business.
403
APIError
USER_FORBIDDEN — insufficient role or businessId mismatch.
POST/api/v1/businesses/:businessId/locations auth: jwt (administrator | update_taxcore_credentials)

Create a new Location for the business. locationType defaults server-side; isDefault optionally promotes this Location to the business's default (existing default cleared atomically).

handlers: LocationsController.create

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
name body
string		yes—Display name (min 1 char).
street body
string | null		no—Street address (min 1 char when set).
city body
string | null		no—City (min 1 char when set).
administrativeUnit body
string | null		no—State / province / region (min 1 char when set).
country body
string | null		no—ISO 3166-1 alpha-2 code (e.g. 'VU').
locationType body
'Headquarters' | 'BranchOffice'		no—Defaults to BranchOffice in the repository when omitted.
isDefault body
boolean		no—Promote this Location to the business default.

Outputs

201
APIResponseDataObject<LocationDTO>
Newly created Location.
403
APIError
USER_FORBIDDEN — insufficient role or businessId mismatch.
422
APIError
VALIDATION_ERROR — schema violation.
GET/api/v1/businesses/:businessId/locations/:locationId auth: jwt (administrator | update_taxcore_credentials)

Fetch a single Location scoped to the business.

handlers: LocationsController.getById

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Target Location UUID.

Outputs

200
APIResponseDataObject<LocationDTO>
The Location.
404
APIError
LOCATION_NOT_FOUND.
PATCH/api/v1/businesses/:businessId/locations/:locationId auth: jwt (administrator | update_taxcore_credentials)

Partial update of a Location. isDefault=true is routed through the dedicated setDefault path so the previous default is cleared atomically. status='inactive' soft-disables the Location.

handlers: LocationsController.update

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Target Location UUID.
name body
string		no—Display name (min 1 char).
street body
string | null		no—Street address. Null clears.
city body
string | null		no—City. Null clears.
administrativeUnit body
string | null		no—Administrative unit. Null clears.
country body
string | null		no—ISO 3166-1 alpha-2 code, or null.
locationType body
'Headquarters' | 'BranchOffice'		no—Updated location type.
status body
'active' | 'inactive'		no—Soft-enable/disable.
isDefault body
boolean		no—Promote this Location to the business default (atomic swap).

Outputs

200
APIResponseDataObject<LocationDTO>
Updated Location.
404
APIError
LOCATION_NOT_FOUND.
422
APIError
VALIDATION_ERROR — empty body or schema violation.
DELETE/api/v1/businesses/:businessId/locations/:locationId auth: jwt (administrator | update_taxcore_credentials)

Hard-delete a Location (or soft-delete depending on repository impl — see ILocationRepository.remove).

handlers: LocationsController.remove

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId path
uuid		yes—Target Location UUID.

Outputs

204
void
Location removed.
404
APIError
LOCATION_NOT_FOUND.