# Create Location Group

`POST /api/v1/location-groups`

Creates a new LocationGroup object. Requires the `create` ability.

## Request body

```json
{
    "name": "Austin Metro",
    "external_id": "AUS-METRO"
}
```

## Example request

```bash
curl -X POST "https://app.franchisesee.com/api/v1/location-groups" \
  -H "Authorization: Bearer $FRANCHISESEE_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Austin Metro",
    "external_id": "AUS-METRO"
}'
```

## Responses

### 201 A single LocationGroup.

```json
{
    "data": {
        "id": "a3c5e7f9-2b4d-4f6a-8c1e-3d5f7a9b1c20",
        "name": "Austin Metro",
        "external_id": "AUS-METRO",
        "created_at": "2025-03-14T15:22:08.000000Z",
        "updated_at": "2026-10-02T09:41:55.000000Z",
        "locations": [
            {
                "id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
                "external_id": "STR-1042",
                "name": "Downtown Austin",
                "address": "401 Congress Ave",
                "city": "Austin",
                "region": "TX",
                "postal_code": "78701",
                "country": "US",
                "timezone": "America/Chicago",
                "timezone_source": "pos",
                "is_private": false,
                "is_corporate": false,
                "is_active": true,
                "activation_status": "active",
                "deactivated_at": null,
                "is_deletable": false,
                "deletable_on": null,
                "district_id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
                "district_id_2": "c7e9a2d4-1b3f-4e8a-9c6d-5f2e8b1a7d30",
                "location_category_id": "5d8e2f1a-6c4b-4a9e-8f3d-2b7c1e9a4d60",
                "created_at": "2025-03-14T15:22:08.000000Z",
                "updated_at": "2026-10-02T09:41:55.000000Z",
                "datasource_settings": {
                    "qu": {
                        "location_id": 12345
                    },
                    "brink": {
                        "api_key_set": true
                    }
                },
                "district": {
                    "id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
                    "name": "Central Texas",
                    "external_id": "CTX",
                    "district_group_id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                    "created_at": "2025-03-14T15:22:08.000000Z",
                    "updated_at": "2026-10-02T09:41:55.000000Z",
                    "districtGroup": {
                        "id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                        "name": "Region",
                        "index": 1,
                        "created_at": "2025-03-14T15:22:08.000000Z",
                        "updated_at": "2026-10-02T09:41:55.000000Z"
                    }
                },
                "district2": {
                    "id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
                    "name": "Central Texas",
                    "external_id": "CTX",
                    "district_group_id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                    "created_at": "2025-03-14T15:22:08.000000Z",
                    "updated_at": "2026-10-02T09:41:55.000000Z",
                    "districtGroup": {
                        "id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                        "name": "Region",
                        "index": 1,
                        "created_at": "2025-03-14T15:22:08.000000Z",
                        "updated_at": "2026-10-02T09:41:55.000000Z"
                    }
                },
                "locationCategory": {
                    "id": "5d8e2f1a-6c4b-4a9e-8f3d-2b7c1e9a4d60",
                    "name": "Inline",
                    "external_id": "INLINE",
                    "location_category_group_id": "f2b6d8a1-4c3e-4e7b-a5d9-1c8e3f6b2a40",
                    "sort_order": 1,
                    "created_at": "2025-03-14T15:22:08.000000Z",
                    "updated_at": "2026-10-02T09:41:55.000000Z",
                    "locationCategoryGroup": {
                        "id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                        "name": "Region",
                        "index": 1,
                        "created_at": "2025-03-14T15:22:08.000000Z",
                        "updated_at": "2026-10-02T09:41:55.000000Z"
                    }
                },
                "locationGroups": [
                    {
                        "id": "a3c5e7f9-2b4d-4f6a-8c1e-3d5f7a9b1c20",
                        "name": "Austin Metro",
                        "external_id": "AUS-METRO",
                        "created_at": "2025-03-14T15:22:08.000000Z",
                        "updated_at": "2026-10-02T09:41:55.000000Z",
                        "locations": []
                    }
                ]
            }
        ]
    }
}
```

### 401 Authentication failed or missing.

```json
{
    "message": "Unauthenticated."
}
```

### 403 The token lacks the required ability or the caller is not permitted.

```json
{
    "message": "This API token does not have the 'create' ability."
}
```

### 422 Validation failed.

```json
{
    "message": "The name field is required.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}
```
