Residents Overview

Introduction

The Residents API provides comprehensive management of resident profiles within the Happy Habitat system. Residents are users who belong to communities and can have associated vehicles, pets, visits, tickets, charges, and payments.

Resident Entity Structure

The Resident entity contains the following core properties:

Core Properties

Property	Type	Description
`Id`	`Guid`	Unique identifier for the resident
`UserId`	`Guid`	Reference to the associated user account (required)
`CommunityId`	`Guid?`	Reference to the community (optional)
`FullName`	`string`	Full name of the resident (required, max 200 chars)
`Email`	`string?`	Email address (optional, max 256 chars)
`Phone`	`string?`	Phone number (optional, max 50 chars)
`Number`	`string?`	Unit/apartment number (optional, max 50 chars)
`Address`	`string`	Physical address (required, max 500 chars)
`CreatedAt`	`string`	Timestamp of resident creation

Relationships

Residents have the following relationships with other entities:

User: Each resident is associated with exactly one user account
Community: A resident can belong to one community (optional)
Vehicles: Collection of vehicles owned by the resident
Pets: Collection of pets owned by the resident
Visits: Collection of visitor records (ResidentVisit)
Tickets: Collection of support tickets created by the resident
Configurations: Resident-specific configuration settings
Survey Responses: Responses to community surveys (RespuestasEncuestas)
Comments: Comments made by the resident (Comentarios)
Charges: Financial charges assigned to the resident (CargosResidente)
Payments: Payment records for the resident (PagosResidente)

Key Features

User-Resident Association

Each resident must be linked to a valid user account
A user can only have one resident profile associated with it
The UserId must exist before creating a resident

Community Management

Residents can be assigned to communities
Community assignment is optional (CommunityId can be null)
Support for querying residents by single or multiple communities

Pagination Support

All list endpoints support optional pagination
Query parameters: page (1-based) and pageSize
Returns paginated results with total count and total pages

Use Cases

Resident Registration

Create new resident profiles for users who have registered in the system and need to be associated with a community.

Community Directory

Retrieve all residents within a specific community to display a directory or contact list.

Multi-Community Management

For management companies handling multiple communities, retrieve residents across several communities efficiently.

Profile Updates

Update resident information such as contact details, address, or community assignment.

Resident Lifecycle Management

Manage the complete lifecycle from resident onboarding to offboarding (deletion).

Authentication & Authorization

All Residents API endpoints require authentication and are restricted to the following roles:

ADMIN_COMPANY: Company administrators
SYSTEM_ADMIN: System-level administrators

Ensure your API requests include a valid JWT token with one of these roles.

Response Structure

Single Resident Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "userId": "8e12d345-9876-4abc-b123-456789abcdef",
  "communityId": "7b34c123-4567-8901-a234-567890bcdefg",
  "fullName": "John Doe",
  "email": "[email protected]",
  "phone": "+1-555-0123",
  "number": "101A",
  "address": "123 Main Street, Apt 101A",
  "communityIds": ["7b34c123-4567-8901-a234-567890bcdefg"],
  "createdAt": "2024-01-15T10:30:00Z"
}

Paginated Response

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "userId": "8e12d345-9876-4abc-b123-456789abcdef",
      "communityId": "7b34c123-4567-8901-a234-567890bcdefg",
      "fullName": "John Doe",
      "email": "[email protected]",
      "phone": "+1-555-0123",
      "number": "101A",
      "address": "123 Main Street, Apt 101A",
      "communityIds": ["7b34c123-4567-8901-a234-567890bcdefg"],
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8
}

Next Steps

Explore the Residents Endpoints documentation for detailed information about each API endpoint, including request parameters, request bodies, and response examples.

Authentication

Residents

Communities

Amenities

Documents

Payments & Charges

Tickets

Vehicles & Pets

Visits

Announcements & Surveys

Error Handling

Introduction

Resident Entity Structure

Core Properties

Relationships

Key Features

User-Resident Association

Community Management

Use Cases

Resident Registration

Community Directory

Multi-Community Management

Profile Updates

Resident Lifecycle Management

Authentication & Authorization

Response Structure

Single Resident Response

Paginated Response

Next Steps

Build docs developers (and LLMs) love

Authentication

Residents

Communities

Amenities

Documents

Payments & Charges

Tickets

Vehicles & Pets

Visits

Announcements & Surveys

Error Handling

​Introduction

​Resident Entity Structure

​Core Properties

​Relationships

​Key Features

​User-Resident Association

​Community Management

​Pagination Support

​Use Cases

​Resident Registration

​Community Directory

​Multi-Community Management

​Profile Updates

​Resident Lifecycle Management

​Authentication & Authorization

​Response Structure

​Single Resident Response

​Paginated Response

​Next Steps

Build docs developers (and LLMs) love

Introduction

Resident Entity Structure

Core Properties

Relationships

Key Features

User-Resident Association

Community Management

Pagination Support

Use Cases

Resident Registration

Community Directory

Multi-Community Management

Profile Updates

Resident Lifecycle Management

Authentication & Authorization

Response Structure

Single Resident Response

Paginated Response

Next Steps