# Locations

The Location object represents a physical location (office, warehouse, etc.) for your company.

## The Location object

| Attribute | Type | Description |
|-----------|------|-------------|
| `uuid` | string | Unique identifier for the location |
| `name` | string | Location name |
| `location_code` | string \| null | Optional location code |
| `address1` | string | First line of address |
| `address2` | string \| null | Second line of address |
| `city` | string | City |
| `state` | string | 2-letter US state code |
| `zip` | string | ZIP code (5 or 9 digits) |
| `phone` | string \| null | Phone number (xxx-xxx-xxxx format) |
| `timezone` | string | Timezone (default: 'America/New_York') |
| `business_hours` | JSONB \| null | Business hours configuration |
| `default_tax_rules` | JSONB \| null | Default tax rules |
| `service_types_offered` | JSONB \| null | Service types offered at this location |
| `default_pricing_set_uuid` | UUID \| null | Default pricing set UUID |
| `is_primary` | boolean | Whether this is the primary location |
| `is_active` | boolean | Whether the location is active |
| `created_at` | string | ISO timestamp of creation |
| `updated_at` | string | ISO timestamp of last update |
| `deleted_at` | string \| null | ISO timestamp of soft deletion (null if not deleted) |

## Endpoints

### List locations

```bash
GET /api/v1/locations
```

Returns a paginated list of locations for your company.

**Query Parameters:**
- `include_deleted` (boolean, default: false) - Include soft-deleted locations
- `page` (number, default: 1) - Page number
- `limit` (number, default: 50, max: 100) - Items per page

**Request:**

```bash
curl https://customtradescrm.com/api/v1/locations \
  -H "Authorization: Bearer ctc_live_..."
```

**Response:**

```json
{
  "success": true,
  "data": {
    "locations": [
      {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Main Office",
        "address1": "123 Main St",
        "city": "Seattle",
        "state": "WA",
        "zip": "98101",
        "is_primary": true,
        "is_active": true
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}
```

### Get a location

```bash
GET /api/v1/locations/{uuid}
```

Returns a specific location by UUID.

**Request:**

```bash
curl https://customtradescrm.com/api/v1/locations/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."
```

### Create a location

```bash
POST /api/v1/locations
```

Creates a new location.

**Request Body:**

```json
{
  "name": "Main Office",
  "address1": "123 Main St",
  "city": "Seattle",
  "state": "WA",
  "zip": "98101",
  "phone": "206-555-1234",
  "is_primary": false
}
```

**Required Fields:**
- `name` - Location name
- `address1` - First line of address
- `city` - City
- `state` - 2-letter US state code (e.g., "WA", "CA")
- `zip` - ZIP code (5 digits or 5+4 format)

**Optional Fields:**
- `location_code` - Location code
- `address2` - Second line of address
- `phone` - Phone number (xxx-xxx-xxxx format)
- `timezone` - Timezone (default: 'America/New_York')
- `business_hours` - JSONB object
- `default_tax_rules` - JSONB object
- `service_types_offered` - JSONB object
- `default_pricing_set_uuid` - UUID
- `is_primary` - boolean (default: false)

**Response:**

```json
{
  "success": true,
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Main Office",
    "address1": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "zip": "98101",
    "is_primary": false,
    "is_active": true,
    "created_at": "2025-01-15T10:00:00Z"
  }
}
```

### Update a location

```bash
PUT /api/v1/locations/{uuid}
PATCH /api/v1/locations/{uuid}
```

Updates a location. All fields are optional (partial update).

**Request Body:**

```json
{
  "name": "Updated Office Name",
  "phone": "206-555-5678"
}
```

### Delete a location

```bash
DELETE /api/v1/locations/{uuid}
```

Soft deletes a location (sets `deleted_at` timestamp). Cannot delete primary location (`is_primary = true`).

**Request:**

```bash
curl -X DELETE https://customtradescrm.com/api/v1/locations/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."
```

**Response:**

```json
{
  "success": true,
  "data": {
    "message": "Location deleted successfully"
  }
}
```

**Status Codes:**
- `200` - Success
- `400` - Validation error or cannot delete primary location
- `401` - Unauthorized (invalid API key)
- `403` - Forbidden (add-on required, IP restriction, or usage limit exceeded)
- `404` - Location not found
- `500` - Server error