Skip to main content

Create a new tenant location record

POST 
/locations

Creates a composite location record comprising a core location, a group location, and a tenant-group-location entry, all scoped to the tenant identified by the required tenant-id header.

When to use: Use when adding a new physical or service location for a tenant. To update an existing location's fields and sub-entities use PUT /locations/{id} (single record) or PUT /locations/update (batch update with specialty management).

Preconditions: The tenant-id header is required. The request body must include a groupId; the request will fail with 400 if groupId is absent. Each of the three nested sub-documents (locationData, groupLocationData, tenantGroupLocationData) is independently validated against a JSON schema — validation failures return 400.

Idempotency: A core location with the same name and address may match an existing record via a crosswalk hash and be reused rather than duplicated; a new TenantGroupLocation entry is still created in this case. Every upsert — including this hash-matched reuse — publishes an MDM change event and an audit event, so this is not a side-effect-free operation even when no new CoreLocation row is created.

Request​

Responses​

A LocationResponse object containing the newly created location's id (= crosswalkId), crosswalkId, tenantId, billing/effective/termination dates, and a partial generalInfo (locationName, suppressSiteFromDirectory). Note: entityAddressId and tenantGroupLocationId are not populated on this response — use GET /locations/{id} after creation if those fields are needed.