Managing Locations

Locations represent physical branches, stores, or facilities where sales transactions occur. You must create locations before syncing transaction data.

Endpoints

Method	Endpoint	Description
GET	/sales/v1/locations	Get all locations
POST	/sales/v1/locations	Create a new location

Get Locations

Retrieve a list of locations for your account.

Query Parameters

Parameter	Type	Required	Default	Description
locationIds	array	No	-	Filter by specific location IDs
locationNames	array	No	-	Filter by location names
isActive	boolean	No	-	Filter by active status
limit	integer	No	100	Results per page (1-1000)
offset	integer	No	0	Pagination offset

Example Request

curl --request GET \
  --url 'https://api.connecteam.com/sales/v1/locations?isActive=true&limit=50' \
  --header 'X-API-KEY: YOUR_API_KEY'

Example: Filter by IDs

curl --request GET \
  --url 'https://api.connecteam.com/sales/v1/locations?locationIds=123&locationIds=456' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "locations": [
      {
        "id": 123,
        "name": "Downtown Store",
        "isActive": true
      },
      {
        "id": 456,
        "name": "Mall Location",
        "isActive": true
      }
    ]
  },
  "paging": {
    "offset": 2
  }
}

Response Fields

Field	Type	Description
id	integer	Unique location identifier (use this for transactions)
name	string	Location display name
isActive	boolean	Whether the location is active

Create Location

Create a new location for syncing sales data.

Request Body

Field	Type	Required	Default	Description
name	string	Yes	-	Location name
isActive	boolean	No	true	Whether the location is active

Example Request

curl --request POST \
  --url https://api.connecteam.com/sales/v1/locations \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "name": "New Branch Location",
    "isActive": true
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": 789,
    "name": "New Branch Location",
    "isActive": true
  }
}

📝
Save the Location ID
Store the returned id - you'll need it when creating transactions for this location.

Best Practices

Location Naming

Use clear, consistent naming for locations:

Include city/region for multi-location businesses
Use unique identifiers if locations have similar names
Examples: "NYC - Times Square", "Store #123 - Downtown"

Managing Inactive Locations

Set isActive: false for locations that:

Are temporarily closed
No longer in operation
Should not receive new transactions

Inactive locations still retain their historical transaction data.

Error Responses

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

API Reference