Address Groups

Address Groups are simple identifiers that allow multiple locations to be logically associated together. They consist only of an ID, name, and type.

Overview

Address groups are specifically designed for Multi-Dwelling Units (MDUs):

• Groups are just identifiers referenced by locations
• The group itself contains no address information
• Locations with the same addressGroupId can have different addresses

Get Address Group by ID

GET /address-groups/{id}
Authorization: Bearer {access_token}

Path Parameters

Parameter	Type	Description
id	UUID	Address group identifier

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Riverside Apartments",
  "type": "MDU_COMPLEX"
}

List Address Groups

GET /address-groups
Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Required	Description
type	String	No	Filter by group type
name	String	No	Filter by name (partial match)
limit	Integer	No	Maximum results to return (default: 100)
offset	Integer	No	Pagination offset (default: 0)

Response

{
  "addressGroups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Riverside Apartments",
      "type": "MDU_COMPLEX"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Sunset Towers",
      "type": "MDU_COMPLEX"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2
  }
}

Data Model

Field	Type	Description
id	UUID	Unique identifier for the address group
name	String	Human-readable name of the group
type	Enum	Currently only MDU_COMPLEX is valid

How It Works

Locations reference address groups through the addressGroupId field in their address object:

// Address Group
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Riverside Apartments",
  "type": "MDU_COMPLEX"
}

// Location with same address
{
  "id": "loc-001",
  "address": {
    "streetNumber": "500",
    "streetName": "RIVERSIDE",
    "streetType": "DRIVE",
    "subunitType": "APT",
    "subunitIdentifier": "101",
    "addressGroupId": "550e8400-e29b-41d4-a716-446655440001"
  }
}

// Location with different address in same group
{
  "id": "loc-002",
  "address": {
    "streetNumber": "502",
    "streetName": "RIVERSIDE",
    "streetType": "DRIVE",
    "subunitType": "APT",
    "subunitIdentifier": "201",
    "addressGroupId": "550e8400-e29b-41d4-a716-446655440001"
  }
}

Common Use Cases

• Apartment buildings and complexes
• Condominiums
• Mobile home parks
• Any residential property with multiple dwelling units

Error Responses

404 Not Found

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Address group not found"
  }
}

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid UUID format"
  }
}

Related Resources

• Locations Data Model - How locations reference address groups
• Location Groups - Groups for business/operational purposes