Companies and locations

A company represents a customer and belongs to a workspace. A location is a business site that belongs to a company. Everything else (profile data, subscriptions, reviews) hangs off the location.

Create a company

Goal: register a new customer in your workspace.

Step	Endpoint
Create the company	POST Company with the workspace ID in the path
Read it back	GET Company

Only name is required. Set externalId to your own customer ID so you can map records later.

POST /company/{workspaceId}

{
  "name": "Muster GmbH",
  "shortName": "muster",
  "legalType": "GmbH",
  "externalId": "CRM-4711"
}

The response contains the new company ID in value.

Create a location

Goal: add a business site to a company.

POST Location takes the company ID in the path. Required fields are name, categories, address and mainPhone.

Field	Notes
categories	Objects with the category key. Look them up with GET Categories or search by term
address	street, city and country are required. house, postCode, state, additive, subLocality are optional
mainPhone	phone and tracked are required. Any common phone format is accepted. Without an international country code, Germany is assumed

POST /location/{companyId}

{
  "name": "Muster GmbH Nürnberg",
  "categories": [{ "key": 1234, "value": "Bakery" }],
  "address": {
    "street": "Hauptstraße",
    "house": "1",
    "postCode": "90402",
    "city": "Nürnberg",
    "country": "DE"
  },
  "mainPhone": { "phone": "+49 911 123456", "tracked": false }
}

tip

Use GET Categories with the language parameter to show localized category names. Without a translation the German name is returned.

Find companies and locations

Task	Endpoint
List companies of a workspace (filter by name, licence, status)	GET Company list
List locations of a company	GET Location list
Read basic location data	GET Location basic
See products connected to a location	GET Location products

Update data

Task	Endpoint
Update a company	PUT Company (name required)
Update basic location data (name, categories, email, closed flag, current offer)	PUT Location basic (name and categories required)
Update address	PUT Address
Update several locations at once	PUT Location bulk

Further profile data such as phones, opening hours and media is covered in Location profile data.

Delete data

Cancel subscriptions first, then delete bottom-up.

1. Cancel subscriptions of the location.
2. DELETE Location.
3. DELETE Company removes the company with all its locations. It only works if no active subscriptions exist.

warning

Deleting a company or location is final. Confirm with your customer before you call these endpoints.

Common problems

Symptom	Cause and fix
Validation error on categories	Use a category key returned by the meta endpoints
Validation error on mainPhone	Check that the number is a valid phone number and that tracked is set
Company cannot be deleted	Active subscriptions still exist. Cancel them first