Residents Endpoints - Happy Habitat

Overview

The Residents API allows you to manage resident profiles within the Happy Habitat system. All endpoints require authentication via bearer token with ADMIN_COMPANY or SYSTEM_ADMIN roles. Base URL: /api/Residents Authentication: Required (Bearer token) Required Roles: ADMIN_COMPANY, SYSTEM_ADMIN

Get All Residents

GET

/api/Residents

Retrieves all residents in the system. Supports optional pagination.

Query Parameters

page

integer

Page number (1-based). Must be greater than 0. Both page and pageSize must be provided together for pagination.

pageSize

integer

Number of items per page. Must be greater than 0. Both page and pageSize must be provided together for pagination.

Response

Without pagination - Returns an array of resident objects:

residents

array

Array of resident objects

Show Resident Object

string (GUID)

Unique identifier for the resident

userId

string (GUID)

Reference to the associated user account

communityId

string (GUID) | null

Reference to the community the resident belongs to (optional)

fullName

string

Full name of the resident

string | null

Email address of the resident

phone

string | null

Phone number of the resident

number

string | null

Unit or apartment number

address

string

Physical address of the resident

communityIds

array

Array of community IDs (for frontend compatibility, typically contains one element if communityId is set)

createdAt

string (ISO 8601)

Timestamp when the resident was created

With pagination - Returns a paginated result:

items

array

Array of resident objects (same structure as above)

totalCount

integer

Total number of residents across all pages

page

integer

Current page number (1-based)

pageSize

integer

Number of items per page

totalPages

integer

Total number of pages available

Example 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
}

Status Codes

200 OK - Residents retrieved successfully
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have required role

Get Resident by ID

GET

/api/Residents/{id}

Retrieves a specific resident by their unique identifier.

Path Parameters

string (GUID)

required

The unique identifier of the resident

Response

Returns a single resident object with the same structure as described in “Get All Residents”.

Example 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"
}

Status Codes

200 OK - Resident found and returned
404 Not Found - Resident with the specified ID does not exist
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have required role

Get Residents by Community

GET

/api/Residents/community/{communityId}

Retrieves all residents belonging to a specific community. Supports optional pagination.

Path Parameters

communityId

string (GUID)

required

The unique identifier of the community

Query Parameters

page

integer

Page number (1-based). Must be greater than 0. Both page and pageSize must be provided together for pagination.

pageSize

integer

Number of items per page. Must be greater than 0. Both page and pageSize must be provided together for pagination.

Response

Returns an array of residents (without pagination) or a paginated result (with pagination). Same structure as “Get All Residents” endpoint.

Example Request

curl -X GET "https://api.happyhabitat.com/api/Residents/community/7b34c123-4567-8901-a234-567890bcdefg?page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Status Codes

200 OK - Residents retrieved successfully
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have required role

Get Residents by Multiple Communities

GET

/api/Residents/by-communities

Retrieves residents from multiple communities. Returns unique residents by user (no duplicates). Supports optional pagination.

Query Parameters

communityIds

array of GUID

required

Array of community IDs. Pass multiple times: ?communityIds=guid1&communityIds=guid2. Returns empty result if not provided.

page

integer

Page number (1-based). Must be greater than 0. Both page and pageSize must be provided together for pagination.

pageSize

integer

Number of items per page. Must be greater than 0. Both page and pageSize must be provided together for pagination.

Response

Returns an array of unique residents (without pagination) or a paginated result (with pagination). Residents are deduplicated by user ID.

Example Request

curl -X GET "https://api.happyhabitat.com/api/Residents/by-communities?communityIds=7b34c123-4567-8901-a234-567890bcdefg&communityIds=9a45d234-5678-9012-b345-678901cdefgh&page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Status Codes

200 OK - Residents retrieved successfully
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have required role

Create Resident

POST

/api/Residents

Creates a new resident profile. The user ID must exist and not already have an associated resident.

Request Body

userId

string (GUID)

required

Reference to the user account. Must exist and not already have a resident profile.

communityId

string (GUID)

Reference to the community the resident belongs to (optional)

fullName

string

required

Full name of the resident. Maximum 200 characters.

string

Email address. Must be valid email format. Maximum 256 characters.

phone

string

Phone number. Maximum 50 characters.

number

string

Unit or apartment number. Maximum 50 characters.

address

string

required

Physical address. Maximum 500 characters.

Example Request

{
  "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"
}

Response

Returns the created resident object with a generated id field.

Status Codes

201 Created - Resident successfully created (includes Location header with the new resource URL)
400 Bad Request - Invalid input data, user doesn’t exist, user already has a resident profile, or invalid community
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have required role

Error Response

{
  "error": "Usuario no existe, ya tiene residente asociado o comunidad no válida."
}

Update Resident

PUT

/api/Residents/{id}

Updates an existing resident’s information. All fields in the request body are optional.

Path Parameters

string (GUID)

required

The unique identifier of the resident to update

Request Body

All fields are optional. Only include fields you want to update.

communityId

string (GUID)

Update community assignment. Must be valid if provided.

fullName

string

Update full name. Maximum 200 characters.

string

Update email address. Must be valid email format. Maximum 256 characters.

phone

string

Update phone number. Maximum 50 characters.

number

string

Update unit or apartment number. Maximum 50 characters.

address

string

Update physical address. Maximum 500 characters.

Example Request

{
  "fullName": "John Michael Doe",
  "email": "[email protected]",
  "phone": "+1-555-0124"
}

Response

Returns the updated resident object.

Example Response

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

Status Codes

200 OK - Resident successfully updated
404 Not Found - Resident with the specified ID does not exist
400 Bad Request - Invalid input data
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have required role

Delete Resident

DELETE

/api/Residents/{id}

Deletes a resident by their unique identifier.

Path Parameters

string (GUID)

required

The unique identifier of the resident to delete

Response

No content returned on successful deletion.

Status Codes

204 No Content - Resident successfully deleted
404 Not Found - Resident with the specified ID does not exist
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have required role

Example Request

curl -X DELETE "https://api.happyhabitat.com/api/Residents/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Responses

All endpoints may return the following error responses:

401 Unauthorized

The request lacks valid authentication credentials.

{
  "error": "Unauthorized"
}

403 Forbidden

The authenticated user does not have the required role (ADMIN_COMPANY or SYSTEM_ADMIN).

{
  "error": "Forbidden"
}

400 Bad Request

The request body is invalid or missing required fields.

{
  "errors": {
    "FullName": ["El nombre completo es obligatorio."],
    "Email": ["The Email field is not a valid e-mail address."]
  }
}

404 Not Found

The requested resource does not exist.

{
  "error": "Resident not found"
}

Best Practices

Pagination

Always use pagination for large datasets to improve performance
Recommended page size: 20-50 items
Both page and pageSize must be provided together and must be greater than 0

Creating Residents

Verify the user exists before creating a resident
Ensure the user doesn’t already have a resident profile
Validate email format and required fields before submission
CommunityId is optional but should be provided when known

Updating Residents

Only include fields you want to update in the request body
All fields in UpdateResidentDto are optional
Validate data before submission to avoid bad request errors

Multi-Community Queries

Use the /by-communities endpoint when managing multiple communities
Returns unique residents (deduplicated by user)
Ideal for management companies with multiple properties

Error Handling

Always check response status codes
Handle 404 errors gracefully (resident not found)
Parse validation errors from 400 responses to display user-friendly messages

Resident Visits - Manage visitor registrations for residents
Vehicles - Manage resident vehicles
Pets - Manage resident pets

Authentication

Residents

Communities

Amenities

Documents

Payments & Charges

Tickets

Vehicles & Pets

Visits

Announcements & Surveys

Error Handling

​Overview

​Get All Residents

​Query Parameters

​Response

​Example Response

​Status Codes

​Get Resident by ID

​Path Parameters

​Response

​Example Response

​Status Codes

​Get Residents by Community

​Path Parameters

​Query Parameters

​Response

​Example Request

​Status Codes

​Get Residents by Multiple Communities

​Query Parameters

​Response

​Example Request

​Status Codes

​Create Resident

​Request Body

​Example Request

​Response

​Status Codes

​Error Response

​Update Resident

​Path Parameters

​Request Body

​Example Request

​Response

​Example Response

​Status Codes

​Delete Resident

​Path Parameters

​Response

​Status Codes

​Example Request

​Error Responses

​401 Unauthorized

​403 Forbidden

​400 Bad Request

​404 Not Found

​Best Practices

​Pagination

​Creating Residents

​Updating Residents

​Multi-Community Queries

​Error Handling

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Get All Residents

Query Parameters

Response

Example Response

Status Codes

Get Resident by ID

Path Parameters

Response

Example Response

Status Codes

Get Residents by Community

Path Parameters

Query Parameters

Response

Example Request

Status Codes

Get Residents by Multiple Communities

Query Parameters

Response

Example Request

Status Codes

Create Resident

Request Body

Example Request

Response

Status Codes

Error Response

Update Resident

Path Parameters

Request Body

Example Request

Response

Example Response

Status Codes

Delete Resident

Path Parameters

Response

Status Codes

Example Request

Error Responses

401 Unauthorized

403 Forbidden

400 Bad Request

404 Not Found

Best Practices

Pagination

Creating Residents

Updating Residents

Multi-Community Queries

Error Handling

Related Endpoints