---
updatedAt: 2026-01-28T13:49:25.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# 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

```bash
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

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

### Response

```json
{
  "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

```bash
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

```json
{
  "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

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

***

[API Reference](https://developer.connecteam.com/reference/)